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:

  1. Event::notify() notifies a number of listeners.
  2. 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:

  1. In an asynchronous manner using .await.
  2. 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

Creates a new Event.

Examples
use event_listener::Event;

let event = Event::new();

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();

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);

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);

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);

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

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Executes the destructor for this type. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.