Struct 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§

source §

impl Event

source

pub const fn new() -> Event

Creates a new Event.

§Examples

use event_listener::Event;

let event = Event::new();

source

pub fn listen(&self) -> EventListener ⓘ

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

source

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

source

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

source

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

source

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