cds/urcu/exempt_ptr.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-2016
   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_EXEMPT_PTR_H
  32 #define CDSLIB_URCU_EXEMPT_PTR_H
  33
  34 #include <type_traits>
  35 #include <cds/details/defs.h>
  36
  37 namespace cds { namespace urcu {
  38
  39     //@cond
  40     namespace details {
  41         template <typename Node, typename Value>
  42         struct conventional_exempt_member_cast
  43         {
  44             Value * operator()( Node * p ) const
  45             {
  46                 return &p->m_Value;
  47             }
  48         };
  49
  50         template <typename Node, typename Value>
  51         struct conventional_exempt_pair_cast
  52         {
  53             Value * operator()( Node * p ) const
  54             {
  55                 return &p->m_Data;
  56             }
  57         };
  58     } // namespace details
  59     //@endcond
  60
  61     /// Exempt pointer for RCU
  62     /**
  63         This special pointer class is intended for returning extracted node from RCU-based container.
  64         The destructor (and \p release() member function) invokes <tt>RCU::retire_ptr< Disposer >()</tt> function to dispose the node.
  65         For non-intrusive containers from \p cds::container namespace \p Disposer is usually an invocation
  66         of node deallocator. For intrusive containers the disposer can be empty or it can trigger an event "node can be reused safely".
  67         In any case, the exempt pointer concept keeps RCU semantics.
  68         The destructor or \p release() should be called outside the RCU lock of current thread.
  69
  70         You don't need use this helper class directly. Any RCU-based container typedefs a simplified version of this template.
  71
  72         Template arguments:
  73         - \p RCU - one of \ref cds_urcu_gc "RCU type"
  74         - \p NodeType - container's node type
  75         - \p ValueType - value type stored in container's node. For intrusive containers it is the same as \p NodeType
  76         - \p Disposer - a disposer functor
  77         - \p Cast - a functor for casting from \p NodeType to \p ValueType. For intrusive containers
  78             the casting is usually disabled, i.e. \p Cast is \p void.
  79     */
  80     template <
  81         class RCU,
  82         typename NodeType,
  83         typename ValueType,
  84         typename Disposer,
  85 #ifdef CDS_DOXYGEN_INVOKED
  86         typename Cast
  87 #else
  88         typename Cast=details::conventional_exempt_member_cast<NodeType, ValueType>
  89 #endif
  90     >
  91     class exempt_ptr
  92     {
  93         //@cond
  94         struct trivial_cast {
  95             ValueType * operator()( NodeType * p ) const
  96             {
  97                 return p;
  98             }
  99         };
 100         //@endcond
 101     public:
 102         typedef RCU         rcu         ;   ///< RCU type - one of <tt>cds::urcu::gc< ... ></tt>
 103         typedef NodeType    node_type   ;   ///< Node type
 104         typedef ValueType   value_type  ;   ///< Value type
 105         typedef Disposer    disposer    ;   ///< Disposer calling when release
 106         /// Functor converting \p node_type to \p value_type
 107         typedef typename std::conditional< std::is_same< Cast, void >::value, trivial_cast, Cast>::type node_to_value_cast;
 108
 109     private:
 110         //@cond
 111         node_type *     m_pNode;
 112         //@endcond
 113
 114     public:
 115         /// Constructs empty pointer
 116         exempt_ptr() CDS_NOEXCEPT
 117             : m_pNode( nullptr )
 118         {}
 119
 120         //@cond
 121         /// Creates exempt pointer for \p pNode. Only for internal use.
 122         explicit exempt_ptr( node_type * pNode ) CDS_NOEXCEPT
 123             : m_pNode( pNode )
 124         {}
 125         explicit exempt_ptr( std::nullptr_t ) CDS_NOEXCEPT
 126             : m_pNode( nullptr )
 127         {}
 128         //@endcond
 129
 130         /// Move ctor
 131         exempt_ptr( exempt_ptr&& p ) CDS_NOEXCEPT
 132             : m_pNode( p.m_pNode )
 133         {
 134             p.m_pNode = nullptr;
 135         }
 136
 137         /// The exempt pointer is not copy-constructible
 138         exempt_ptr( exempt_ptr const& ) = delete;
 139
 140         /// Releases the pointer, see \p release()
 141         ~exempt_ptr()
 142         {
 143             release();
 144         }
 145
 146         /// Checks if the pointer is \p nullptr
 147         bool empty() const CDS_NOEXCEPT
 148         {
 149             return m_pNode == nullptr;
 150         }
 151
 152         /// \p bool operator returns <tt>!empty()</tt>
 153         explicit operator bool() const CDS_NOEXCEPT
 154         {
 155             return !empty();
 156         }
 157
 158         /// Dereference operator
 159         value_type * operator->() const CDS_NOEXCEPT
 160         {
 161             return !empty() ? node_to_value_cast()(m_pNode) : nullptr;
 162         }
 163
 164         /// Returns a reference to the value
 165         value_type& operator *() CDS_NOEXCEPT
 166         {
 167             assert( !empty());
 168             return *node_to_value_cast()( m_pNode );
 169         }
 170
 171         /// Move assignment. Can be called only outside of RCU critical section
 172         exempt_ptr& operator =( exempt_ptr&& p ) CDS_NOEXCEPT
 173         {
 174             release();
 175             m_pNode = p.m_pNode;
 176             p.m_pNode = nullptr;
 177             return *this;
 178         }
 179
 180         /// The exempt pointer is not copy-assignable
 181         exempt_ptr& operator=(exempt_ptr const&) = delete;
 182
 183         /// Disposes the pointer. Should be called only outside of RCU critical section
 184         void release()
 185         {
 186             if ( !empty() ) {
 187                 assert( !rcu::is_locked() );
 188                 rcu::template retire_ptr<disposer>( m_pNode );
 189                 m_pNode = nullptr;
 190             }
 191         }
 192     };
 193 }} // namespace cds::urcu
 194
 195 #endif //#ifndef CDSLIB_URCU_EXEMPT_PTR_H