cds  2.2.0
cds::urcu::general_threaded< Buffer, Lock, DisposerThread, Backoff > Class Template Reference

User-space general-purpose RCU with deferred threaded reclamation. More...

#include <cds/urcu/general_threaded.h>

Inheritance diagram for cds::urcu::general_threaded< Buffer, Lock, DisposerThread, Backoff >:

Public Types

typedef Buffer buffer_type
 Buffer type.
 
typedef Lock lock_type
 Lock type.
 
typedef Backoff back_off
 Back-off scheme.
 
typedef DisposerThread disposer_thread
 Disposer thread type.
 
typedef general_threaded_tag rcu_tag
 Thread-side RCU part.
 
typedef base_class::thread_gc thread_gc
 Access lock class.
 
typedef thread_gc::scoped_lock scoped_lock
 Access lock class.
 

Public Member Functions

virtual void retire_ptr (retired_ptr &p)
 Retires p pointer. More...
 
template<typename ForwardIterator >
void batch_retire (ForwardIterator itFirst, ForwardIterator itLast)
 Retires the pointer chain [itFirst, itLast)
 
template<typename Func >
void batch_retire (Func e)
 Retires the pointer chain until Func returns nullptr retired pointer.
 
void synchronize ()
 Waits to finish a grace period and calls disposing thread.
 
size_t capacity () const
 Returns the threshold of internal buffer.
 

Static Public Member Functions

static general_threadedinstance ()
 Returns singleton instance.
 
static bool isUsed ()
 Checks if the singleton is created and ready to use.
 
static void Construct (size_t nBufferCapacity=256)
 Creates singleton object and starts reclamation thread. More...
 
static void Destruct (bool bDetachAll=false)
 Destroys singleton object and terminates internal reclamation thread.
 

Static Public Attributes

static bool const c_bBuffered = true
 This RCU buffers disposed elements.
 

Detailed Description

template<class Buffer = cds::container::VyukovMPSCCycleQueue< epoch_retired_ptr >, class Lock = std::mutex, class DisposerThread = dispose_thread<Buffer>, class Backoff = cds::backoff::Default>
class cds::urcu::general_threaded< Buffer, Lock, DisposerThread, Backoff >

User-space general-purpose RCU with deferred threaded reclamation.

This implementation is similar to general_buffered but separate thread is created for deleting the retired objects. Like general_buffered, the class contains an internal buffer where retired objects are accumulated. When the buffer becomes full, the RCU synchronize() function is called that waits until all reader/updater threads end up their read-side critical sections, i.e. until the RCU quiescent state will come. After that the "work ready" message is sent to reclamation thread. The reclamation thread frees the buffer. This synchronization cycle may be called in any thread that calls retire_ptr() function.

There is a wrapper gc<general_threaded> for general_threaded class that provides unified RCU interface. You should use this wrapper class instead general_threaded

The Buffer contains items of epoch_retired_ptr type

and it should support a multiple producer/single consumer queue with the following interface:

  • bool push( epoch_retired_ptr& p ) - places the retired pointer p into queue. If the function returns false it means that the buffer is full and RCU synchronization cycle must be processed.
  • epoch_retired_ptr * front() - returns a pointer to the top element or nullptr if the buffer is empty.
  • bool pop_front() - pops the top element; returns false if the buffer is empty.
  • size_t size() - returns queue's item count.

The buffer is considered as full if push() returns false or the buffer size reaches the RCU threshold.

Template arguments:

  • Buffer - MPSC (muliple producer/single consumer) buffer type with FIFO semantics.

    Default is cds::container::VyukovMPSCCycleQueue. The buffer contains the objects of epoch_retired_ptr type that contains additional m_nEpoch field. This field specifies an epoch when the object has been placed into the buffer. The general_threaded object has a global epoch counter that is incremented on each synchronize() call. The epoch is used internally to prevent early deletion.

  • Lock - mutex type, default is std::mutex
  • DisposerThread - the reclamation thread class. Default is cds::urcu::dispose_thread, see the description of this class for required interface.
  • Backoff - back-off schema, default is cds::backoff::Default

Member Function Documentation

§ Construct()

template<class Buffer = cds::container::VyukovMPSCCycleQueue< epoch_retired_ptr >, class Lock = std::mutex, class DisposerThread = dispose_thread<Buffer>, class Backoff = cds::backoff::Default>
static void cds::urcu::general_threaded< Buffer, Lock, DisposerThread, Backoff >::Construct ( size_t  nBufferCapacity = 256)
inlinestatic

Creates singleton object and starts reclamation thread.

The nBufferCapacity parameter defines RCU threshold.

§ retire_ptr()

template<class Buffer = cds::container::VyukovMPSCCycleQueue< epoch_retired_ptr >, class Lock = std::mutex, class DisposerThread = dispose_thread<Buffer>, class Backoff = cds::backoff::Default>
virtual void cds::urcu::general_threaded< Buffer, Lock, DisposerThread, Backoff >::retire_ptr ( retired_ptr p)
inlinevirtual

Retires p pointer.

The method pushes p pointer to internal buffer. When the buffer becomes full synchronize function is called to wait for the end of grace period and then a message is sent to the reclamation thread.


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

cds 2.2.0 Developed by Maxim Khizhinsky aka khizmax 2007 - 2017
Autogenerated Wed Jan 4 2017 08:50:08 by Doxygen 1.8.12