Documentation Home >> Headers >> <jss/rcu.hpp> Header

RCU is a facility for ensuring safe reclamation of objects that may be potentially accessed by multiple threads concurrently. It is designed to be low overhead, and mostly lock-free, for threads that only perform read operations. Threads that need to reclaim objects have three choices:

  1. Register the object for reclamation and leave it for a background thread to collect;
  2. Register the object for reclamation and explicitly block until reclamation has occured; or
  3. Block waiting for concurrent readers to complete their reads, then reclaim the object directly.

Objects are registered for reclamation using jss::rcu_retire or jss::rcu_obj_base::retire. Blocking until reclamation has occured is performed with jss::rcu_barrier, and blocking until concurrent readers have completed their reads is performed with jss::rcu_synchronize.

Readers construct an instance of jss::rcu_reader before accessing a data structure which might contain objects that are being reclaimed. The jss::rcu_reader instance can be destroyed once the data structure access is complete. This is naturally achieved by constructing the jss::rcu_reader object as a local variable:

std::atomic<node*> list_head;

void foo(){
    jss::rcu_reader read_guard;

    auto* p=list_head.load();
    while(p){
        do_something(p);
        p=p->next.load();
    }
}

Once an jss::rcu_reader instance has been constructed, you are guaranteed that no objects subsequently registered with jss::rcu_retire will be reclaimed until that jss::rcu_reader has been destroyed. This prevents ABA problems and use-after-free problems that can easily manifest when building data structures that are safe for concurrent access by multiple threads.

See Also