cds/urcu/exempt_ptr.h

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