Epoch-based memory reclamation.
An interesting problem concurrent collections deal with comes from the remove operation. Suppose that a thread removes an element from a lock-free map, while another thread is reading that same element at the same time. The first thread must wait until the second thread stops reading the element. Only then it is safe to destruct it.
Programming languages that come with garbage collectors solve this problem trivially. The garbage collector will destruct the removed element when no thread can hold a reference to it anymore.
This crate implements a basic memory reclamation mechanism, which is based on epochs. When an element gets removed from a concurrent collection, it is inserted into a pile of garbage and marked with the current epoch. Every time a thread accesses a collection, it checks the current epoch, attempts to increment it, and destructs some garbage that became so old that no thread can be referencing it anymore.
That is the general mechanism behind epoch-based memory reclamation, but the details are a bit more complicated. Anyhow, memory reclamation is designed to be fully automatic and something users of concurrent collections don’t have to worry much about.
Concurrent collections are built using atomic pointers. This module provides
is just a shared atomic pointer to a heap-allocated object. Loading an
Atomic yields a
Shared, which is an epoch-protected pointer through which the loaded object can be safely
Atomic can be loaded, a participant must be
pinned. By pinning a participant
we declare that any object that gets removed from now on must not be destructed just
yet. Garbage collection of newly removed objects is suspended until the participant gets
Objects that get removed from concurrent collections must be stashed away until all currently pinned participants get unpinned. Such objects can be stored into a thread-local or global storage, where they are kept until the right time for their destruction comes.
There is a global shared instance of garbage queue. You can
defer the execution of an
arbitrary function until the global epoch is advanced enough. Most notably, concurrent data
structures may defer the deallocation of an object.
For majority of use cases, just use the default garbage collector by invoking
pin. If you
want to create your own garbage collector, use the
An atomic pointer that can be safely shared between threads.
An epoch-based garbage collector.
The error returned on failed compare-and-swap operation.
A guard that keeps the current thread pinned.
A handle to a garbage collector.
An owned heap-allocated object.
A pointer to an object protected by the epoch GC.
Memory orderings for compare-and-set operations.
Types that are pointed to by a single word.
A trait for either
Returns the default global collector.
true if the current thread is pinned.
Pins the current thread.
Returns a reference to a dummy guard that allows unprotected access to
The error returned on failed compare-and-set operation.