cds/urcu/signal_threaded.h

   1 /*
   2     This file is a part of libcds - Concurrent Data Structures library
   3
   4     (C) Copyright Maxim Khizhinsky (libcds.dev@gmail.com) 2006-2017
   5
   6     Source code repo: http://github.com/khizmax/libcds/
   7     Download: http://sourceforge.net/projects/libcds/files/
   8
   9     Redistribution and use in source and binary forms, with or without
  10     modification, are permitted provided that the following conditions are met:
  11
  12     * Redistributions of source code must retain the above copyright notice, this
  13       list of conditions and the following disclaimer.
  14
  15     * Redistributions in binary form must reproduce the above copyright notice,
  16       this list of conditions and the following disclaimer in the documentation
  17       and/or other materials provided with the distribution.
  18
  19     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  20     AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21     IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  22     DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
  23     FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24     DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  25     SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  26     CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  27     OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28     OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29 */
  30
  31 #ifndef CDSLIB_URCU_SIGNAL_THREADED_H
  32 #define CDSLIB_URCU_SIGNAL_THREADED_H
  33
  34 #include <cds/urcu/details/sig_threaded.h>
  35
  36 #ifdef CDS_URCU_SIGNAL_HANDLING_ENABLED
  37
  38 namespace cds { namespace urcu {
  39
  40     /// User-space signal-handled RCU with special thread for deferred reclamation
  41     /** @anchor cds_urcu_signal_threaded_gc
  42
  43         This is a wrapper around \p signal_threaded class.
  44
  45         Template arguments:
  46         - \p Buffer - lock-free MPSC (muliple producer/single consumer) queue.
  47             Default is \p cds::container::VyukovMPSCCycleQueue< epoch_retired_ptr >
  48         - \p Lock - mutex type, default is \p std::mutex
  49         - \p DisposerThread - reclamation thread class, default is \p %general_threaded_dispose_thread
  50             See \ref cds::urcu::dispose_thread for class interface.
  51         - \p Backoff - back-off schema, default is \p cds::backoff::Default
  52
  53     */
  54     template <
  55 #ifdef CDS_DOXGEN_INVOKED
  56         class Buffer = cds::container::VyukovMPSCCycleQueue< epoch_retired_ptr >
  57         ,class Lock = std::mutex
  58         ,class DisposerThread = dispose_thread<Buffer>
  59         ,class Backoff = cds::backoff::Default
  60 #else
  61         class Buffer
  62        ,class Lock
  63        ,class DisposerThread
  64        ,class Backoff
  65 #endif
  66     >
  67     class gc< signal_threaded< Buffer, Lock, DisposerThread, Backoff > >: public details::gc_common
  68     {
  69     public:
  70         typedef signal_threaded< Buffer, Lock, DisposerThread, Backoff >  rcu_implementation   ;    ///< Wrapped URCU implementation
  71
  72         typedef typename rcu_implementation::rcu_tag     rcu_tag     ;   ///< URCU tag
  73         typedef typename rcu_implementation::thread_gc   thread_gc   ;   ///< Thread-side RCU part
  74         typedef typename rcu_implementation::scoped_lock scoped_lock ;   ///< Access lock class
  75
  76         using details::gc_common::atomic_marked_ptr;
  77
  78     public:
  79         /// Creates URCU \p %general_threaded singleton.
  80         /**
  81             The \p nBufferCapacity parameter defines RCU threshold.
  82
  83             The \p nSignal parameter defines a signal number stated for RCU, default is \p SIGUSR1
  84         */
  85         gc( size_t nBufferCapacity = 256, int nSignal = SIGUSR1 )
  86         {
  87             rcu_implementation::Construct( nBufferCapacity, nSignal );
  88         }
  89
  90         /// Destroys URCU \p %signal_threaded singleton
  91         ~gc()
  92         {
  93             rcu_implementation::Destruct( true );
  94         }
  95
  96     public:
  97         /// Waits to finish a grace period and calls disposing thread
  98         /**
  99             After grace period finished the function gives new task to disposing thread.
 100             Unlike \ref force_dispose the \p %synchronize function does not wait for
 101             task ending. Only a "task ready" message is sent to disposing thread.
 102         */
 103         static void synchronize()
 104         {
 105             rcu_implementation::instance()->synchronize();
 106         }
 107
 108         /// Retires pointer \p p by the disposer \p pFunc
 109         /**
 110             If the buffer is full, \ref synchronize function is invoked.
 111         */
 112         template <typename T>
 113         static void retire_ptr( T * p, void (* pFunc)(T *))
 114         {
 115             retired_ptr rp( reinterpret_cast<void *>( p ), reinterpret_cast<free_retired_ptr_func>( pFunc ));
 116             retire_ptr( rp );
 117         }
 118
 119         /// Retires pointer \p p using \p Disposer
 120         /**
 121             If the buffer is full, \ref synchronize function is invoked.
 122         */
 123         template <typename Disposer, typename T>
 124         static void retire_ptr( T * p )
 125         {
 126             retire_ptr( p, cds::details::static_functor<Disposer, T>::call );
 127         }
 128
 129         /// Retires pointer \p p of type \ref cds_urcu_retired_ptr "retired_ptr"
 130         /**
 131             If the buffer is full, \ref synchronize function is invoked.
 132         */
 133         static void retire_ptr( retired_ptr& p )
 134         {
 135             rcu_implementation::instance()->retire_ptr(p);
 136         }
 137
 138         /// Frees chain [ \p itFirst, \p itLast) in one synchronization cycle
 139         template <typename ForwardIterator>
 140         static void batch_retire( ForwardIterator itFirst, ForwardIterator itLast )
 141         {
 142             rcu_implementation::instance()->batch_retire( itFirst, itLast );
 143         }
 144
 145         /// Retires the pointer chain until \p Func returns \p nullptr retired pointer
 146         template <typename Func>
 147         static void batch_retire( Func e )
 148         {
 149             rcu_implementation::instance()->batch_retire( e );
 150         }
 151
 152          /// Acquires access lock (so called RCU reader-side lock)
 153         /**
 154             For safety reasons, it is better to use \ref scoped_lock class for locking/unlocking
 155         */
 156         static void access_lock()
 157         {
 158             thread_gc::access_lock();
 159         }
 160
 161         /// Releases access lock (so called RCU reader-side lock)
 162         /**
 163             For safety reasons, it is better to use \ref scoped_lock class for locking/unlocking
 164         */
 165         static void access_unlock()
 166         {
 167             thread_gc::access_unlock();
 168         }
 169
 170         /// Checks if the thread is inside read-side critical section (i.e. the lock is acquired)
 171         /**
 172             Usually, this function is used internally to be convinced
 173             that subsequent remove action is not lead to a deadlock.
 174         */
 175         static bool is_locked()
 176         {
 177             return thread_gc::is_locked();
 178         }
 179
 180         /// Returns the threshold of internal buffer
 181         static size_t capacity()
 182         {
 183             return rcu_implementation::instance()->capacity();
 184         }
 185
 186         /// Returns the signal number stated for RCU
 187         static int signal_no()
 188         {
 189             return rcu_implementation::instance()->signal_no();
 190         }
 191
 192         /// Forces retired object removal (synchronous version of \ref synchronize)
 193         /**
 194             The function calls \ref synchronize and waits until reclamation thread
 195             frees retired objects.
 196         */
 197         static void force_dispose()
 198         {
 199             rcu_implementation::instance()->force_dispose();
 200         }
 201     };
 202
 203     //@cond
 204     template<>
 205     class gc< signal_threaded_stripped >: public gc< signal_threaded<>>
 206     {};
 207     //@endcond
 208
 209 }} // namespace cds::urcu
 210
 211 #endif // #ifdef CDS_URCU_SIGNAL_HANDLING_ENABLED
 212 #endif // #ifndef CDSLIB_URCU_SIGNAL_THREADED_H