Struct event_listener::Event
source · [−]pub struct Event { /* private fields */ }
Expand description
A synchronization primitive for notifying async tasks and threads.
Listeners can be registered using Event::listen()
. There are two ways to notify listeners:
Event::notify()
notifies a number of listeners.Event::notify_additional()
notifies a number of previously unnotified listeners.
If there are no active listeners at the time a notification is sent, it simply gets lost.
There are two ways for a listener to wait for a notification:
- In an asynchronous manner using
.await
. - In a blocking manner by calling
EventListener::wait()
on it.
If a notified listener is dropped without receiving a notification, dropping will notify another active listener. Whether one additional listener will be notified depends on what kind of notification was delivered.
Listeners are registered and notified in the first-in first-out fashion, ensuring fairness.
Implementations
sourceimpl Event
impl Event
sourcepub fn listen(&self) -> EventListenerⓘNotable traits for EventListenerimpl Future for EventListener type Output = ();
pub fn listen(&self) -> EventListenerⓘNotable traits for EventListenerimpl Future for EventListener type Output = ();
Returns a guard listening for a notification.
This method emits a SeqCst
fence after registering a listener.
Examples
use event_listener::Event;
let event = Event::new();
let listener = event.listen();
sourcepub fn notify(&self, n: usize)
pub fn notify(&self, n: usize)
Notifies a number of active listeners.
The number is allowed to be zero or exceed the current number of listeners.
In contrast to Event::notify_additional()
, this method only makes sure at least n
listeners among the active ones are notified.
This method emits a SeqCst
fence before notifying listeners.
Examples
use event_listener::Event;
let event = Event::new();
// This notification gets lost because there are no listeners.
event.notify(1);
let listener1 = event.listen();
let listener2 = event.listen();
let listener3 = event.listen();
// Notifies two listeners.
//
// Listener queueing is fair, which means `listener1` and `listener2`
// get notified here since they start listening before `listener3`.
event.notify(2);
sourcepub fn notify_relaxed(&self, n: usize)
pub fn notify_relaxed(&self, n: usize)
Notifies a number of active listeners without emitting a SeqCst
fence.
The number is allowed to be zero or exceed the current number of listeners.
In contrast to Event::notify_additional()
, this method only makes sure at least n
listeners among the active ones are notified.
Unlike Event::notify()
, this method does not emit a SeqCst
fence.
Examples
use event_listener::Event;
use std::sync::atomic::{self, Ordering};
let event = Event::new();
// This notification gets lost because there are no listeners.
event.notify(1);
let listener1 = event.listen();
let listener2 = event.listen();
let listener3 = event.listen();
// We should emit a fence manually when using relaxed notifications.
atomic::fence(Ordering::SeqCst);
// Notifies two listeners.
//
// Listener queueing is fair, which means `listener1` and `listener2`
// get notified here since they start listening before `listener3`.
event.notify(2);
sourcepub fn notify_additional(&self, n: usize)
pub fn notify_additional(&self, n: usize)
Notifies a number of active and still unnotified listeners.
The number is allowed to be zero or exceed the current number of listeners.
In contrast to Event::notify()
, this method will notify n
additional listeners that
were previously unnotified.
This method emits a SeqCst
fence before notifying listeners.
Examples
use event_listener::Event;
let event = Event::new();
// This notification gets lost because there are no listeners.
event.notify(1);
let listener1 = event.listen();
let listener2 = event.listen();
let listener3 = event.listen();
// Notifies two listeners.
//
// Listener queueing is fair, which means `listener1` and `listener2`
// get notified here since they start listening before `listener3`.
event.notify_additional(1);
event.notify_additional(1);
sourcepub fn notify_additional_relaxed(&self, n: usize)
pub fn notify_additional_relaxed(&self, n: usize)
Notifies a number of active and still unnotified listeners without emitting a SeqCst
fence.
The number is allowed to be zero or exceed the current number of listeners.
In contrast to Event::notify()
, this method will notify n
additional listeners that
were previously unnotified.
Unlike Event::notify_additional()
, this method does not emit a SeqCst
fence.
Examples
use event_listener::Event;
use std::sync::atomic::{self, Ordering};
let event = Event::new();
// This notification gets lost because there are no listeners.
event.notify(1);
let listener1 = event.listen();
let listener2 = event.listen();
let listener3 = event.listen();
// We should emit a fence manually when using relaxed notifications.
atomic::fence(Ordering::SeqCst);
// Notifies two listeners.
//
// Listener queueing is fair, which means `listener1` and `listener2`
// get notified here since they start listening before `listener3`.
event.notify_additional_relaxed(1);
event.notify_additional_relaxed(1);
Trait Implementations
impl RefUnwindSafe for Event
impl Send for Event
impl Sync for Event
impl UnwindSafe for Event
Auto Trait Implementations
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more