Struct swim_mem::lease::Hard

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

A thread-safe, atomically counted, undereferenceable hard reference to a Resident occuping a shared, Hold-allocated memory block.

Methods

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

pub fn hard_count(&self) -> usize

Returns the number of hard references to the shared resident. Does not traverse relocations.

pub fn soft_count(&self) -> usize

Returns the number of soft references to the shared resident. Does not traverse relocations.

pub fn ref_count(&self) -> usize

Returns the number of immutable references to the shared resident. Does not traverse relocations.

pub fn is_mut(&self) -> bool

Returns true if the shared resident is mutably referenced. Does not traverse relocations.

pub fn is_relocated(&self) -> bool

Returns true if the shared resident has relocated to a new arc.

pub fn is_aliased(&self) -> bool

Returns true if the shared resident is immutably or mutably referenced. Does not traverse relocations.

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

Returns a mutable lease to the resident, traversing any completed relocations, cloning the resident if there are any outstanding leases, and returning an error if there is an outstanding mutable lease, if the resident is currently being relocated, or on allocation failure.

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

Returns a mutable lease to the resident, traversing any completed relocations, waiting for any concurrent relocation to complete, cloning the resident if there are any outstanding leases, and returning an error on allocation failure or hard refcount overflow.

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

Returns a mutable lease to the resident, traversing any completed relocations, waiting for any concurrent relocation to complete, and cloning the resident if there are any outstanding leases.

Panics

Panics on allocation failure or hard refcount overflow.

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

Converts this hard lease into a mutable lease to the resident, traversing any completed relocations, waiting for any concurrent relocations to complete, cloning the resident if there are any outstanding leases, and returning an error on allocation failure.

Panics

Panics if the incremented hard reference count overflows HARD_COUNT_MAX, or if the incremented reference count overflows REF_COUNT_MAX.

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

Converts this hard lease into a mutable lease to the resident, traversing any completed relocations, waiting for any concurrent relocations to complete, and cloning the resident if there are any outstanding leases.

Panics

Panics on allocation failure.

pub unsafe fn poll_mut(&self) -> Result<Mut<'a, R>, ArcError>

Returns a new mutable lease to the shared resident, traversing any complered relocations, and returning an error if the resident is currently being relocated, if there is an outstanding mutable lease, or if there is atomic operation contention.

Safety

Mutable leases can coexist with hard and soft leases to the same resident. This 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 unsafe fn try_to_mut(&self) -> Result<Mut<'a, R>, ArcError>

Returns a new mutable lease to the shared resident, traversing any completed relocations, waiting for any concurrent relocation to complete and for any outstanding mutable or immutable leases to drop, and returning an error if the incremented hard reference count overflows HARD_COUNT_MAX.

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 unsafe fn to_mut(&self) -> Mut<'a, R>

Returns a new mutable lease to the shared resident, traversing any completed relocations, and waiting for any concurrent relocation to complete and 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.

Panics

Panics if the incremented hard reference count overflows HARD_COUNT_MAX.

pub unsafe fn try_into_mut(self) -> Result<Mut<'a, R>, ArcError>

Converts this hard lease into a mutable lease to the shared resident, traversing any completed relocations, waiting for any concurrent relocations to complete and for any outstanding mutable or immutable leases to drop, and returning an error if an incremented hard reference count overflows HARD_COUNT_MAX.

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 unsafe fn into_mut(self) -> Mut<'a, R>

Converts this hard lease into a mutable lease to the shared resident, traversing any completed relocations, and waiting for any concurrent relocations to complete and 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.

Panics

Panics if an incremented hard reference count overflows HARD_COUNT_MAX.

pub fn poll_ref(&self) -> Result<Ref<'a, R>, ArcError>

Returns a new immutable lease to the shared resident, traversing any completed relocations, and returning an error if the reisdent is currently being relocated, or if there is an outstanding mutable lease, or if there is atomic operation contention, or if obtaining the lease would cause a reference count overflow.

pub fn try_to_ref(&self) -> Result<Ref<'a, R>, ArcError>

Returns a new immutable lease to the shared resident, traversing any completed relocations, waiting for any concurrent relocation to complete and for any outstanding mutable lease to drop, and returning an error if the incremented hard reference count overflows HARD_COUNT_MAX, or if the incremented reference count overflows REF_COUNT_MAX.

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

Returns a new immutable lease to the shared resident, traversing any completed relocations, waiting for any concurrent relocation to complete, and for any outstanding mutable lease to drop.

Panics

Panics if the incremented hard reference count overflows HARD_COUNT_MAX, or if the incremented reference count overflows REF_COUNT_MAX.

pub fn try_into_ref(self) -> Result<Ref<'a, R>, ArcError>

Converts this hard lease into an immutable lease to the shared resident, traversing any completed relocations, waiting for any concurrent relocation to complete and for any outstanding mutable leases to drop, and returning an error if the incremented hard reference count overflows HARD_COUNT_MAX, or if the incremented immutable reference count overflows REF_COUNT_MAX.

pub fn into_ref(self) -> Ref<'a, R>

Converts this hard lease into an immutable lease to the shared resident, traversing any completed relocations, and waiting for any concurrent relocation to complete and for any outstanding mutable leases to drop.

Panics

Panics if the incremented hard reference count overflows HARD_COUNT_MAX, or if the incremented reference count overflows REF_COUNT_MAX.

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

Returns a new soft lease to the shared resident, without traversing any relocations, returning an error if the incremented soft reference count overflows SOFT_COUNT_MAX.

pub fn to_soft(&self) -> Soft<'a, R>

Returns a new soft lease to the shared resident, without traversing any relocations.

Panics

Panics if the incremented soft reference count overflows SOFT_COUNT_MAX.

pub fn try_into_soft(self) -> Result<Soft<'a, R>, ArcError>

Converts this hard lease into a soft lease to the shared resident, without traversing any relocations, returning an error if the incremented soft reference count overflows SOFT_COUNT_MAX.

pub fn into_soft(self) -> Soft<'a, R>

Converts this hard lease into a soft lease to the shared resident, without traversing any relocations.

Panics

Panics if the incremented soft reference count overflows SOFT_COUNT_MAX.

pub unsafe fn into_raw(self) -> *mut R::Data

Converts this hard lease into a raw pointer to the shared resident. Use Hard::from_raw to reconstitute the returned pointer back into a hard lease.

Safety

The shared resident is not pinned to the returned memory address, and may be concurrently relocated at any time. A memory leak will occur unless the returned pointer is eventually converted back into a hard lease and dropped.

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

Returns an immutable lease to the shared resident, traversing any completed moves, without waiting.

Panics

Panics if the the shared resident is mutably aliased.

pub unsafe fn as_ptr_unchecked(&self) -> *mut R::Data

Returns a raw pointer to the shared resident.

Safety

The shared resident may be uninitialized, or mutably aliased, or may have been have relocated.

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

Consumes this hard lease, traversing any completed relocations, and returns the shared resident; returns an error if there are any outstanding hard, mutable, or immutable leases.

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

Consumes this hard lease, traversing any completed relocations, and returns the shared resident.

Panics

Panics if there are any outstanding hard, mutable, or immutable leases.

Trait Implementations

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

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

Returns the Hold that allocated this object.

impl<'a, 'b, R: ResidentStow<'b, Hard<'a, R>, Hard<'b, R>>> Stow<'b, Hard<'b, R>> for Hard<'a, R>

unsafe fn stow(
    src: *mut Hard<'a, R>,
    dst: *mut Hard<'b, R>,
    hold: &dyn Hold<'b>
) -> Result<(), HoldError>

Moves the value at the src pointer to the dst pointer, recursively moving all child values into the hold. If a child stow operation fails, then any already completed child stow operations get reverted by calling unstow on the child.

unsafe fn unstow(src: *mut Hard<'a, R>, dst: *mut Hard<'b, R>)

Reverts the most recent stow operation by moving the value at the dst pointer back to the src pointer from whence it came. The memory at the src address will be in the same state the stow operation left it in.

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

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

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

impl<'a, R: Resident> Lease for Hard<'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: ResidentDisplay<Ref<'a, R>>> Display for Hard<'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 Hard<'a, R>

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

Formats the value using the given formatter.

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

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, R: ResidentHash<Ref<'a, R>>> Hash for Hard<'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 Hard<'a, R> where
    R::Data: Sync,
    R::Meta: Sync, 

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

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

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

Formats the value using the given formatter.

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.