Struct refpool::PoolRef

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

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

Implementations

impl<A> PoolRef<A>

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);

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);

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);

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);

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);

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);

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);

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);

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!");
}

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));

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));

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));

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.

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);

Trait Implementations

impl<A> AsRef<A> for PoolRef<A>

fn as_ref(&self) -> &A

Performs the conversion.

impl<A> Borrow<A> for PoolRef<A>

fn borrow(&self) -> &A

Immutably borrows from an owned value.

impl<A> Clone for PoolRef<A>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<A> Debug for PoolRef<A> where
    A: Debug, 

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

Formats the value using the given formatter.

impl<A> Deref for PoolRef<A>

type Target = A

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<A> Display for PoolRef<A> where
    A: Display, 

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

Formats the value using the given formatter.

impl<A> Drop for PoolRef<A>

fn drop(&mut self)

Executes the destructor for this type.

impl<A> Eq for PoolRef<A> where
    A: Eq, 

impl<A> Hash for PoolRef<A> where
    A: Hash, 

fn hash<H: Hasher>(&self, hasher: &mut H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl<A> Ord for PoolRef<A> where
    A: Ord, 

fn cmp(&self, other: &Self) -> Ordering

This method returns an [Ordering] between self and other.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<A> PartialEq<PoolRef<A>> for PoolRef<A> where
    A: PartialEq, 

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A> PartialOrd<PoolRef<A>> for PoolRef<A> where
    A: PartialOrd, 

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<A> Pointer for PoolRef<A>

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

Formats the value using the given formatter.