Struct event_listener::Event

pub struct Event { /* fields omitted */ }

A synchronization primitive for notifying async tasks and threads.

Listeners can be registered using Event::listen(). There are threifour ways of notifying listeners:

1. Event::notify_one() notifies one listener.
2. Event::notify_all() notifies all listeners.
3. Event::notify() notifies an arbitrary number of listeners.
4. Event::notify_additional() notifies an arbitrary number of unnotified listeners.

If there are no active listeners at the time a notification is sent, it simply gets lost.

Note that Event::notify_one() does not notify one additional listener - it only makes sure at least one listener among the active ones is notified. Similarly, Event::notify() makes sure a number of active listeners are notified. If you need to notify additional listeners, use Event::notify_additional().

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.

Listeners are registered and notified in the first-in first-out fashion, ensuring fairness.

Implementations

impl Event

pub fn new() -> Event

Creates a new Event.

Examples

use event_listener::Event;

let event = Event::new();

pub fn listen(&self) -> EventListener

Returns a guard listening for a notification.

Examples

use event_listener::Event;

let event = Event::new();
let listener = event.listen();

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.

Note that this does not notify n additional listeners - it only makes sure at least n listeners among the active ones are notified.

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

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.

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

pub fn notify_one(&self)

Notifies a single active listener.

Note that this does not notify one additional listener - it only makes sure at least one listener among the active ones is notified.

This method is equivalent to self.notify(1).

Examples

use event_listener::Event;

let event = Event::new();

// This notification gets lost because there are no listeners.
event.notify_one();

let listener1 = event.listen();
let listener2 = event.listen();

// Notifies just one of `listener1` and `listener2`.
//
// Listener queueing is fair, which means `listener1` gets notified
// here since it was the first to start listening.
event.notify_one();

pub fn notify_all(&self)

Notifies all active listeners.

This method is equivalent to self.notify(usize::MAX).

Examples

use event_listener::Event;

let event = Event::new();

// This notification gets lost because there are no listeners.
event.notify_all();

let listener1 = event.listen();
let listener2 = event.listen();

// Both `listener1` and `listener2` get notified.
event.notify_all();

Trait Implementations

impl Debug for Event

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Default for Event

fn default() -> Event

Returns the "default value" for a type.

impl Drop for Event

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Event

impl Sync for Event