Struct LocalBlindPool

Source

pub struct LocalBlindPool { /* private fields */ }

Expand description

A single-threaded reference-counting object pool that accepts any type of object.

All values in the pool remain pinned for their entire lifetime.

The pool automatically expands its capacity when needed.

§Lifetime management

The pool itself acts as a handle - any clones of it are functionally equivalent, similar to Rc.

When inserting an object into the pool, a handle to the object is returned. The object is removed from the pool when the last remaining handle to the object is dropped (Rc-like behavior).

§Thread safety

The pool is single-threaded.

§Example

use infinity_pool::LocalBlindPool;

fn work_with_data(data: impl std::fmt::Display + 'static) {
    let mut pool = LocalBlindPool::new();

    // Insert an object into the pool (type determined at runtime)
    let handle = pool.insert(data.to_string());

    // Access the object through the handle
    assert_eq!(*handle, data.to_string());

    // The object is automatically removed when the handle is dropped
}

work_with_data("Hello, Local Blind!");
work_with_data(42);

§Pool clones are functionally equivalent

use infinity_pool::LocalBlindPool;

let mut pool1 = LocalBlindPool::new();
let pool2 = pool1.clone();

assert_eq!(pool1.len(), pool2.len());
let _handle = pool1.insert(42_i32);
assert_eq!(pool1.len(), pool2.len());

Implementations§

Source §

impl LocalBlindPool

Source

pub fn new() -> Self

Creates a new pool with the default configuration.

Source

pub fn len(&self) -> usize

The number of objects currently in the pool.

Source

pub fn capacity_for<T: 'static>(&self) -> usize

The total capacity of the pool for objects of type T.

This is the maximum number of objects (including current contents) that the pool can contain without capacity extension. The pool will automatically extend its capacity if more than this many objects of type T are inserted.

Capacity may be shared between different types of objects.

Source

pub fn is_empty(&self) -> bool

Whether the pool contains zero objects.

Source

pub fn reserve_for<T: 'static>(&self, additional: usize)

Ensures that the pool has capacity for at least additional more objects of type T.

§Panics

Panics if the new capacity would exceed the size of virtual memory (usize::MAX).

Source

pub fn shrink_to_fit(&self)

Drops unused pool capacity to reduce memory usage.

There is no guarantee that any unused capacity can be dropped. The exact outcome depends on the specific pool structure and which objects remain in the pool.

Source

pub fn insert<T: 'static>(&self, value: T) -> LocalBlindPooledMut<T>

Inserts an object into the pool and returns a handle to it.

§Example

use infinity_pool::LocalBlindPool;

let mut pool = LocalBlindPool::new();

// Insert an object into the pool
let mut handle = pool.insert("Hello".to_string());

// Mutate the object via the unique handle
handle.push_str(", Local Blind World!");
assert_eq!(&*handle, "Hello, Local Blind World!");

// Transform the unique handle into a shared handle
let shared_handle = handle.into_shared();

// After transformation, you can only immutably dereference the object
assert_eq!(&*shared_handle, "Hello, Local Blind World!");
// shared_handle.push_str("!"); // This would not compile

// The object is removed when the handle is dropped
drop(shared_handle); // Explicitly drop to remove from pool
assert_eq!(pool.len(), 0);

Source

pub unsafe fn insert_with<T, F>(&self, f: F) -> LocalBlindPooledMut<T>
where T: 'static, F: FnOnce(&mut MaybeUninit<T>),

Inserts an object into the pool via closure and returns a handle to it.

This method allows the caller to partially initialize the object, skipping any MaybeUninit fields that are intentionally not initialized at insertion time. This can make insertion of objects containing MaybeUninit fields faster, although requires unsafe code to implement.

This method is NOT faster than insert() for fully initialized objects. Prefer insert() for a better safety posture if you do not intend to skip initialization of any MaybeUninit fields.

§Example

use std::mem::MaybeUninit;

use infinity_pool::LocalBlindPool;

struct DataBuffer {
    id: u32,
    data: MaybeUninit<[u8; 1024]>, // Large buffer to skip initializing
}

let mut pool = LocalBlindPool::new();

// Initialize only the id, leaving data uninitialized for performance
let handle = unsafe {
    pool.insert_with(|uninit: &mut MaybeUninit<DataBuffer>| {
        let ptr = uninit.as_mut_ptr();
        // SAFETY: Writing to the id field within allocated space
        unsafe {
            std::ptr::addr_of_mut!((*ptr).id).write(42);
            // data field is intentionally left uninitialized
        }
    })
};

// ID is accessible, data remains uninitialized
let id = unsafe { std::ptr::addr_of!((*handle).id).read() };
assert_eq!(id, 42);