Struct BlindPool

pub struct BlindPool { /* private fields */ }

A pinned object pool of unbounded size that accepts objects of any type.

The pool returns a Pooled<T> for each inserted value, which acts as both the key and provides direct access to the inserted item via a pointer.

Out of band access

The collection does not create or keep references to the memory blocks. The only way to access the contents of the collection is via unsafe code by using the pointer from a Pooled<T>.

The collection does not create or maintain any & shared or &mut exclusive references to the items it contains, except when explicitly called to operate on an item (e.g. remove() implies exclusive access).

Resource usage

The collection automatically grows as items are added. To reduce memory usage after items have been removed, use the shrink_to_fit() method to release unused capacity.

Example

use blind_pool::BlindPool;

let mut pool = BlindPool::new();

// Insert values of different types.
let pooled_u32 = pool.insert(42_u32);
let pooled_i64 = pool.insert(-123_i64);

// Read from the memory.
// SAFETY: The pointers are valid and the memory contains the values we just inserted.
let value_u32 = unsafe { pooled_u32.ptr().read() };
let value_i64 = unsafe { pooled_i64.ptr().read() };

assert_eq!(value_u32, 42);
assert_eq!(value_i64, -123);

Implementations

impl BlindPool

pub fn new() -> Self

Creates a new BlindPool with default configuration.

This is equivalent to BlindPool::builder().build().

Example

use blind_pool::BlindPool;

let mut pool = BlindPool::new();

let pooled = pool.insert(42_u64);

// SAFETY: The pointer is valid and contains the value we just inserted.
let value = unsafe { pooled.ptr().read() };
assert_eq!(value, 42);

pub fn builder() -> BlindPoolBuilder

Creates a builder for configuring and constructing a BlindPool.

Example

use blind_pool::{BlindPool, DropPolicy};

let pool = BlindPool::builder()
    .drop_policy(DropPolicy::MustNotDropItems)
    .build();

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

Inserts a value into the pool and returns a handle to access it.

The pool stores the value and provides a handle for later access or removal.

Example

use blind_pool::BlindPool;

let mut pool = BlindPool::new();

// Insert different types into the same pool.
let pooled_int = pool.insert(42_i32);
let pooled_float = pool.insert(2.5_f64);
let pooled_string = pool.insert("hello".to_string());

// All values are stored in the same BlindPool.
assert_eq!(pool.len(), 3);

pub fn remove<T>(&mut self, pooled: Pooled<T>)

Removes a value from the pool and drops it.

The Pooled<T> handle is consumed and the memory is returned to the pool. The value is dropped.

Example

use blind_pool::BlindPool;

let mut pool = BlindPool::new();

let pooled = pool.insert(42_u64);
assert_eq!(pool.len(), 1);

pool.remove(pooled);
assert_eq!(pool.len(), 0);

pub fn len(&self) -> usize

Returns the total number of items stored in the pool.

Example

use blind_pool::BlindPool;

let mut pool = BlindPool::new();

assert_eq!(pool.len(), 0);

let _a = pool.insert(42_u32);
let _b = pool.insert("hello".to_string());
let _c = pool.insert(2.5_f64);

assert_eq!(pool.len(), 3);

pub fn is_empty(&self) -> bool

Whether the pool has no inserted values.

An empty pool may still be holding unused memory capacity.

Example

use blind_pool::BlindPool;

let mut pool = BlindPool::new();

assert!(pool.is_empty());

let pooled = pool.insert(42_u16);

assert!(!pool.is_empty());

pool.remove(pooled);
assert!(pool.is_empty());

pub fn capacity(&self) -> usize

Returns the total capacity of the pool.

This is the total number of items that can be stored without allocating more memory.

Example

use blind_pool::BlindPool;

let mut pool = BlindPool::new();

// Initially no capacity is allocated.
assert_eq!(pool.capacity(), 0);

// Inserting a value allocates capacity.
let _pooled = pool.insert(42_u32);
assert!(pool.capacity() > 0);

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the pool to fit its current size.

This can help reduce memory usage after items have been removed from the pool.

Example

use blind_pool::BlindPool;

let mut pool = BlindPool::new();

// Insert many items to allocate capacity.
for i in 0..1000 {
    pool.insert(i);
}

let capacity_before = pool.capacity();

// Remove all items but keep the allocated capacity.
while !pool.is_empty() {
    // In a real scenario you'd keep track of handles to remove them properly.
    // This is just for the example.
    break;
}

// Shrink to fit the current size (which is 0).
pool.shrink_to_fit();
assert!(pool.capacity() <= capacity_before);

Trait Implementations

impl Debug for BlindPool

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

Formats the value using the given formatter.

impl Default for BlindPool

fn default() -> Self

Returns the “default value” for a type.

impl Drop for BlindPool

fn drop(&mut self)

Executes the destructor for this type.