Struct cow_arc::CowArc

pub struct CowArc<T> { /* private fields */ }

A special form of an Arc reference that uses two nested Arcs to support a mechanism similar to copy-on-write or clone-on-write.

Effectively, this type reduces to Arc<Arc<Mutex<T>>>.

Unlike regular Arcs, which do not permit mutability if there are multiple strong or weak references to the data inside the Arc, the CowArc type can still allow interior mutability of the data T when there are multiple strong or weak references to it. This works by treating the inner Arc reference as the actual reference count, enabling it to differentiate between two states:

• Exclusive: only a single strong reference to the internal Arc, meaning that it is okay to mutate the data.
• Shared: there are multiple strong references to the internal Arc, meaning that it cannot be accessed mutably.

The inner data T is protected by a Mutex, allowing it to be borrowed mutably when the CowArc is in the Exclusive state only. The inner data can be borrowed immutably in either state.

This point of this data type is to encourage deeply copying data that’s in the Shared state in order to modify it, because deeply copying (cloning) Shared data will yield a new instance that starts in the Exclusive state by default.

Finally, the CowArc type can be “cloned” in two ways:

• using the regular clone function, which actually affects the shared state by duplicating the inner reference, meaning that the CowArc will be in the shared state after invoking clone,
• using the clone_shallow function, which does not affect the shared state and only duplicates the outer reference.

Implementations

impl<T> CowArc<T>

pub fn new(data: T) -> CowArc<T>

Crates a new CowArc that wraps the given data. The new CowArc will be in the Exclusive state, that is, not shared.

pub fn lock_as_ref(&self) -> DerefsTo<MutexGuard<'_, T>, T>

This acquires the lock on the inner Mutex wrapping the data T, and always succeeds because an CowArc always allows immutable access to the data, regardless of whether the data is Shared or Exclusive.

The returned value derefs to and can be used exactly like &T.

pub fn try_lock_as_ref(&self) -> Option<DerefsTo<MutexGuard<'_, T>, T>>

This attempts to acquire the lock on the inner Mutex wrapping the data T.

This returns None if the lock is currently held, but will always succeed if the lock is not held because an CowArc always allows immutable access to the data, regardless of whether the data is Shared or Exclusive.

The returned value derefs to and can be used exactly like &T.

pub fn lock_as_mut(&self) -> Option<DerefsToMut<MutexGuard<'_, T>, T>>

This acquires the lock on the inner Mutex wrapping the data T if it succeeds, which only occurs if this CowArc is in the Shared state, i.e., only a single strong reference to the inner Arc is held.

The returned value derefs to and can be used exactly like &mut T.

pub fn downgrade(this: &CowArc<T>) -> CowWeak<T>

Downgrades this CowArc into a CowWeak weak reference.

pub fn is_shared(&self) -> bool

Returns true if this CowArc is in the Shared state, and false if it is in the Exclusive state.

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

Returns true if the two CowArcs point to the same value (not just values that compare as equal).

pub fn clone_shallow(&self) -> CowArc<T>

Creates a shallow clone of this CowArc that does not affect its Shared state. This means that it will not change it to Shared if it was Exclusive, nor will it increase the shared count if it was already Shared`.

Likewise, dropping the returned reference will not decrement the shared count nor potentially change its state from Shared back to Exclusive.

This is useful for passing around a duplicate reference to the same instance (of the outer reference) that will be used somewhere else temporarily, e.g., in the same context, without marking it as a totally separate shared instance.

The fact that this is different from the CowArc::clone function is what differentiates the behavior of CowArc from regular Arc.

Trait Implementations

impl<T> Clone for CowArc<T>

fn clone(&self) -> CowArc<T>

Creates a shared reference to this CowArc and returns that shared reference as a new CowArc whose internal reference points to the same data.

This increases the shared count of this CowArc, and the returned new CowArc instance will have the same shared count and reference the same data.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for CowArc<T>

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

Formats the value using the given formatter.