FOLLY: synchronization/Rcu.h

FOLLY: synchronization/Rcu.h


C++ read-copy-update (RCU) functionality in folly.


A low-overhead synchronization technique called read-copy-update (RCU) guarantees the ordering of actions on shared data. In the most basic usage pattern, writers modify shared state and then postpone some cleanup actions while readers enter a crucial part, view some state, and exit the critical region.

A cleanup action that is postponed during a reader critical section won't be carried out until after that critical section has ended if the foolish RCU APIs are used properly.




The main synchronization primitive in folly RCU is a folly::rcu_domain. A folly::rcu_domain is a "universe" of deferred execution. Each domain has an executor on which deferred functions may execute. folly::rcu_domain provides the requirements to be BasicLockable.

Default vs. custom domains

 A global, default domain can be accessed using folly::rcu_default_domain().


Another synchronization primitive provided by the folly RCU library is rcu_barrier(). Unlike rcu_synchronize(), which blocks until all outstanding readers have exited their read regions, rcu_barrier() blocks until all outstanding deleters are completed.

API limitations of updaters

During a retire callback, exceptions cannot be thrown at any stage. Both the deleter and the object's destructor fall under this category.  Other than this, any operation is safe from within a retired object's destructor, including retiring other objects, or even retiring the same object as long as the custom deleter did not free it. Holding a lock over a rcu retire() that the deleter has obtained is forbidden while using the default domain or the default executor.

 When using the default deleter delete, which does not acquire any user locks, this is typically not a problem. An object with a user-defined destructor that gains locks held throughout the corresponding call to rcu retire(), however, can still stall even when using the default deleter.

Also keep in mind that the order in which retiring callbacks are called is not guaranteed. It is guaranteed that a retire callback won't be activated until all readers who were present when it was planned have left. If not, callback invocation can happen in any sequence.