Struct RawPinnedPool 

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

A pool of objects of type T.

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

The pool automatically expands its capacity when needed.

Thread safety

If T: Send then the pool is thread-mobile (Send but not Sync).

If T: !Send, the pool is single-threaded.

Example

use infinity_pool::RawPinnedPool;

let mut pool = RawPinnedPool::<String>::new();

// Insert an object into the pool
let handle = pool.insert("Hello, Raw Pinned!".to_string());

// Access the object through the handle
let stored_value = unsafe { handle.ptr().as_ref() };
assert_eq!(stored_value, "Hello, Raw Pinned!");

// Explicitly remove the object from the pool
pool.remove_mut(handle);

Implementations

impl<T> RawPinnedPool<T>

pub fn builder() -> RawPinnedPoolBuilder<T>

Starts configuring and creating a new instance of the pool.

pub fn new() -> Self

Creates a new pool with the default configuration.

pub fn len(&self) -> usize

The number of objects currently in the pool.

pub fn capacity(&self) -> usize

The total capacity of the pool.

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 are inserted.

pub fn is_empty(&self) -> bool

Whether the pool contains zero objects.

pub fn reserve(&mut self, additional: usize)

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

Panics

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

pub fn shrink_to_fit(&mut 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.

pub fn insert(&mut self, value: T) -> RawPooledMut<T>

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

Example

use infinity_pool::RawPinnedPool;

let mut pool = RawPinnedPool::<String>::new();

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

// Mutate the object via the unique handle
// SAFETY: The handle is valid and points to a properly initialized String
unsafe {
    handle.as_mut().push_str(", Raw World!");
    assert_eq!(handle.as_ref(), "Hello, Raw World!");
}

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

// After transformation, you can only immutably dereference the object
// SAFETY: The shared handle is valid and points to a properly initialized String
unsafe {
    assert_eq!(shared_handle.as_ref(), "Hello, Raw World!");
    // shared_handle.as_mut(); // This would not compile
}

// Explicitly remove the object from the pool
// SAFETY: The handle belongs to this pool and references a valid object
unsafe {
    pool.remove(shared_handle);
}
assert_eq!(pool.len(), 0);

pub unsafe fn insert_with<F>(&mut self, f: F) -> RawPooledMut<T>

where 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::RawPinnedPool;

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

let mut pool = RawPinnedPool::<DataBuffer>::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.ptr().as_ref().id).read() };
assert_eq!(id, 42);

Safety

The closure must correctly initialize the object. All fields that are not MaybeUninit must be initialized when the closure returns.

pub fn remove_mut<P: ?Sized>(&mut self, handle: RawPooledMut<P>)

Removes an object from the pool, dropping it.

Panics

Panics if the handle does not reference an object in this pool.

pub unsafe fn remove<P: ?Sized>(&mut self, handle: RawPooled<P>)

Removes an object from the pool, dropping it.

Panics

Panics if the handle does not reference an object in this pool.

Safety

The caller must ensure that the handle belongs to this pool and that the object it references has not already been removed from the pool.

pub fn iter(&self) -> RawPinnedPoolIterator<'_, T>

Returns an iterator over all objects in the pool.

impl<T> RawPinnedPool<T>

where T: Unpin,

pub fn remove_mut_unpin(&mut self, handle: RawPooledMut<T>) -> T

Removes an object from the pool and returns it.

Panics

Panics if the handle does not reference an object in this pool.

pub unsafe fn remove_unpin(&mut self, handle: RawPooled<T>) -> T

Removes an object from the pool and returns it.

Panics

Panics if the handle does not reference an existing object in this pool.

Safety

The caller must ensure that the handle belongs to this pool and that the object it references has not already been removed from the pool.

Trait Implementations

impl<T> Debug for RawPinnedPool<T>

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

Formats the value using the given formatter.

impl<T> Default for RawPinnedPool<T>

fn default() -> Self

Returns the “default value” for a type.

impl<'p, T> IntoIterator for &'p RawPinnedPool<T>

type Item = NonNull<T>

The type of the elements being iterated over.

type IntoIter = RawPinnedPoolIterator<'p, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T> Send for RawPinnedPool<T>

where T: Send,