Struct Pooled

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

The result of inserting a value of type T into a OpaquePool.

Acts as a super-powered pointer that can be copied and cloned freely. The handle serves both as the key and provides direct access to the stored value. You can return this to the pool to remove the value from the pool and drop it. Depending on the pool’s drop policy, the pool may panic if it is dropped while still containing items.

Being Copy and Clone, this type behaves like a regular pointer - you can duplicate handles freely without affecting the underlying stored value. Multiple copies of the same handle all refer to the same stored value.

The generic parameter T provides type-safe access to the stored value through ptr(). If you need to erase the type information, use erase() to convert the instance to a Pooled<()>, which is functionally equivalent.

Example

use std::alloc::Layout;

use opaque_pool::OpaquePool;

let mut pool = OpaquePool::builder().layout_of::<i64>().build();

// SAFETY: i64 matches the layout used to create the pool.
let pooled = unsafe { pool.insert(-123i64) };

// The handle acts like a super-powered pointer - it can be copied freely.
let pooled_copy = pooled;
let pooled_clone = pooled.clone();

// All copies refer to the same stored value.
// SAFETY: All pointers are valid and point to the same value.
let value1 = unsafe { pooled.ptr().read() };
let value2 = unsafe { pooled_copy.ptr().read() };
let value3 = unsafe { pooled_clone.ptr().read() };
assert_eq!(value1, -123);
assert_eq!(value2, -123);
assert_eq!(value3, -123);

// To remove and drop an item, any handle can be returned to the pool.
pool.remove(pooled);

Implementations

impl<T> Pooled<T>

pub fn ptr(&self) -> NonNull<T>

Returns a pointer to the inserted value.

This is the only way to access the value stored in the pool. The owner of the handle has exclusive access to the value and may both read and write and may create both & shared and &mut exclusive references to the item.

Example

use std::alloc::Layout;

use opaque_pool::OpaquePool;

let mut pool = OpaquePool::builder().layout_of::<f64>().build();

// SAFETY: f64 matches the layout used to create the pool.
let pooled = unsafe { pool.insert(3.14159f64) };

// Read data back from the memory.
let value = unsafe { pooled.ptr().read() };
assert_eq!(value, 3.14159);

pub fn erase(self) -> Pooled<()>

Erases the type information from this Pooled<T> handle, returning a Pooled<()>.

This is useful when you want to store handles of different types in the same collection or pass them to code that doesn’t need to know the specific type.

The handle remains functionally equivalent and can still be used to remove the item from the pool and drop it. The only change is the removal of the type information.

Example

use std::alloc::Layout;

use opaque_pool::OpaquePool;

let mut pool = OpaquePool::builder().layout_of::<u64>().build();

// SAFETY: u64 matches the layout used to create the pool.
let pooled = unsafe { pool.insert(42u64) };

// Erase type information.
let erased = pooled.erase();

// Can still access the raw pointer.
// SAFETY: We know this contains a u64.
let value = unsafe { erased.ptr().cast::<u64>().read() };
assert_eq!(value, 42);

// Can still remove the item.
pool.remove(erased);

Trait Implementations

impl<T: Clone> Clone for Pooled<T>

fn clone(&self) -> Pooled<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for Pooled<T>

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

Formats the value using the given formatter.

impl<T: Copy> Copy for Pooled<T>