Crate backdrop_arc

BackdropArc

An Arc (atomically reference counted smart pointer) that supports customized dropping strategies using backdrop.

Arc<T, BackdropStrategy> works very much like a std::sync::Arc<T>, except for two differences:

1. Drop strategies

When the last clone of a particular Arc goes out of scope, rather than dropping normally, the particular BackdropStrategy is invoked. This way, dropping large or complex structures can be done in a background thread, background tokio task, delayed until later, etc.

This allows better reasoning about how long code using an Arc will take, since this is no longer dependent on ‘do I own the last Arc or not?’. An backdrop_arc::Arc<T, S> behaves much like a Arc<backdrop::Backdrop<Box<T>, S>>, in that the backdrop strategy is executed when the last Arc clone goes out of scope. The difference with Arc<backdrop::Backdrop<Box<T>, S>> is that there is no double pointer-indirection (arc -> box -> T), managing the allocated T is done directly in the Arc.

2. No weak pointers => smaller arcs, predictable cleanup

std::sync::Arc<T> allows the usage of weak pointers. This is very helpful internally in self-referential structures (trees, graphs) but frequently not needed. On the other hand, weak pointers are not ‘free’:

• They make every Arc instance bigger (3 words instead of 2), since instead of storing (ptr, reference_count) they need to store (ptr, reference_count, weak_reference_count).
• They make dropping an Arc<T> more complex. The ‘drop glue’ of T will run once the last strong reference goes out of scope. But to not make Weak pointers dangle, the deallocation of T only happens when the last Weak pointer goes out of scope (see here). As you can imagine, this ‘two part drop’ interacts badly with BackdropStrategy where we want to e.g. move objects to a background thread on drop, because we need to make sure that the allocation of T lives long enough.

Therefore, backdrop_arc is modeled on the excellent triomphe library. Converting a Arc to and from a triomphe::Arc is a zero-cost operation, as the two types are guaranteed to have the same representation in memory. (The same holds true for UniqueArc <-> triomphe::UniqueArc)

Not supporting weak pointers enables a bunch of other features:

• Arc does not need any read-modify-update operations to handle the possibility of weak references.
• UniqueArc allows one to construct a temporarily-mutable Arc which can be converted to a regular Arc later.
• OffsetArc can be used transparently from C++ code and is compatible with (and can be converted to/from) Arc.
• ArcBorrow is functionally similar to &backdrop_arc::Arc<T>, however in memory it’s simply &T. This makes it more flexible for FFI; the source of the borrow need not be an Arc pinned on the stack (and can instead be a pointer from C++, or an OffsetArc). Additionally, this helps avoid pointer-chasing.
• Arc has can be constructed for dynamically-sized types via from_header_and_iter
• ArcUnion is union of two Arcs which fits inside one word of memory

Features

• backdrop_arc supports no_std environments, as long as alloc is available, by disabling the (enabled by default) std feature.
• serde: Enables serialization/deserialization with the serde crate.
• stable_deref_trait: Implements the StableDeref trait from the stable_deref_trait crate for Arc.
• arc-swap: Use Arc together with the arc-swap crate.
• triomphe: Convert (zero-cost) between triomphe::Arc <-> Arc (and UniqueArc <-> triomphe::UniqueArc).
• unsize use Arc together with the unsize crate.
• yoke: Implements the CloneableCart trait from the the yoke crate for Arc, making it easier to use in zero-copy serialization scenarios.

Attribution

The source code of backdrop_arc is very heavily based on (and originally a fork of) triomphe, which itself originates from servo_arc.

Modules

thread

Structs

Arc

An atomically reference counted shared pointer

ArcBorrow

A “borrowed Arc”. This is a pointer to a T that is known to have been allocated within an Arc.

ArcCloneIter

Iterator type to give out many clones an arc without the overhead of calling clone every time.

ArcInner

The internal object allocated by an Arc<T, S>.

ArcUnion

A tagged union that can represent Arc<A> or Arc<B> while only consuming a single word. The type is also NonNull, and thus can be stored in an Option without increasing size.

Backdrop

Wrapper to drop any value at a later time, such as in a background thread.

DebugStrategy

‘Wrapper’ strategy that prints out T when executed.

HeaderSlice

Structure to allow Arc-managing some fixed-sized data and a variably-sized slice in a single allocation.

HeaderWithLength

Header data with an inline length. Consumers that use HeaderWithLength as the Header type in HeaderSlice can take advantage of ThinArc.

LeakStrategy

Strategy which will leak the contained value rather than dropping it.

OffsetArc

An Arc, except it holds a pointer to the T instead of to the entire ArcInner.

ThreadStrategy

Strategy which drops the contained value in a newly spawned background thread.

TrashQueueStrategy

Strategy which adds garbage to a global ‘trash VecDeque’.

TrashThreadStrategy

Strategy which sends any to-be-dropped values to a dedicated ‘trash thread’

TrivialStrategy

Strategy which drops the contained value normally.

UniqueArc

An Arc that is known to be uniquely owned

Enums

ArcUnionBorrow

This represents a borrow of an ArcUnion.

Traits

BackdropStrategy

The strategy to use to drop T.

Type Aliases

LeakBackdrop

ThreadBackdrop

Convenient alias for a Backdrop that uses the ThreadStrategy

TrashThreadBackdrop

Convenient alias for a Backdrop that uses the TrashThreadStrategy

TrivialBackdrop