Struct LocalOnceEventPool 

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

A pool that manages single-threaded events with automatic cleanup.

The pool creates local events on demand and automatically cleans them up when both sender and receiver endpoints are dropped.

This is the single-threaded variant that cannot be shared across threads but has lower overhead than the thread-safe super::OnceEventPool.

The pool provides zero-allocation event reuse for high-frequency eventing scenarios within a single thread.

Example

use events::LocalOnceEventPool;

let pool = LocalOnceEventPool::<i32>::new();

// First usage - creates new event
let (sender1, receiver1) = pool.bind_by_ref();
sender1.send(42);
let value1 = futures::executor::block_on(receiver1).unwrap();
assert_eq!(value1, 42);
// Event returned to pool when sender1/receiver1 are dropped

// Second usage - reuses the same event instance for efficiency
let (sender2, receiver2) = pool.bind_by_ref();
sender2.send(100);
let value2 = futures::executor::block_on(receiver2).unwrap();
assert_eq!(value2, 100);
// Same event reused - no additional allocation overhead

Implementations

impl<T> LocalOnceEventPool<T>

pub fn new() -> Self

Creates a new empty local event pool.

Example

use events::LocalOnceEventPool;

let pool = LocalOnceEventPool::<String>::new();

pub fn bind_by_ref( &self, ) -> (PooledLocalOnceSender<RefLocalPool<'_, T>>, PooledLocalOnceReceiver<RefLocalPool<'_, T>>)

Creates sender and receiver endpoints connected by reference to the pool.

The pool will create a new local event and return endpoints that reference it. When both endpoints are dropped, the event will be automatically cleaned up.

Example

use events::LocalOnceEventPool;

let pool = LocalOnceEventPool::<i32>::new();

// First usage
let (sender1, receiver1) = pool.bind_by_ref();
sender1.send(42);
let value1 = futures::executor::block_on(receiver1).unwrap();
assert_eq!(value1, 42);

// Second usage - efficiently reuses the same underlying event
let (sender2, receiver2) = pool.bind_by_ref();
sender2.send(100);
let value2 = futures::executor::block_on(receiver2).unwrap();
assert_eq!(value2, 100);

pub fn bind_by_rc( self: &Rc<Self>, ) -> (PooledLocalOnceSender<RcLocalPool<T>>, PooledLocalOnceReceiver<RcLocalPool<T>>)

Creates sender and receiver endpoints connected by Rc to the pool.

The pool will create a new local event and return endpoints that hold Rc references. When both endpoints are dropped, the event will be automatically cleaned up.

Example

use std::rc::Rc;

use events::LocalOnceEventPool;

let pool = Rc::new(LocalOnceEventPool::<i32>::new());

// First usage
let (sender1, receiver1) = pool.bind_by_rc();
sender1.send(42);
let value1 = futures::executor::block_on(receiver1).unwrap();
assert_eq!(value1, 42);

// Second usage - reuses the same event from the pool
let (sender2, receiver2) = pool.bind_by_rc();
sender2.send(200);
let value2 = futures::executor::block_on(receiver2).unwrap();
assert_eq!(value2, 200);

pub unsafe fn bind_by_ptr( self: Pin<&Self>, ) -> (PooledLocalOnceSender<PtrLocalPool<T>>, PooledLocalOnceReceiver<PtrLocalPool<T>>)

Creates sender and receiver endpoints connected by raw pointer to the pool.

The pool will create a new local event and return endpoints that hold raw pointers. When both endpoints are dropped, the event will be automatically cleaned up.

Safety

The caller must ensure that:

• The pool remains valid and pinned for the entire lifetime of the sender and receiver
• The sender and receiver are dropped before the pool is dropped

Example

use std::pin::Pin;

use events::LocalOnceEventPool;

let pool = Box::pin(LocalOnceEventPool::<i32>::new());

// First usage
// SAFETY: We ensure the pool is pinned and outlives the sender and receiver
let (sender1, receiver1) = unsafe { pool.as_ref().bind_by_ptr() };
sender1.send(42);
let value1 = receiver1.await.unwrap();
assert_eq!(value1, 42);

// Second usage - reuses the same event efficiently
// SAFETY: Pool is still valid and pinned
let (sender2, receiver2) = unsafe { pool.as_ref().bind_by_ptr() };
sender2.send(100);
let value2 = receiver2.await.unwrap();
assert_eq!(value2, 100);
// Both sender and receiver pairs are dropped here, before pool

pub fn len(&self) -> usize

Returns the number of events currently in the pool.

This represents the count of events that are currently allocated in the pool, including those that are currently bound to sender/receiver endpoints. Events are removed from the pool only when both endpoints are dropped.

Example

use events::LocalOnceEventPool;

let pool = LocalOnceEventPool::<i32>::new();
assert_eq!(pool.len(), 0);

let (sender, receiver) = pool.bind_by_ref();
assert_eq!(pool.len(), 1); // Event is in pool while endpoints exist

drop(sender);
drop(receiver);
assert_eq!(pool.len(), 0); // Event cleaned up after both endpoints dropped

pub fn is_empty(&self) -> bool

Returns whether the pool is empty.

This is equivalent to pool.len() == 0 but may be more efficient. An empty pool may still have reserved capacity.

Example

use events::LocalOnceEventPool;

let pool = LocalOnceEventPool::<i32>::new();
assert!(pool.is_empty());

let (sender, receiver) = pool.bind_by_ref();
assert!(!pool.is_empty()); // Pool has event while endpoints exist

drop(sender);
drop(receiver);
assert!(pool.is_empty()); // Pool empty after both endpoints dropped

pub fn shrink_to_fit(&self)

Shrinks the capacity of the pool to reduce memory usage.

This method attempts to release unused memory by reducing the pool’s capacity. The actual reduction is implementation-dependent and may vary - some capacity may be released, or none at all.

Example

use events::LocalOnceEventPool;

let pool = LocalOnceEventPool::<i32>::new();

// Use the pool which may grow its capacity
for _ in 0..100 {
    let (sender, receiver) = pool.bind_by_ref();
    sender.send(42);
    let _value = futures::executor::block_on(receiver);
}

// Attempt to shrink to reduce memory usage
pool.shrink_to_fit();

pub fn inspect_awaiters(&self, f: impl FnMut(Option<&Backtrace>))

Uses the provided closure to inspect the backtraces of the most recent awaiter of each event in the pool (or None if it has never been awaited).

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 is called once for each event in the pool that is currently being awaited by someone.

Trait Implementations

impl<T> Debug for LocalOnceEventPool<T>

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

Formats the value using the given formatter.

impl<T> Default for LocalOnceEventPool<T>

fn default() -> Self

Returns the “default value” for a type.