fb1182e305
This MR removes the slab-based implementation of event-listener, leaving only the intrusive linked list backend. The core reasoning for this is because the slab-based backend is sloppy and barely tested in production. It's a potential landmine for anyone using any of smol's synchronization primitives. It is replaced by having a spinlock synchronization option in "intrusive.rs". This spinlock is dangerous and can cause issues when threads are pre-empted. This possibility is considered less dangerous than the current slab-based backend. In a future breaking change, we should remove this spinlock and make compiling without either the `std` feature or the `critical-section` feature a compile error. This MR has two other benefits. First, it reduces the number of lines of code in event-listener from 3.8kLOC to 2.3kLOC, for a net reduction of 1.5kLOC, or around 40% of the previous code. Secondly, it removes the concurrent-queue dependency, making it so event-listener build substantially faster. Closes: #109 Signed-off-by: John Nunley <dev@notgull.net>
106 lines
3.4 KiB
Markdown
106 lines
3.4 KiB
Markdown
# event-listener
|
|
|
|
[](
|
|
https://github.com/smol-rs/event-listener/actions)
|
|
[](
|
|
https://github.com/smol-rs/event-listener)
|
|
[](
|
|
https://crates.io/crates/event-listener)
|
|
[](
|
|
https://docs.rs/event-listener)
|
|
|
|
Notify async tasks or threads.
|
|
|
|
This is a synchronization primitive similar to [eventcounts] invented by Dmitry Vyukov.
|
|
|
|
You can use this crate to turn non-blocking data structures into async or blocking data
|
|
structures. See a [simple mutex] implementation that exposes an async and a blocking interface
|
|
for acquiring locks.
|
|
|
|
[eventcounts]: https://www.1024cores.net/home/lock-free-algorithms/eventcounts
|
|
[simple mutex]: ./examples/mutex.rs
|
|
|
|
## Examples
|
|
|
|
Wait until another thread sets a boolean flag:
|
|
|
|
```rust
|
|
use std::sync::atomic::{AtomicBool, Ordering};
|
|
use std::sync::Arc;
|
|
use std::thread;
|
|
use std::time::Duration;
|
|
use event_listener::Event;
|
|
|
|
let flag = Arc::new(AtomicBool::new(false));
|
|
let event = Arc::new(Event::new());
|
|
|
|
// Spawn a thread that will set the flag after 1 second.
|
|
thread::spawn({
|
|
let flag = flag.clone();
|
|
let event = event.clone();
|
|
move || {
|
|
// Wait for a second.
|
|
thread::sleep(Duration::from_secs(1));
|
|
|
|
// Set the flag.
|
|
flag.store(true, Ordering::SeqCst);
|
|
|
|
// Notify all listeners that the flag has been set.
|
|
event.notify(usize::MAX);
|
|
}
|
|
});
|
|
|
|
// Wait until the flag is set.
|
|
loop {
|
|
// Check the flag.
|
|
if flag.load(Ordering::SeqCst) {
|
|
break;
|
|
}
|
|
|
|
// Start listening for events.
|
|
let listener = event.listen();
|
|
|
|
// Check the flag again after creating the listener.
|
|
if flag.load(Ordering::SeqCst) {
|
|
break;
|
|
}
|
|
|
|
// Wait for a notification and continue the loop.
|
|
listener.wait();
|
|
}
|
|
```
|
|
|
|
## Features
|
|
|
|
- The `std` feature (enabled by default) enables the use of the Rust standard library. Disable it
|
|
for `no_std` support.
|
|
|
|
- The `critical-section` feature enables usage of the [`critical-section`] crate to enable
|
|
a more efficient implementation of `event-listener` for `no_std` platforms.
|
|
|
|
- The `portable-atomic` feature enables the use of the [`portable-atomic`] crate to provide
|
|
atomic operations on platforms that don't support them.
|
|
|
|
In production environments, at least one of `std` or `critical-section` should be
|
|
enabled. This ensures that the internal locking mechanism has a critical section of some
|
|
kind to fall back on. Otherwise, it falls back to a spinlock implementation. This
|
|
implementation is [dangerous] to rely on.
|
|
|
|
[`critical-section`]: https://crates.io/crates/critical-section
|
|
[`portable-atomic`]: https://crates.io/crates/portable-atomic
|
|
[dangerous]: https://matklad.github.io/2020/01/02/spinlocks-considered-harmful.html
|
|
|
|
## License
|
|
|
|
Licensed under either of
|
|
|
|
* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
|
|
* MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT)
|
|
|
|
at your option.
|
|
|
|
#### Contribution
|
|
|
|
Unless you explicitly state otherwise, any contribution intentionally submitted
|
|
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
|
|
dual licensed as above, without any additional terms or conditions.
|