cds/urcu/details/gpi.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_DETAILS_GPI_H
  32 #define CDSLIB_URCU_DETAILS_GPI_H
  33
  34 #include <mutex>
  35 #include <cds/urcu/details/gp.h>
  36 #include <cds/algo/backoff_strategy.h>
  37
  38 namespace cds { namespace urcu {
  39
  40     /// User-space general-purpose RCU with immediate reclamation
  41     /**
  42         @headerfile cds/urcu/general_instant.h
  43
  44         This is simplest general-purpose RCU implementation. When a thread calls \ref retire_ptr function
  45         the RCU \p synchronize function is called that waits until all reader/updater threads end up
  46         their read-side critical sections, i.e. until the RCU quiescent state will come.
  47         After that the retired object is freed immediately.
  48         Thus, the implementation blocks for any retired object
  49
  50         There is a wrapper \ref cds_urcu_general_instant_gc "gc<general_instant>" for \p %general_instant class
  51         that provides unified RCU interface. You should use this wrapper class instead \p %general_instant
  52
  53         Template arguments:
  54         - \p Lock - mutex type, default is \p std::mutex
  55         - \p Backoff - back-off schema, default is cds::backoff::Default
  56     */
  57     template <
  58         class Lock = std::mutex
  59        ,class Backoff = cds::backoff::Default
  60     >
  61     class general_instant: public details::gp_singleton< general_instant_tag >
  62     {
  63         //@cond
  64         typedef details::gp_singleton< general_instant_tag > base_class;
  65         //@endcond
  66
  67     public:
  68         typedef general_instant_tag rcu_tag ;   ///< RCU tag
  69         typedef Lock    lock_type   ;           ///< Lock type
  70         typedef Backoff back_off    ;           ///< Back-off schema type
  71
  72         typedef typename base_class::thread_gc  thread_gc ;   ///< Thread-side RCU part
  73         typedef typename thread_gc::scoped_lock scoped_lock ; ///< Access lock class
  74
  75         //@cond
  76         static bool const c_bBuffered = false ; ///< No buffers
  77         //@endcond
  78
  79     protected:
  80         //@cond
  81         typedef details::gp_singleton_instance< rcu_tag >    singleton_ptr;
  82         //@endcond
  83
  84     protected:
  85         //@cond
  86         lock_type   m_Lock;
  87         //@endcond
  88
  89     public:
  90         /// Returns singleton instance
  91         static general_instant * instance()
  92         {
  93             return static_cast<general_instant *>( base_class::instance());
  94         }
  95
  96         /// Checks if the singleton is created and ready to use
  97         static bool isUsed()
  98         {
  99             return singleton_ptr::s_pRCU != nullptr;
 100         }
 101
 102     protected:
 103         //@cond
 104         general_instant()
 105         {}
 106
 107         ~general_instant()
 108         {}
 109
 110         void flip_and_wait()
 111         {
 112             back_off bkoff;
 113             base_class::flip_and_wait( bkoff );
 114         }
 115         //@endcond
 116
 117     public:
 118         /// Creates singleton object
 119         static void Construct()
 120         {
 121             if ( !singleton_ptr::s_pRCU )
 122                 singleton_ptr::s_pRCU = new general_instant();
 123         }
 124
 125         /// Destroys singleton object
 126         static void Destruct( bool bDetachAll = false )
 127         {
 128             if ( isUsed()) {
 129                 if ( bDetachAll )
 130                     instance()->m_ThreadList.detach_all();
 131                 delete instance();
 132                 singleton_ptr::s_pRCU = nullptr;
 133             }
 134         }
 135
 136     public:
 137         /// Retires \p p pointer
 138         /**
 139             The method calls \p synchronize() to wait for the end of grace period
 140             and calls \p p disposer.
 141         */
 142         virtual void retire_ptr( retired_ptr& p ) override
 143         {
 144             synchronize();
 145             if ( p.m_p )
 146                 p.free();
 147         }
 148
 149         /// Retires the pointer chain [\p itFirst, \p itLast)
 150         template <typename ForwardIterator>
 151         void batch_retire( ForwardIterator itFirst, ForwardIterator itLast )
 152         {
 153             if ( itFirst != itLast ) {
 154                 synchronize();
 155                 while ( itFirst != itLast ) {
 156                     retired_ptr p( *itFirst );
 157                     ++itFirst;
 158                     if ( p.m_p )
 159                         p.free();
 160                 }
 161             }
 162         }
 163
 164         /// Retires the pointer chain until \p Func returns \p nullptr retired pointer
 165         template <typename Func>
 166         void batch_retire( Func e )
 167         {
 168             retired_ptr p{ e() };
 169             if ( p.m_p ) {
 170                 synchronize();
 171                 while ( p.m_p ) {
 172                     retired_ptr pr( p );
 173                     p = e();
 174                     pr.free();
 175                 }
 176             }
 177         }
 178
 179         /// Waits to finish a grace period
 180         void synchronize()
 181         {
 182             assert( !thread_gc::is_locked());
 183             std::unique_lock<lock_type> sl( m_Lock );
 184             flip_and_wait();
 185             flip_and_wait();
 186         }
 187
 188         //@cond
 189         // Added for uniformity
 190         size_t CDS_CONSTEXPR capacity() const
 191         {
 192             return 1;
 193         }
 194         //@endcond
 195     };
 196
 197     /// User-space general-purpose RCU with immediate reclamation (stripped version)
 198     /**
 199         @headerfile cds/urcu/general_instant.h
 200
 201         This short version of \p general_instant is intended for stripping debug info.
 202         If you use \p %general_instant with default template arguments you may use
 203         this stripped version. All functionality of both classes are identical.
 204     */
 205     class general_instant_stripped: public general_instant<>
 206     {};
 207
 208 }} // namespace cds::urcu
 209
 210 #endif // #ifndef CDSLIB_URCU_DETAILS_GPI_H