Module crossbeam_epoch::internal

The global data and participant for garbage collection.

Registration

In order to track all participants in one place, we need some form of participant registration. When a participant is created, it is registered to a global lock-free singly-linked list of registries; and when a participant is leaving, it is unregistered from the list.

Pinning

Every participant contains an integer that tells whether the participant is pinned and if so, what was the global epoch at the time it was pinned. Participants also hold a pin counter that aids in periodic global epoch advancement.

When a participant is pinned, a Guard is returned as a witness that the participant is pinned. Guards are necessary for performing atomic operations, and for freeing/dropping locations.

Thread-local bag

Objects that get unlinked from concurrent data structures must be stashed away until the global epoch sufficiently advances so that they become safe for destruction. Pointers to such objects are pushed into a thread-local bag, and when it becomes full, the bag is marked with the current global epoch and pushed into the global queue of bags. We store objects in thread-local storages for amortizing the synchronization cost of pushing the garbages to a global queue.

Global queue

Whenever a bag is pushed into a queue, the objects in some bags in the queue are collected and destroyed along the way. This design reduces contention on data structures. The global queue cannot be explicitly accessed: the only way to interact with it is by calling functions defer() that adds an object to the thread-local bag, or collect() that manually triggers garbage collection.

Ideally each instance of concurrent data structure may have its own queue that gets fully destroyed as soon as the data structure gets dropped.

Structs

• Bag 🔒
  A bag of deferred functions.
• Global 🔒
  The global data for a garbage collector.
• Local 🔒
  Participant for garbage collection.
• SealedBag 🔒
  A pair of an epoch and a bag.

Constants

• MAX_OBJECTS 🔒
  Maximum number of objects a bag can contain.