Crate trc

Trc is a performant heap-allocated smart pointer that implements a thread reference counting. Trc stands for: Thread Reference Counted. Trc provides shared ownership of the data similar to Arc<T> and Rc<T>. It implements thread reference counting, which is based on the observation that most objects are only used by one thread. This means that two reference counts can be created: one for local thread use, and one atomic one for sharing between threads. Thread reference counting sets the atomic reference count to the number of threads using the data.

Breaking reference cycles with Weak<T>

A cycle between Trc pointers cannot be deallocated as the reference counts will never reach zero. The solution is a Weak<T>. A Weak is a non-owning reference to the data held by a Trc. They break reference cycles by adding a layer of indirection and act as an observer. They cannot access the data directly, and must be converted back into Trc. Weak does not keep the value alive (which can be dropped), and only keeps the backing allocation alive.

Sending data across threads with SharedTrc<T>

To soundly implement thread safety Trc<T> is !Send and !Sync. To solve this, Trc introduces a SharedTrc<T>, which is Send and Sync. SharedTrc is the only way to safely send a Trc’s data across threads without using a Weak.

Because Trc is not part of the standard library, the CoerceUnsized and Receiver traits cannot currently be implemented by default. However, Trc provides dyn_unstable trait which enables the above traits for Trc and SharedTrc and must be used with nightly Rust (cargo +nightly ...).

Structs

• SharedTrc
  SharedTrc is a thread-safe wrapper used to send Trcs across threads. Unlike Trc (which is !Send and !Sync), SharedTrc is Send and Sync. This means that along with Weak, SharedTrc is one of the ways to send a Trc across threads. However, unlike Weak, SharedTrc does not modify the weak count - and only modifies the atomic count. In addition, SharedTrc will not fail on conversion back to a Trc because it prevents the data T from being dropped.
• Trc
  Trc is a performant heap-allocated smart pointer that implements thread reference counting. Trc stands for: Thread Reference Counted. Trc provides shared ownership of the data similar to Arc<T> and Rc<T>. It implements thread reference counting, which is based on the observation that most objects are only used by one thread. This means that two reference counts can be created: one for local thread use, and one atomic one for sharing between threads. Thread reference counting sets the atomic reference count to the number of threads using the data.
• Weak
  Weak is a non-owning reference to Trc’s data. It is used to prevent cyclic references which cause memory to never be freed. Weak does not keep the value alive (which can be dropped), they only keep the backing allocation alive. Weak cannot directly access the data, and must be converted into Trc to do so.