event-listener 5.4.2

Notify async tasks or threads
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

# event-listener

[![Build](https://github.com/smol-rs/event-listener/workflows/CI/badge.svg)](
https://github.com/smol-rs/event-listener/actions)
[![License](https://img.shields.io/badge/license-Apache--2.0_OR_MIT-blue.svg)](
https://github.com/smol-rs/event-listener)
[![Cargo](https://img.shields.io/crates/v/event-listener.svg)](
https://crates.io/crates/event-listener)
[![Documentation](https://docs.rs/event-listener/badge.svg)](
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.