Struct PoolRef

Source

pub struct PoolRef<A> { /* private fields */ }

Expand description

A reference counted pointer to a pool allocated value of A.

Implementations§

Source §

impl<A> PoolRef<A>

Source

pub fn default(pool: &Pool<A>) -> Self
where A: PoolDefault,

Construct a PoolRef with a newly initialised value of A.

This uses PoolDefault::default_uninit() to initialise a default value, which may be faster than constructing a PoolRef from an existing value using PoolRef::new(), depending on the data type.

§Examples

let pool: Pool<usize> = Pool::new(256);
let zero = PoolRef::default(&pool);
assert_eq!(0, *zero);

Source

pub fn new(pool: &Pool<A>, value: A) -> Self

Wrap a value in a PoolRef.

This will copy the entire value into the memory handled by the PoolRef, which may be slower than using PoolRef::default(), so it’s not recommended to use this to construct the default value.

§Examples

let pool: Pool<usize> = Pool::new(256);
let number = PoolRef::new(&pool, 1337);
assert_eq!(1337, *number);

Source

pub fn clone_from(pool: &Pool<A>, value: &A) -> Self
where A: PoolClone,

Clone a value and return a new PoolRef to it.

This will use PoolClone::clone_uninit() to perform the clone, which may be more efficient than using PoolRef::new(value.clone()).

§Examples

let pool: Pool<Vec<usize>> = Pool::new(1);
let vec = vec![1, 2, 3];
let ref1 = PoolRef::clone_from(&pool, &vec);
assert_eq!(vec, *ref1);

Source

pub fn pin_default(pool: &Pool<A>) -> Pin<Self>
where A: PoolDefault,

Construct a Pinned PoolRef with a default value.

§Examples

let pool: Pool<usize> = Pool::new(256);
let zero = PoolRef::pin_default(&pool);
assert_eq!(0, *zero);

Source

pub fn pin(pool: &Pool<A>, value: A) -> Pin<Self>

Construct a Pinned PoolRef with the given value.

§Examples

let pool: Pool<usize> = Pool::new(256);
let number = PoolRef::pin(&pool, 1337);
assert_eq!(1337, *number);

Source

pub fn cloned(pool: &Pool<A>, this: &Self) -> Self
where A: PoolClone,

Clone the value inside a PoolRef and return a new PoolRef to it.

This will use PoolClone::clone_uninit() to perform the clone, which may be more efficient than using PoolRef::new((*this_ref).clone()).

§Examples

let pool: Pool<usize> = Pool::new(256);
let mut number = PoolRef::new(&pool, 1337);
let other_number = PoolRef::cloned(&pool, &number);
*PoolRef::make_mut(&pool, &mut number) = 123;
assert_eq!(123, *number);
assert_eq!(1337, *other_number);

Source

pub fn make_mut<'a>(pool: &Pool<A>, this: &'a mut Self) -> &'a mut A
where A: PoolClone,

Get a mutable reference to the value inside a PoolRef, cloning it first if this PoolRef isn’t a unique reference.

§Examples

let pool: Pool<usize> = Pool::new(1);
let ref1 = PoolRef::new(&pool, 1);
let mut ref2 = ref1.clone();
*PoolRef::make_mut(&pool, &mut ref2) = 2;
assert_eq!(1, *ref1);
assert_eq!(2, *ref2);

Source

pub fn get_mut(this: &mut Self) -> Option<&mut A>

Attempt to get a mutable reference to the value inside a PoolRef.

This will produce a None if this PoolRef isn’t a unique reference to the value.

§Examples

let pool: Pool<usize> = Pool::new(128);
let mut number = PoolRef::new(&pool, 1337);
assert_eq!(1337, *number);
if let Some(number_ref) = PoolRef::get_mut(&mut number) {
    *number_ref = 123;
} else {
    panic!("Couldn't get a unique reference!");
}
assert_eq!(123, *number);

Source

pub fn try_unwrap(this: Self) -> Result<A, Self>

Attempt to unwrap the value inside a PoolRef.

If this PoolRef isn’t the only reference to the value, ownership of the PoolRef is passed back to you in the Err value.

Please note that the unwrapped value is not reclaimed by the pool when dropped.

§Examples

let pool: Pool<usize> = Pool::new(1);
let ref1 = PoolRef::default(&pool);
let ref2 = ref1.clone();
let unwrap_result = PoolRef::try_unwrap(ref1);
assert!(unwrap_result.is_err());

let pool: Pool<usize> = Pool::new(1);
let ref1 = PoolRef::new(&pool, 1337);
if let Ok(number) = PoolRef::try_unwrap(ref1) {
    assert_eq!(1337, number);
} else {
    panic!("couldn't unwrap the number after all!");
}

Source

pub fn unwrap_or_clone(this: Self) -> A
where A: PoolClone,

Unwrap the value inside a PoolRef, cloning if necessary.

If this PoolRef is a unique reference to the value, the value is unwrapped and returned, consuming the PoolRef. Otherwise, the value is cloned and the clone is returned.

Please note that the unwrapped value is not reclaimed by the pool when dropped.

§Examples

let pool: Pool<usize> = Pool::new(1);
let number = PoolRef::new(&pool, 1337);
let other_ref = number.clone();
assert_eq!(1337, PoolRef::unwrap_or_clone(other_ref));

Source

pub fn ptr_eq(left: &Self, right: &Self) -> bool

Test two PoolRefs for pointer equality.

§Examples

let pool: Pool<usize> = Pool::new(1);
let ref1 = PoolRef::default(&pool);
let ref2 = ref1.clone();
assert!(PoolRef::ptr_eq(&ref1, &ref2));

Source

pub fn strong_count(this: &Self) -> usize

Get the current number of LocalRef references to the wrapped value.

§Examples

let pool: Pool<usize> = Pool::new(1);
let ref1 = PoolRef::default(&pool);
let ref2 = ref1.clone();
let ref3 = ref2.clone();
assert_eq!(3, PoolRef::strong_count(&ref1));

Source

pub fn into_raw(b: PoolRef<A>) -> *const A

Consume the PoolRef and return a pointer to the contents.

The pointer is guaranteed to be non-null.

Please note that the only proper way to drop the value pointed to is by using PoolRef::from_raw to turn it back into a PoolRef, because the value is followed by PoolRef metadata which also needs to be dropped.

Source

pub unsafe fn from_raw(ptr: *const A) -> Self

Turn a raw pointer back into a PoolRef.

The pointer must be non-null and obtained from a previous call to PoolRef::into_raw or PoolRef::into_raw_non_null.

§Safety

This must only be called on pointers obtained through PoolRef::into_raw. It’s not OK to call it on a pointer to a value of A you’ve allocated yourself.

§Examples

let pool: Pool<usize> = Pool::new(1);
let ref1 = PoolRef::new(&pool, 31337);

// Turn the PoolRef into a raw pointer and see if it still works.
let ptr = PoolRef::into_raw(ref1);
assert_eq!(31337, unsafe { *ptr });

// Turn it back into a PoolRef and see, again, if it still works.
let ref2 = unsafe { PoolRef::from_raw(ptr) };
assert_eq!(31337, *ref2);