Module swim_mem::lease

Memory ownership and access model.

Leases

A Lease abstracts over the allocation and ownership semantics of a raw, unsized memory block. Most Lease implementations compose a Resident, type, which abstracts over the usage of the leased memory block.

The most commonly used Lease implementations include:

• Raw: the exclusive owner of a relocatable, raw memory block, with resident metadata stored with the pointer.
• Ptr: the exclusive owner of a relocatable memory block, with resident metadata stored within the allocation.
• Mut: a mutably dereferenceable strong owner of an unrelocatable, reference counted memory block.
• Ref: an immutably dereferenceable strong owner of an unrelocatable, reference counted memory block.
• Hard: an undereferenceable strong owner of a relocatable, reference counted memory block.
• Soft: an undereferenceable weak owner of a relocatable, reference counted memory block.

Commonly composed Resident implementations include:

• Box: stores a single value in a leased memory block.
• Buf: stores a resizeable array of values in a leased memory block.
• String: stores a resizeable Unicode string in a leased memory block.

Lease residents

Lease implementations conditionally implement core Rust traits, such as Deref, Eq, and Hash, dependent upon whether a Lease's parameterized Resident type implements corresponding Resident* traits, like ResodentDeref, ResidentEq, and ResidentHash, respectively. These Resident* proxy traits differ from their corresponding core Rust traits in that they take a Lease type in lieu of a Self type as their first argument. Implementations of the Resident* proxy traits often convert their Lease argument into some concrete reference type, and then delegate to that type's implementation of the corresponding core Rust trait.

For example, the Lease type Raw<R: Resident> implements Hash if and only if R implements ResidentHash. Furthermore, the Resident type Box<T> implements ResidentHash if and only if T implemenets Hash. Consequently, the composed type Raw<Box<T>> transitively implements Hash if and only if T implements Hash. The ResidentHash indirection effectively dereferences the Lease into a reference to type T.

Indirection through Resident* proxy traits typically has zero cost; each trait is specialized by a concrete Lease type, and its methods get frequently inlined.

Raw leases

A Raw lease represents an exclusive reference to the Resident stored in its memory block. Similar to Rust's std::boxed::Box, a Raw lease is not reference counted, and stores no metadata on the heap. Raw leases can be freely dereferenced. And resident metadata, such as the BufHeader associated with every Buf resident, is stored directly in the Raw struct, similar to how std::vec::Vec stores its length and capacity in the Vec struct, rather than on the heap.

Type aliases for Raw leases with common Resident types include:

• RawBox: an exclusively owned value.
• RawBuf: an exclusively owned resizeable array of values.
• RawString: an exclusively owned resizeable Unicode string.

Structs

ArcHeader	Atomic reference counting metadata.
Hard	A thread-safe, atomically counted, undereferenceable hard reference to a Resident occuping a shared, Hold-allocated memory block.
Mut	A thread-safe, atomically counted, mutably dereferenceable hard reference to a Resident occupying a shared, Hold-allocated memory block.
Ptr	An exclusive reference to a Resident occupying an owned, Hold-allocated memory block, with resident metadata stored within the allocation.
Raw	An exclusive reference to a Resident occupying an owned, Hold-allocated memory block, with resident metadata stored with the pointer.
Ref	A thread-safe, atomically counted, immutably dereferenceable hard reference to a Resident occupying a shared, Hold-allocated memory block.
Soft	A thread-safe, atomically counted, undereferenceable soft reference to a Resident occupying a shared, Hold-allocated memory block.

Enums

Arc	Polymorphic, atomically reference counted lease.
ArcError	Atomic reference counting error.

Constants

HARD_COUNT_MAX	Maximum number of hard references per lease. A Mut, Ref, or Hard lease each holds its own hard reference to its pointed-to arc.
REF_COUNT_MAX	Maximum number of immutable references per lease. A Ref leases hold an immutable reference to its pointed-to arc.
SOFT_COUNT_MAX	Maximum number of soft references per lease. A Soft lease holds a soft softreference to its pointed-to arc. A Mut, Ref, or Hard lease temporarily acquire a soft reference when it drops, if it holds the last hard reference to its arc, and outstanding soft references remain.

Traits

DynamicLease	A resizeable memory Lease.
Lease	A raw memory block, with associated metadata. A memory Lease abstracts over the ownership semantics of a raw, unsized memory block.

Type Definitions

HardBox	Undereferenceable strong owner of a value stored in a Hold-allocated, atomically reference counted memory block.
HardBuf	Undereferenceable strong owner of a resizeable array of values stored in a Hold-allocated, atomically reference counted memory block.
HardString	Undereferenceable strong owner of a resizeable Unicode string stored in a Hold-allocated, atomically reference counted memory block.
MutBox	Mutably dereferenceable strong owner of a value stored in a Hold-allocated, atomically reference counted memory block.
MutBuf	Mutably dereferenceable strong owner of a resizeable array of values stored in a Hold-allocated, atomically reference counted memory block.
MutString	Mutably dereferenceable strong owner of a resizeable Unicode string stored in a Hold-allocated, atomically reference counted memory block.
PtrBox	Exclusive reference to a value stored in a Hold-allocated memory block, with optional metadata stored inside the allocation.
PtrBuf	Exclusive reference to a resizeable array of values stored in a Hold-allocated memory block, with buffer length and capacity metadata stored inside the allocation.
PtrString	Exclusive reference to a resizeable Unicode string stored in a Hold-allocated memory block, with string length and capacity metadata stored inside the allocation.
RawBox	Exclusive reference to a value stored in a Hold-allocated memory block, with optional metadata stored alongside the pointer.
RawBuf	Exclusive reference to a resizeable array of values stored in a Hold-allocated memory block, with buffer length and capacity metadata stored alongside the pointer.
RawString	Exclusive reference to a resizeable Unicode string stored in a Hold-allocated memory block, with string length and capacity metadata stored alongside the pointer.
RefBox	Immutably dereferenceable strong owner of a value stored in a Hold-allocated, atomically reference counted memory block.
RefBuf	Immutably dereferenceable strong owner of a resizeable array of values stored in a Hold-allocated, atomically reference counted memory block.
RefString	Immutably dereferenceable strong owner of a resizeable Unicode string stored in a Hold-allocated, atomically reference counted memory block.
SoftBox	Undereferenceable weak owner of a value stored in a Hold-allocated, atomically reference counted memory block.
SoftBuf	Undereferenceable weak owner of a resizeable array of values stored in a Hold-allocated, atomically reference counted memory block.
SoftString	Undereferenceable weak owner of a resizeable Unicode string stored in a Hold-allocated, atomically reference counted memory block.