PMDK C++ bindings  1.13.0-git85.g2ab46040
This is the C++ bindings documentation for PMDK's libpmemobj.
pmem::detail::ebr Class Reference

Epoch-based reclamation (EBR). More...

#include <libpmemobj++/detail/ebr.hpp>

Public Member Functions

 ebr ()
 Default and only ebr constructor.
 
worker register_worker ()
 Registers and returns a new worker, which can perform critical operations (accessing some shared data that can be removed in other threads). More...
 
bool sync ()
 Attempts to synchronise and announce a new epoch. More...
 
void full_sync ()
 Perform full synchronisation ensuring that all objects which are no longer globally visible (and potentially staged for reclamation) at the time of calling this routine will be safe to reclaim/destroy after this synchronisation routine completes and returns. More...
 
size_t staging_epoch ()
 Returns the epoch where objects can be staged for reclamation. More...
 
size_t gc_epoch ()
 Returns the epoch available for reclamation, i.e. More...
 

Detailed Description

Epoch-based reclamation (EBR).

Any workers (threads or processes) actively referencing (accessing) the globally visible objects must do that in the critical path covered using the dedicated function. The grace period is determined using "epochs" implemented as a global counter (and, for example, a dedicated G/C list for each epoch). Objects in the current global epoch can be staged for reclamation (garbage collection). Then, the objects in the target epoch can be reclaimed after two successful increments of the global epoch. Only three epochs are needed (e, e-1 and e-2), therefore we use clock arithmetic.

See also
K. Fraser, Practical lock-freedom, Technical Report UCAM-CL-TR-579, February 2004

Member Function Documentation

◆ full_sync()

void pmem::detail::ebr::full_sync ( )

Perform full synchronisation ensuring that all objects which are no longer globally visible (and potentially staged for reclamation) at the time of calling this routine will be safe to reclaim/destroy after this synchronisation routine completes and returns.

Note: the synchronisation may take across multiple epochs.

◆ gc_epoch()

size_t pmem::detail::ebr::gc_epoch ( )

Returns the epoch available for reclamation, i.e.

the epoch where it is guaranteed that the objects are safe to be reclaimed/destroyed. Note that this function would normally be serialized together with the ebr::sync() calls.

Returns
the epoch available for reclamation.

◆ register_worker()

ebr::worker pmem::detail::ebr::register_worker ( )

Registers and returns a new worker, which can perform critical operations (accessing some shared data that can be removed in other threads).

There can be only one worker per thread. The worker will be automatically unregistered in the destructor.

Exceptions
runtime_errorif there is already a registered worker for the current thread.
Returns
new registered worker.

◆ staging_epoch()

size_t pmem::detail::ebr::staging_epoch ( )

Returns the epoch where objects can be staged for reclamation.

This can be used as a reference value for the pending queue/tag, used to postpone the reclamation until this epoch becomes available for G/C. Note that this function would normally be serialized together with the ebr::sync() calls.

Returns
the epoch where objects can be staged for reclamation.

◆ sync()

bool pmem::detail::ebr::sync ( )

Attempts to synchronise and announce a new epoch.

The synchronisation points must be serialized (e.g. if there are multiple G/C workers or other writers). Generally, calls to ebr::staging_epoch() and ebr::gc_epoch() would be a part of the same serialized path (calling sync() and gc_epoch()/staging_epoch() concurrently in two other threads will cause an undefined behavior).

Returns
true if a new epoch is announced and false if it wasn't possible in the current state.

The documentation for this class was generated from the following file: