Struct swim_mem::lease::Soft

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

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

Methods

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

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

Constructs a Soft lease from a raw pointer returned by Soft::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 unsafe fn poll_mut(&self) -> Result<Mut<'a, R>, ArcError>

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

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 moves, waiting for any concurrent relocation to complete and for any outstanding mutable or immutable leases to drop, and returning an error if the shared resident has already been dropped, or if obtaining the lease would cause a reference count overflow.

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 moves, 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 shared resident has already been dropped, or if obtaining the lease would cause a reference count overflow.

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

Converts this soft lease into a mutable lease to the shared resident, traversing any completed moves, waiting for any concurrnet relocation to complete and for any outstanding mutable or immutable leases to drop, and returning an error if the shared resident has already been dropped, or if obtaining the lease would cause a reference count overflow.

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 soft lease into a mutable lease to the shared resident, traversing any completed moves, waiting for any concurrnet relocation to complete and for any outstanding mutable or immutable leases to drop, and returning an error if the shared resident has already been dropped, or if obtaining the lease would cause a reference count overflow.

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 shared resident has already been dropped, or if obtaining the lease would cause a reference count overflow.

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

Returns a new immutable lease to the shared resident, traversing any completed moves, and returning an error if the resident is currently being relocated, or if there is an outstanding mutable lease, or if the shared resident has already been dropped, 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 moves, waiting for any concurrent relocation to complete and for any outstanding mutable lease to drop, and returning an error if the shared resident has already been dropped, or if obtaining the lease would cause a reference count overflow.

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

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

Panics

Panics if the shared resident has already been dropped, or if obtaining the lease would cause a reference count overflow.

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

Converts this soft lease into an immutable lease to the shared resident, traversing any completed moves, waiting for any concurrent relocation to complete and for any outstanding mutable lease to drop, and returning an error if the shared resident has already been dropped, or if obtaining the lease would cause a reference count overflow.

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

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

Panics

Panics if the shared resident has already been dropped, or if obtaining the lease would cause a reference count overflow.

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

Returns a new hard lease to the shared resident, without traversing any moves, returning an error if the shared resident has already been dropped or if obtaining the lease would cause a reference count overflow.

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

Returns a new hard lease to the shared resident, without traversing any moves.

Panics

Panics if the shared resident has already been dropped or if obtaining the lease would cause a reference count overflow.

pub fn try_into_hard(self) -> Result<Hard<'a, R>, ArcError>

Converts this soft lease into a hard lease, without traversing any moves, returning an error if the shared resident has already been dropped, or if obtaining the lease would cause a reference count overflow.

pub fn into_hard(self) -> Hard<'a, R>

Converts this soft lease into a hard lease, without traversing any moves.

Panics

Panics if the shared resident has already been dropped, or if obtaining the lease would cause a reference count overflow.

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

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

Safety

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

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 relocated, or dropped.

Trait Implementations

impl<'a, R: Resident> Holder<'a> for Soft<'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, Soft<'b, R>> for Soft<'a, R>

unsafe fn stow(
    src: *mut Soft<'a, R>,
    dst: *mut Soft<'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 Soft<'a, R>, dst: *mut Soft<'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 Soft<'a, R>

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

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

impl<'a, R: Resident> Lease for Soft<'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: Resident> Drop for Soft<'a, R>

fn drop(&mut self)

Executes the destructor for this type.

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

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

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

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

Formats the value using the given formatter.

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.