Struct swim_mem::lease::Ref

pub struct Ref<'a, R: Resident> { /* fields omitted */ }

A thread-safe, atomically counted, immutably dereferenceable hard reference to a Resident occupying a shared, Hold-allocated memory block.

Methods

impl<'a, R: Resident> Ref<'a, R>

pub fn try_hold_new_meta<T, M>(
    hold: &dyn Hold<'a>,
    data: T,
    meta: M
) -> Result<Ref<'a, R>, HoldError> where
    R: ResidentFromValue<Ref<'a, R>, T, M>, 

pub fn try_hold_clone_meta<T: ?Sized, M>(
    hold: &dyn Hold<'a>,
    data: &T,
    meta: M
) -> Result<Ref<'a, R>, HoldError> where
    R: ResidentFromClone<Ref<'a, R>, T, M>, 

pub unsafe fn try_hold_clone_unchecked_meta<T: ?Sized, M>(
    hold: &dyn Hold<'a>,
    data: &T,
    meta: M
) -> Result<Ref<'a, R>, HoldError> where
    R: ResidentFromCloneUnchecked<Ref<'a, R>, T, M>, 

pub fn try_hold_copy_meta<T: ?Sized, M>(
    hold: &dyn Hold<'a>,
    data: &T,
    meta: M
) -> Result<Ref<'a, R>, HoldError> where
    R: ResidentFromCopy<Ref<'a, R>, T, M>, 

pub unsafe fn try_hold_copy_unchecked_meta<T: ?Sized, M>(
    hold: &dyn Hold<'a>,
    data: &T,
    meta: M
) -> Result<Ref<'a, R>, HoldError> where
    R: ResidentFromCopyUnchecked<Ref<'a, R>, T, M>, 

pub fn try_hold_empty_meta<M>(
    hold: &dyn Hold<'a>,
    meta: M
) -> Result<Ref<'a, R>, HoldError> where
    R: ResidentFromEmpty<Ref<'a, R>, M>, 

pub fn try_hold_cap_meta<M>(
    hold: &dyn Hold<'a>,
    cap: usize,
    meta: M
) -> Result<Ref<'a, R>, HoldError> where
    R: ResidentWithCapacity<Ref<'a, R>, M>, 

pub fn try_hold_new<T>(
    hold: &dyn Hold<'a>,
    data: T
) -> Result<Ref<'a, R>, HoldError> where
    R: ResidentFromValue<Ref<'a, R>, T>, 

pub fn try_hold_clone<T: ?Sized>(
    hold: &dyn Hold<'a>,
    data: &T
) -> Result<Ref<'a, R>, HoldError> where
    R: ResidentFromClone<Ref<'a, R>, T>, 

pub unsafe fn try_hold_clone_unchecked<T: ?Sized>(
    hold: &dyn Hold<'a>,
    data: &T
) -> Result<Ref<'a, R>, HoldError> where
    R: ResidentFromCloneUnchecked<Ref<'a, R>, T>, 

pub fn try_hold_copy<T: ?Sized>(
    hold: &dyn Hold<'a>,
    data: &T
) -> Result<Ref<'a, R>, HoldError> where
    R: ResidentFromCopy<Ref<'a, R>, T>, 

pub unsafe fn try_hold_copy_unchecked<T: ?Sized>(
    hold: &dyn Hold<'a>,
    data: &T
) -> Result<Ref<'a, R>, HoldError> where
    R: ResidentFromCopyUnchecked<Ref<'a, R>, T>, 

pub fn try_hold_empty(hold: &dyn Hold<'a>) -> Result<Ref<'a, R>, HoldError> where
    R: ResidentFromEmpty<Ref<'a, R>>, 

pub fn try_hold_cap(
    hold: &dyn Hold<'a>,
    cap: usize
) -> Result<Ref<'a, R>, HoldError> where
    R: ResidentWithCapacity<Ref<'a, R>>, 

pub fn hold_new<T>(hold: &dyn Hold<'a>, data: T) -> Ref<'a, R> where
    R: ResidentFromValue<Ref<'a, R>, T>, 

pub fn hold_clone<T: ?Sized>(hold: &dyn Hold<'a>, data: &T) -> Ref<'a, R> where
    R: ResidentFromClone<Ref<'a, R>, T>, 

pub unsafe fn hold_clone_unchecked<T: ?Sized>(
    hold: &dyn Hold<'a>,
    data: &T
) -> Ref<'a, R> where
    R: ResidentFromCloneUnchecked<Ref<'a, R>, T>, 

pub fn hold_copy<T: ?Sized>(hold: &dyn Hold<'a>, data: &T) -> Ref<'a, R> where
    R: ResidentFromCopy<Ref<'a, R>, T>, 

pub unsafe fn hold_copy_unchecked<T: ?Sized>(
    hold: &dyn Hold<'a>,
    data: &T
) -> Ref<'a, R> where
    R: ResidentFromCopyUnchecked<Ref<'a, R>, T>, 

pub fn hold_empty(hold: &dyn Hold<'a>) -> Ref<'a, R> where
    R: ResidentFromEmpty<Ref<'a, R>>, 

pub fn hold_cap(hold: &dyn Hold<'a>, cap: usize) -> Ref<'a, R> where
    R: ResidentWithCapacity<Ref<'a, R>>, 

pub fn new<T>(data: T) -> Ref<'a, R> where
    R: ResidentFromValue<Ref<'a, R>, T>, 

pub fn from_clone<T: ?Sized>(data: &T) -> Ref<'a, R> where
    R: ResidentFromClone<Ref<'a, R>, T>, 

pub unsafe fn from_clone_unchecked<T: ?Sized>(data: &T) -> Ref<'a, R> where
    R: ResidentFromCloneUnchecked<Ref<'a, R>, T>, 

pub fn from_copy<T: ?Sized>(data: &T) -> Ref<'a, R> where
    R: ResidentFromCopy<Ref<'a, R>, T>, 

pub unsafe fn from_copy_unchecked<T: ?Sized>(data: &T) -> Ref<'a, R> where
    R: ResidentFromCopyUnchecked<Ref<'a, R>, T>, 

pub fn empty() -> Ref<'a, R> where
    R: ResidentFromEmpty<Ref<'a, R>>, 

pub fn with_cap(cap: usize) -> Ref<'a, R> where
    R: ResidentWithCapacity<Ref<'a, R>>, 

pub unsafe fn from_raw(data: *mut R::Data) -> Ref<'a, R>

Constructs a Ref lease from a raw pointer returned by Ref::into_raw.

pub fn hard_count(this: &Ref<'a, R>) -> usize

Returns the number of hard references to the shared resident.

pub fn soft_count(this: &Ref<'a, R>) -> usize

Returns the number of soft references to the shared resident.

pub fn ref_count(this: &Ref<'a, R>) -> usize

Returns the number of immutable references to the shared resident.

pub fn metadata<'b>(this: &'b Ref<'a, R>) -> &'b R::Meta

Returns a reference to the user-provided metadata associated with the shared resident.

pub fn try_to_unique(this: &Ref<'a, R>) -> Result<Mut<'a, R>, ArcError> where
    R::Data: TryClone,
    R::Meta: TryClone, 

Returns a mutable lease to a clone of the shared resident, returning an error on allocation failure.

pub fn to_unique(this: &Ref<'a, R>) -> Mut<'a, R> where
    R::Data: TryClone,
    R::Meta: TryClone, 

Returns a mutable lease to a clone of the shared resident

Panics

Panics on allocation failure.

pub fn try_into_unique(this: Ref<'a, R>) -> Result<Mut<'a, R>, ArcError> where
    R::Data: TryClone,
    R::Meta: TryClone, 

Converts this immutable lease into a mutable lease to the shared resident, cloning the resident if there are any outstanding mutable or immutable leases, and returning an error on allocation failure.

pub fn into_unique(this: Ref<'a, R>) -> Mut<'a, R> where
    R::Data: TryClone,
    R::Meta: TryClone, 

Converts this immutable lease into a mutable lease to the shared resident, cloning the resident if there are any outstanding mutable or immutable leases.

Panics

Panics on allocation failure.

pub unsafe fn into_mut(this: Ref<'a, R>) -> Mut<'a, R>

Converts this immutable lease into a mutable lease to the shared resident, waiting for any outstanding mutable or immutable leases to drop.

Safety

Deadlocks if the current thread already holds a mutable or immutable lease to the shared resident. Can cause a future deadlock if a thread holding a mutable lease to a resident attempts to convert another hard or soft lease to the same resident into a mutable or immutable lease.

pub fn try_to_hard(this: &Ref<'a, R>) -> Result<Hard<'a, R>, ArcError>

Returns a new hard lease to the shared resident, returning an error if the incremented hard reference count overflows HARD_COUNT_MAX.

pub fn to_hard(this: &Ref<'a, R>) -> Hard<'a, R>

Returns a new hard lease to the shared resident.

Panics

Panics if the incremented hard reference count overflows HARD_COUNT_MAX.

pub fn into_hard(this: Ref<'a, R>) -> Hard<'a, R>

Converts this immutable lease into a hard lease.

pub fn try_to_soft(this: &Ref<'a, R>) -> Result<Soft<'a, R>, ArcError>

Returns a new soft reference to the shared resident, returning an error if the incremented soft reference count overflows SOFT_COUNT_MAX.

pub fn to_soft(this: &Ref<'a, R>) -> Soft<'a, R>

Returns a new soft reference to the shared resident.

Panics

Panics if the incremented soft reference count overflows SOFT_COUNT_MAX.

pub fn try_into_soft(this: Ref<'a, R>) -> Result<Soft<'a, R>, ArcError>

Converts this immutable lease into a soft lease to the shared resident, returning an error if the incremented soft reference count overflows SOFT_COUNT_MAX.

pub fn into_soft(this: Ref<'a, R>) -> Soft<'a, R>

Converts this immutable lease into a soft lease to the shared resident.

Panics

Panics if the incremented soft reference count overflows SOFT_COUNT_MAX.

pub unsafe fn into_raw(this: Ref<'a, R>) -> *mut R::Data

Converts this immutable lease into a raw pointer to the shared resident. Use Ref::from_raw to reconstitute the returned pointer back into an immutable lease.

Safety

A memory leak will occur unless the returned pointer is eventually converted back into an immutable lease and dropped.

pub unsafe fn as_ptr_unchecked(this: &Ref<'a, R>) -> *mut R::Data

Returns a raw pointer to the shared resident.

Safety

The shared resident may be uninitialized, or mutably aliased.

pub fn try_unwrap(this: Ref<'a, R>) -> Result<R::Target, Ref<'a, R>> where
    R: ResidentUnwrap<Ref<'a, R>>, 

Consumes this immutable lease, and returns the shared resident; returns an Err containing the original lease if any outstanding hard or immutable leases prevent the resident from being moved.

pub fn unwrap(this: Ref<'a, R>) -> R::Target where
    R: ResidentUnwrap<Ref<'a, R>>, 

Consumes this immutable lease, and returns the shared resident.

Panics

Panics if any outstanding hard or immutable leases prevent the resident from being moved.

Trait Implementations

impl<'a, R: Resident> Holder<'a> for Ref<'a, R>

fn holder(&self) -> &'a dyn Hold<'a>

Returns the Hold that allocated this object.

impl<'a, R: Resident> TryClone for Ref<'a, R>

fn try_clone(&self) -> Result<Ref<'a, R>, HoldError>

Returns a clone of self; returns an error if the clone fails.

impl<'a, R: Resident> Lease for Ref<'a, R>

type Data = R::Data

The type of pointed-to data stored in leased memory blocks. The size of leased memory blocks must be a positive multiple of the Data size.

type Meta = R::Meta

The type of metadata stored with leased memory blocks. Meta data must contain sufficient information to resolve the size of any resided-in memory Lease.

fn data(&self) -> *mut R::Data

Returns a pointer to the leased memory block. The size of the pointed-to memory block is an implementation-defined multiple of the size of the Data type. The Lease makes no guarantees about the initinialization state of the pointed-to data; the resident of the Lease takes full responsibility for managing its own data.

fn meta(&self) -> *mut R::Meta

Returns a pointer to the metadata associated with the leased memory block. The Lease makes no guarantees about the initialization state of the pointed-to metadata; the resident of the Lease takes full responsibility for managing its own metadata.

impl<'a, R: ResidentPartialEq<Ref<'a, R>, T>, T: ?Sized> PartialEq<T> for Ref<'a, R>

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

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

fn ne(&self, other: &T) -> bool

This method tests for !=.

impl<'a, R: ResidentEq<Ref<'a, R>>> Eq for Ref<'a, R>

impl<'a, R: ResidentOrd<Ref<'a, R>>> Ord for Ref<'a, R>

fn cmp(&self, other: &Ref<'a, R>) -> Ordering

This method returns an Ordering between self and other.

default fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

default fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

default 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, R: ResidentPartialOrd<Ref<'a, R>, T>, T: ?Sized> PartialOrd<T> for Ref<'a, R>

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

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

fn lt(&self, other: &T) -> bool

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

fn le(&self, other: &T) -> bool

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

fn ge(&self, other: &T) -> bool

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

fn gt(&self, other: &T) -> bool

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

impl<'a, R: ResidentDeref<Ref<'a, R>>> Deref for Ref<'a, R>

type Target = R::Target

The resulting type after dereferencing.

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

Dereferences the value.

impl<'a, R: ResidentDisplay<Ref<'a, R>>> Display for Ref<'a, R>

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

Formats the value using the given formatter.

impl<'a, R: ResidentDebug<Ref<'a, R>>> Debug for Ref<'a, R>

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

Formats the value using the given formatter.

impl<'a, R: ResidentAdd<Ref<'a, R>, Rhs>, Rhs> Add<Rhs> for Ref<'a, R>

type Output = R::Output

The resulting type after applying the + operator.

fn add(self, rhs: Rhs) -> R::Output

Performs the + operation.

impl<'a, R: Resident> Drop for Ref<'a, R>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, R: ResidentIndex<Ref<'a, R>, Idx>, Idx> Index<Idx> for Ref<'a, R>

type Output = R::Output

The returned type after indexing.

fn index(&self, index: Idx) -> &R::Output

Performs the indexing (container[index]) operation.

impl<'a, R: ResidentHash<Ref<'a, R>>> Hash for Ref<'a, R>

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

Feeds this value into the given [Hasher].

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

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

impl<'a, R: Resident> Sync for Ref<'a, R> where
    R::Data: Sync,
    R::Meta: Sync, 

impl<'a, R: ResidentIntoIterator<Ref<'a, R>>> IntoIterator for Ref<'a, R>

type Item = R::Item

The type of the elements being iterated over.

type IntoIter = R::IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> R::IntoIter

Creates an iterator from a value.

impl<'a, R: ResidentIntoRefIterator<'a, Ref<'a, R>>> IntoIterator for &'a Ref<'a, R>

type Item = R::Item

The type of the elements being iterated over.

type IntoIter = R::IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> R::IntoIter

Creates an iterator from a value.

impl<'a, R: Resident> Send for Ref<'a, R> where
    R::Data: Send,
    R::Meta: Send, 

impl<'a, R: Resident> Pointer for Ref<'a, R>

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

Formats the value using the given formatter.

impl<'a, R: Resident> Clone for Ref<'a, R>

fn clone(&self) -> Ref<'a, R>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a, R: ResidentAsRef<Ref<'a, R>, T>, T: ?Sized> AsRef<T> for Ref<'a, R>

fn as_ref(&self) -> &T

Performs the conversion.