Struct OnceEvent 

pub struct OnceEvent<T>
where
    T: Send,
{ /* private fields */ }

A one-time event that can send and receive a value of type T, potentially across threads.

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 OnceEventPool.

For single-threaded usage, see LocalOnceEvent which has lower overhead.

Example

use events::OnceEvent;

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

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

Implementations

impl<T> OnceEvent<T>

where T: Send,

pub fn new() -> Self

Creates a new thread-safe event.

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

Example

use events::OnceEvent;

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

pub fn new_managed() -> (OnceSender<ManagedEvent<T>>, OnceReceiver<ManagedEvent<T>>)

Creates a new thread-safe 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().

Example

use std::thread;

use events::OnceEvent;

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

let sender_handle = thread::spawn(move || {
    sender.send("Hello from a managed event!".to_string());
});

let receiver_handle = thread::spawn(move || block_on(receiver));

sender_handle.join().unwrap();
let message = receiver_handle.join().unwrap().unwrap();
assert_eq!(message, "Hello from a managed event!");

pub fn bind_by_ref( &self, ) -> (OnceSender<RefEvent<'_, T>>, OnceReceiver<RefEvent<'_, 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::OnceEvent;

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

pub fn bind_by_ref_checked( &self, ) -> Option<(OnceSender<RefEvent<'_, T>>, OnceReceiver<RefEvent<'_, 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::OnceEvent;

let event = OnceEvent::<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, ) -> (OnceSender<RefEvent<'_, T>>, OnceReceiver<RefEvent<'_, 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::OnceEvent;

let event = OnceEvent::<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_arc( self: &Arc<Self>, ) -> (OnceSender<ArcEvent<T>>, OnceReceiver<ArcEvent<T>>)

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

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

Panics

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

Example

use std::sync::Arc;

use events::OnceEvent;

let event = Arc::new(OnceEvent::<i32>::new());
let (sender, receiver) = event.bind_by_arc();

pub fn bind_by_arc_checked( self: &Arc<Self>, ) -> Option<(OnceSender<ArcEvent<T>>, OnceReceiver<ArcEvent<T>>)>

Returns both the sender and receiver for this event, connected by an Arc 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 Arc when called.

Example

use std::sync::Arc;

use events::OnceEvent;

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

pub unsafe fn bind_by_arc_unchecked( self: &Arc<Self>, ) -> (OnceSender<ArcEvent<T>>, OnceReceiver<ArcEvent<T>>)

Returns both the sender and receiver for this event, connected by an Arc 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 Arc when called.

Safety

The caller must guarantee the event is not already bound.

Example

use std::sync::Arc;

use events::OnceEvent;

let event = Arc::new(OnceEvent::<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_arc_unchecked() };

pub unsafe fn bind_by_ptr( self: Pin<&Self>, ) -> (OnceSender<PtrEvent<T>>, OnceReceiver<PtrEvent<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::OnceEvent;

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

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

pub unsafe fn bind_by_ptr_checked( self: Pin<&Self>, ) -> Option<(OnceSender<PtrEvent<T>>, OnceReceiver<PtrEvent<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 std::pin::Pin;

use events::OnceEvent;

let mut event = Box::pin(OnceEvent::<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>, ) -> (OnceSender<PtrEvent<T>>, OnceReceiver<PtrEvent<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::OnceEvent;

let mut event = Box::pin(OnceEvent::<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>>, ) -> (OnceSender<PtrEvent<T>>, OnceReceiver<PtrEvent<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, especially in multi-threaded contexts.

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 std::thread;

use events::OnceEvent;

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

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

let sender_handle = thread::spawn(move || {
    sender.send("Hello from in-place event!".to_string());
});

let receiver_handle = thread::spawn(move || block_on(receiver));

sender_handle.join().unwrap();
let message = receiver_handle.join().unwrap().unwrap();
assert_eq!(message, "Hello from in-place event!");

// 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 for OnceEvent<T>

where T: Send + Debug,

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

Formats the value using the given formatter.

impl<T> Default for OnceEvent<T>

where T: Send,

fn default() -> Self

Returns the “default value” for a type.

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