Struct LocalOnceEvent 

pub struct LocalOnceEvent<T> { /* private fields */ }

A one-time event that can send and receive a value of type T on a single thread.

The event can only be used once - after binding a sender and receiver, subsequent bind calls will panic (or return None for the checked variants).

Similarly, sending a value will consume the sender, preventing further use. You need to create a new event instance to create another sender-receiver pair.

To reuse event resources for many operations and avoid constantly recreating events, use LocalOnceEventPool.

For an event that can send the value across threads, see OnceEvent.

Example

use events::LocalOnceEvent;

let event = LocalOnceEvent::<String>::new();
let (sender, receiver) = event.bind_by_ref();

sender.send("Hello".to_string());
let message = futures::executor::block_on(receiver).unwrap();
assert_eq!(message, "Hello");

Implementations

impl<T> LocalOnceEvent<T>

pub fn new() -> Self

Creates a new single-threaded event.

The event must be bound to a sender-receiver pair to be used.

Example

use events::LocalOnceEvent;

let event = LocalOnceEvent::<i32>::new();

pub fn new_managed() -> (LocalOnceSender<ManagedLocalEvent<T>>, LocalOnceReceiver<ManagedLocalEvent<T>>)

Creates a new single-threaded event with automatically managed heap storage, returning both the sender and receiver for this event.

The memory used by the event is released when both endpoints are dropped. This is similar to oneshot::channel() but for single-threaded use cases.

Example

use events::LocalOnceEvent;

let (sender, receiver) = LocalOnceEvent::<String>::new_managed();

sender.send("Hello from the managed event!".to_string());
let message = receiver.await.unwrap();
assert_eq!(message, "Hello from the managed event!");

pub fn bind_by_ref( &self, ) -> (LocalOnceSender<RefLocalEvent<'_, T>>, LocalOnceReceiver<RefLocalEvent<'_, T>>)

Returns both the sender and receiver for this event, connected by a shared reference to the event.

Panics

Panics if the event has already been bound to a sender-receiver pair.

Example

use events::LocalOnceEvent;

let event = LocalOnceEvent::<i32>::new();
let (sender, receiver) = event.bind_by_ref();

pub fn bind_by_ref_checked( &self, ) -> Option<(LocalOnceSender<RefLocalEvent<'_, T>>, LocalOnceReceiver<RefLocalEvent<'_, T>>)>

Returns both the sender and receiver for this event, connected by a shared reference to the event.

Returns None if the event has already been bound to a sender-receiver pair.

Example

use events::LocalOnceEvent;

let event = LocalOnceEvent::<i32>::new();
let endpoints = event.bind_by_ref_checked().unwrap();
let endpoints2 = event.bind_by_ref_checked(); // Returns None
assert!(endpoints2.is_none());

pub unsafe fn bind_by_ref_unchecked( &self, ) -> (LocalOnceSender<RefLocalEvent<'_, T>>, LocalOnceReceiver<RefLocalEvent<'_, T>>)

Returns both the sender and receiver for this event, connected by a shared reference to the event.

This method assumes the event is not already bound and skips the check for performance.

Safety

The caller must guarantee the event is not already bound.

Example

use events::LocalOnceEvent;

let event = LocalOnceEvent::<i32>::new();
// We know this is the first and only binding of this event
// SAFETY: We know this is the first and only binding of this event
let (sender, receiver) = unsafe { event.bind_by_ref_unchecked() };

pub fn bind_by_rc( self: &Rc<Self>, ) -> (LocalOnceSender<RcLocalEvent<T>>, LocalOnceReceiver<RcLocalEvent<T>>)

Returns both the sender and receiver for this event, connected by an Rc to the event.

This method requires the event to be wrapped in an Rc when called.

Panics

Panics if the event has already been bound to a sender-receiver pair.

Example

use std::rc::Rc;

use events::LocalOnceEvent;

let event = Rc::new(LocalOnceEvent::<i32>::new());
let (sender, receiver) = event.bind_by_rc();

pub fn bind_by_rc_checked( self: &Rc<Self>, ) -> Option<(LocalOnceSender<RcLocalEvent<T>>, LocalOnceReceiver<RcLocalEvent<T>>)>

Returns both the sender and receiver for this event, connected by an Rc to the event.

Returns None if the event has already been bound to a sender-receiver pair.

This method requires the event to be wrapped in an Rc when called.

Example

use std::rc::Rc;

use events::LocalOnceEvent;

let event = Rc::new(LocalOnceEvent::<i32>::new());
let endpoints = event.bind_by_rc_checked().unwrap();
let endpoints2 = event.bind_by_rc_checked(); // Returns None
assert!(endpoints2.is_none());

pub unsafe fn bind_by_rc_unchecked( self: &Rc<Self>, ) -> (LocalOnceSender<RcLocalEvent<T>>, LocalOnceReceiver<RcLocalEvent<T>>)

Returns both the sender and receiver for this event, connected by an Rc to the event.

This method assumes the event is not already bound and skips the check for performance.

This method requires the event to be wrapped in an Rc when called.

Safety

The caller must ensure that the event is not already bound.

Example

use std::rc::Rc;

use events::LocalOnceEvent;

let event = Rc::new(LocalOnceEvent::<i32>::new());
// We know this is the first and only binding of this event
// SAFETY: We know this is the first and only binding of this event
let (sender, receiver) = unsafe { event.bind_by_rc_unchecked() };

pub unsafe fn bind_by_ptr( self: Pin<&Self>, ) -> (LocalOnceSender<PtrLocalEvent<T>>, LocalOnceReceiver<PtrLocalEvent<T>>)

Returns both the sender and receiver for this event, connected by a raw pointer to the event.

This method requires the event to be pinned when called.

Safety

The caller must ensure that:

• The event remains alive and pinned for the entire lifetime of the sender and receiver.
• The sender and receiver are dropped before the event is dropped.

Panics

Panics if the event has already been bound to a sender-receiver pair.

Example

use events::LocalOnceEvent;

let mut event = Box::pin(LocalOnceEvent::<i32>::new());
// SAFETY: We ensure the event outlives the sender and receiver, see below.
let (sender, receiver) = unsafe { event.as_ref().bind_by_ptr() };

sender.send(42);
let value = futures::executor::block_on(receiver).unwrap();
assert_eq!(value, 42);
// sender and receiver are dropped here, before event

pub unsafe fn bind_by_ptr_checked( self: Pin<&Self>, ) -> Option<(LocalOnceSender<PtrLocalEvent<T>>, LocalOnceReceiver<PtrLocalEvent<T>>)>

Returns both the sender and receiver for this event, connected by a raw pointer to the event.

Returns None if the event has already been bound to a sender-receiver pair.

This method requires the event to be pinned when called.

Safety

The caller must ensure that:

• The event remains alive and pinned for the entire lifetime of the sender and receiver.
• The sender and receiver are dropped before the event is dropped.

Example

use events::LocalOnceEvent;

let mut event = Box::pin(LocalOnceEvent::<i32>::new());
// SAFETY: We ensure the event outlives the sender and receiver
let endpoints = unsafe { event.as_ref().bind_by_ptr_checked() }.unwrap();
let endpoints2 = unsafe { event.as_ref().bind_by_ptr_checked() }; // Returns None
assert!(endpoints2.is_none());

pub unsafe fn bind_by_ptr_unchecked( self: Pin<&Self>, ) -> (LocalOnceSender<PtrLocalEvent<T>>, LocalOnceReceiver<PtrLocalEvent<T>>)

Returns both the sender and receiver for this event, connected by a raw pointer to the event.

This method assumes the event is not already bound and skips the check for performance.

This method requires the event to be pinned when called.

Safety

The caller must ensure that:

• The event is not already bound.
• The event remains alive and pinned for the entire lifetime of the sender and receiver.
• The sender and receiver are dropped before the event is dropped.

Example

use events::LocalOnceEvent;

let mut event = Box::pin(LocalOnceEvent::<i32>::new());
// SAFETY: We ensure the event outlives the sender and receiver
let (sender, receiver) = unsafe { event.as_ref().bind_by_ptr_unchecked() };

pub unsafe fn new_in_place_by_ptr( place: Pin<&mut MaybeUninit<Self>>, ) -> (LocalOnceSender<PtrLocalEvent<T>>, LocalOnceReceiver<PtrLocalEvent<T>>)

Initializes the event in-place at a pinned location and returns both the sender and receiver for this event, connected by a raw pointer to the event.

This method is useful for high-performance scenarios where you want to avoid heap allocation and have precise control over memory layout.

Safety

The caller must ensure that:

• The place the event is stored remains valid for the entire lifetime of the sender and receiver.
• The sender and receiver are dropped before the event is dropped.
• The event is eventually dropped by its owner.

Example

use std::mem::MaybeUninit;
use std::pin::pin;

use events::LocalOnceEvent;

let mut event_storage = pin!(MaybeUninit::uninit());

// SAFETY: We keep the event alive until sender/receiver are done
let (sender, receiver) =
    unsafe { LocalOnceEvent::<i32>::new_in_place_by_ptr(event_storage.as_mut()) };

sender.send(42);
let value = receiver.await.unwrap();
assert_eq!(value, 42);

// Both sender and receiver are dropped here, before we drop the event

// SAFETY: We initialized it above and have dropped both sender and receiver
unsafe {
    event_storage.get_unchecked_mut().assume_init_drop();
}

pub fn inspect_awaiter(&self, f: impl FnOnce(Option<&Backtrace>))

Uses the provided closure to inspect the backtrace of the current awaiter, if there is an awaiter and if backtrace capturing is enabled.

This method is only available in debug builds (cfg(debug_assertions)). For any data to be present, RUST_BACKTRACE=1 or RUST_LIB_BACKTRACE=1 must be set.

The closure receives None if no one is awaiting the event.

Trait Implementations

impl<T: Debug> Debug for LocalOnceEvent<T>

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

Formats the value using the given formatter.

impl<T> Default for LocalOnceEvent<T>

fn default() -> Self

Returns the “default value” for a type.