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:

  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§

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

Trait Implementations§

source§

impl Debug for Event

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for Event

source§

fn default() -> Event

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

impl Drop for Event

source§

fn drop(&mut self)

Executes the destructor for this type. Read more
source§

impl RefUnwindSafe for Event

source§

impl Send for Event

source§

impl Sync for Event

source§

impl UnwindSafe for Event

Auto Trait Implementations§

§

impl Unpin for Event

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

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

source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.