Struct event_listener::EventListener

pub struct EventListener<T = ()> { /* private fields */ }

A guard waiting for a notification from an Event.

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.

The listener is not registered into the linked list inside of the Event by default if it is created via the new() method. It needs to be pinned first before being inserted using the listen() method. After the listener has begun listening, the user can await it like a future or call wait() to block the current thread until it is notified.

Examples

use event_listener::{Event, EventListener};
use std::sync::{Arc, atomic::{AtomicBool, Ordering}};
use std::thread;
use std::time::Duration;

// Some flag to wait on.
let flag = Arc::new(AtomicBool::new(false));

// Create an event to wait on.
let event = Arc::new(Event::new());

thread::spawn({
    let flag = flag.clone();
    let event = event.clone();
    move || {
        thread::sleep(Duration::from_secs(2));
        flag.store(true, Ordering::SeqCst);

        // Wake up the listener.
        event.notify_additional(std::usize::MAX);
    }
});

let listener = EventListener::new();

// Make sure that the event listener is pinned before doing anything else.
//
// We pin the listener to the stack here, as it lets us avoid a heap allocation.
futures_lite::pin!(listener);

// Wait for the flag to become ready.
loop {
    if flag.load(Ordering::Acquire) {
        // We are done.
        break;
    }

    if listener.is_listening() {
        // We are inserted into the linked list and we can now wait.
        listener.as_mut().wait();
    } else {
        // We need to insert ourselves into the list. Since this insertion is an atomic
        // operation, we should check the flag again before waiting.
        listener.as_mut().listen(&event);
    }
}

The above example is equivalent to the one provided in the crate level example. However, it has some advantages. By directly creating the listener with EventListener::new(), we have control over how the listener is handled in memory. We take advantage of this by pinning the listener variable to the stack using the futures_lite::pin macro. In contrast, Event::listen binds the listener to the heap.

However, this additional power comes with additional responsibility. By default, the event listener is created in an “uninserted” state. This property means that any notifications delivered to the Event by default will not wake up this listener. Before any notifications can be received, the listen() method must be called on EventListener to insert it into the list of listeners. After a .await or a wait() call has completed, listen() must be called again if the user is still interested in any events.

Implementations

impl<T> EventListener<T>

pub fn new() -> Self

Create a new EventListener that will wait for a notification from the given Event.

This function does not register the EventListener into the linked list of listeners contained within the Event. Make sure to call listen before awaiting on this future or calling wait().

Examples

use event_listener::{Event, EventListener};

let event = Event::new();
let listener = EventListener::new();

// Make sure that the listener is pinned and listening before doing anything else.
let mut listener = Box::pin(listener);
listener.as_mut().listen(&event);

pub fn listen(self: Pin<&mut Self>, event: &Event<T>)

Register this listener into the given Event.

This method can only be called after the listener has been pinned, and must be called before the listener is polled.

Notifications that exist when this function is called will be discarded.

pub fn is_listening(&self) -> bool

Tell if this EventListener is currently listening for a notification.

Examples

use event_listener::{Event, EventListener};

let event = Event::new();
let mut listener = Box::pin(EventListener::new());

// The listener starts off not listening.
assert!(!listener.is_listening());

// After listen() is called, the listener is listening.
listener.as_mut().listen(&event);
assert!(listener.is_listening());

// Once the future is notified, the listener is no longer listening.
event.notify(1);
listener.as_mut().wait();
assert!(!listener.is_listening());

pub fn wait(self: Pin<&mut Self>) -> T

Blocks until a notification is received.

Examples

use event_listener::Event;

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

// Notify `listener`.
event.notify(1);

// Receive the notification.
listener.as_mut().wait();

pub fn wait_timeout(self: Pin<&mut Self>, timeout: Duration) -> Option<T>

Blocks until a notification is received or a timeout is reached.

Returns true if a notification was received.

Examples

use std::time::Duration;
use event_listener::Event;

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

// There are no notification so this times out.
assert!(listener.as_mut().wait_timeout(Duration::from_secs(1)).is_none());

pub fn wait_deadline(self: Pin<&mut Self>, deadline: Instant) -> Option<T>

Blocks until a notification is received or a deadline is reached.

Returns true if a notification was received.

Examples

use std::time::{Duration, Instant};
use event_listener::Event;

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

// There are no notification so this times out.
assert!(listener.as_mut().wait_deadline(Instant::now() + Duration::from_secs(1)).is_none());

pub fn discard(self: Pin<&mut Self>) -> bool

Drops this listener and discards its notification (if any) without notifying another active listener.

Returns true if a notification was discarded.

Examples

use event_listener::Event;

let event = Event::new();
let mut listener1 = event.listen();
let mut listener2 = event.listen();

event.notify(1);

assert!(listener1.as_mut().discard());
assert!(!listener2.as_mut().discard());

pub fn listens_to(&self, event: &Event<T>) -> bool

Returns true if this listener listens to the given Event.

Examples

use event_listener::Event;

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

assert!(listener.listens_to(&event));

pub fn same_event(&self, other: &EventListener<T>) -> bool

Returns true if both listeners listen to the same Event.

Examples

use event_listener::Event;

let event = Event::new();
let listener1 = event.listen();
let listener2 = event.listen();

assert!(listener1.same_event(&listener2));

Trait Implementations

impl<T> Debug for EventListener<T>

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

Formats the value using the given formatter.

impl<T> Default for EventListener<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T> Future for EventListener<T>

type Output = T

The type of value produced on completion.

fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output>

Attempt to resolve the future to a final value, registering the current task for wakeup if the value is not yet available.

impl<T> RefUnwindSafe for EventListener<T>

impl<T: Send> Send for EventListener<T>

impl<T: Send> Sync for EventListener<T>

impl<T> UnwindSafe for EventListener<T>