# [−][src]Module crossbeam::epoch

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.

# Pointers

Concurrent collections are built using atomic pointers. This module provides `Atomic`, which 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 read.

# Pinning

Before an `Atomic` can be loaded, a participant must be `pin`ned. 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 unpinned.

# Garbage

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.

# APIs

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 `Collector` API.

## Structs

Atomic | An atomic pointer that can be safely shared between threads.
Collector | An epoch-based garbage collector.
CompareAndSetError | The error returned on failed compare-and-set operation.
Guard | A guard that keeps the current thread pinned.
LocalHandle | A handle to a garbage collector.
Owned | An owned heap-allocated object.
Shared | A pointer to an object protected by the epoch GC.

## Traits

CompareAndSetOrdering | Memory orderings for compare-and-set operations.
Pointer | A trait for either `Owned` or `Shared` pointers.

## Functions

default_collector | Returns the default global collector.
is_pinned | Returns `true` if the current thread is pinned.
pin | Pins the current thread.
unprotected⚠ | Returns a reference to a dummy guard that allows unprotected access to `Atomic`s.

# Help

## Keyboard Shortcuts

`?`
  Show this help dialog
`S`
  Focus the search field
`↑`
  Move up in search results
`↓`
  Move down in search results
`↹`
  Switch tab
`⏎`
  Go to active search result
`+`
  Expand all sections
`-`
  Collapse all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g., `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g., `vec -> usize` or `* -> vec`)

Search multiple things at once by splitting your query with comma (e.g., `str,u8` or `String,struct:Vec,test`)