cds/urcu/general_threaded.h

   1 //$$CDS-header$$
   2
   3 #ifndef _CDS_URCU_GENERAL_THREADED_H
   4 #define _CDS_URCU_GENERAL_THREADED_H
   5
   6 #include <cds/urcu/details/gpt.h>
   7
   8 namespace cds { namespace urcu {
   9
  10     /// User-space general-purpose RCU with special thread for deferred reclamation
  11     /** @anchor cds_urcu_general_threaded_gc
  12
  13         This is a wrapper around general_threaded class used for metaprogramming.
  14
  15         Template arguments:
  16         - \p Buffer - lock-free queue or lock-free bounded queue.
  17             Default is cds::container::VyukovMPMCCycleQueue< retired_ptr >
  18         - \p Lock - mutex type, default is \p std::mutex
  19         - \p DisposerThread - reclamation thread class, default is \p cds::urcu::dispose_thread
  20             See \ref cds::urcu::dispose_thread for class interface.
  21         - \p Backoff - back-off schema, default is cds::backoff::Default
  22
  23     */
  24     template <
  25 #ifdef CDS_DOXGEN_INVOKED
  26         class Buffer = cds::container::VyukovMPMCCycleQueue<
  27             epoch_retired_ptr
  28             ,cds::opt::buffer< cds::opt::v::dynamic_buffer< epoch_retired_ptr > >
  29         >
  30         ,class Lock = cds_std::mutex
  31         ,class DisposerThread = dispose_thread<Buffer>
  32         ,class Backoff = cds::backoff::Default
  33 #else
  34         class Buffer
  35        ,class Lock
  36        ,class DisposerThread
  37        ,class Backoff
  38 #endif
  39     >
  40     class gc< general_threaded< Buffer, Lock, DisposerThread, Backoff > >: public details::gc_common
  41     {
  42     public:
  43         typedef general_threaded< Buffer, Lock, DisposerThread, Backoff >  rcu_implementation   ;    ///< Wrapped URCU implementation
  44
  45         typedef typename rcu_implementation::rcu_tag     rcu_tag     ;   ///< URCU tag
  46         typedef typename rcu_implementation::thread_gc   thread_gc   ;   ///< Thread-side RCU part
  47         typedef typename rcu_implementation::scoped_lock scoped_lock ;   ///< Access lock class
  48
  49         using details::gc_common::atomic_marked_ptr;
  50
  51     public:
  52         /// Creates URCU \p %general_threaded singleton.
  53         gc( size_t nBufferCapacity = 256 )
  54         {
  55             rcu_implementation::Construct( nBufferCapacity );
  56         }
  57
  58         /// Destroys URCU \p %general_threaded singleton
  59         ~gc()
  60         {
  61             rcu_implementation::Destruct( true );
  62         }
  63
  64     public:
  65         /// Waits to finish a grace period and calls disposing thread
  66         /**
  67             After grace period finished the function gives new task to disposing thread.
  68             Unlike \ref force_dispose the \p %synchronize function does not wait for
  69             task ending. Only a "task ready" message is sent to disposing thread.
  70         */
  71         static void synchronize()
  72         {
  73             rcu_implementation::instance()->synchronize();
  74         }
  75
  76         /// Retires pointer \p p by the disposer \p pFunc
  77         /**
  78             If the buffer is full, \ref synchronize function is invoked.
  79         */
  80         template <typename T>
  81         static void retire_ptr( T * p, void (* pFunc)(T *) )
  82         {
  83             retired_ptr rp( reinterpret_cast<void *>( p ), reinterpret_cast<free_retired_ptr_func>( pFunc ) );
  84             retire_ptr( rp );
  85         }
  86
  87         /// Retires pointer \p p using \p Disposer
  88         /**
  89             If the buffer is full, \ref synchronize function is invoked.
  90         */
  91         template <typename Disposer, typename T>
  92         static void retire_ptr( T * p )
  93         {
  94             retire_ptr( p, cds::details::static_functor<Disposer, T>::call );
  95         }
  96
  97         /// Retires pointer \p p of type \ref cds_urcu_retired_ptr "retired_ptr"
  98         /**
  99             If the buffer is full, \ref synchronize function is invoked.
 100         */
 101         static void retire_ptr( retired_ptr& p )
 102         {
 103             rcu_implementation::instance()->retire_ptr(p);
 104         }
 105
 106         /// Frees chain [ \p itFirst, \p itLast) in one synchronization cycle
 107         template <typename ForwardIterator>
 108         static void batch_retire( ForwardIterator itFirst, ForwardIterator itLast )
 109         {
 110             rcu_implementation::instance()->batch_retire( itFirst, itLast );
 111         }
 112
 113          /// Acquires access lock (so called RCU reader-side lock)
 114         /**
 115             For safety reasons, it is better to use \ref scoped_lock class for locking/unlocking
 116         */
 117         static void access_lock()
 118         {
 119             thread_gc::access_lock();
 120         }
 121
 122         /// Releases access lock (so called RCU reader-side lock)
 123         /**
 124             For safety reasons, it is better to use \ref scoped_lock class for locking/unlocking
 125         */
 126         static void access_unlock()
 127         {
 128             thread_gc::access_unlock();
 129         }
 130
 131         /// Checks if the thread is inside read-side critical section (i.e. the lock is acquired)
 132         /**
 133             Usually, this function is used internally to be convinced
 134             that subsequent remove action is not lead to a deadlock.
 135         */
 136         static bool is_locked()
 137         {
 138             return thread_gc::is_locked();
 139         }
 140
 141         /// Returns the threshold of internal buffer
 142         static size_t capacity()
 143         {
 144             return rcu_implementation::instance()->capacity();
 145         }
 146
 147         /// Forces retired object removal (synchronous version of \ref synchronize)
 148         /**
 149             The function calls \ref synchronize and waits until reclamation thread
 150             frees retired objects.
 151         */
 152         static void force_dispose()
 153         {
 154             rcu_implementation::instance()->force_dispose();
 155         }
 156     };
 157
 158 }} // namespace cds::urcu
 159
 160 #endif // #ifndef _CDS_URCU_GENERAL_THREADED_H