cds/container/msqueue.h

   1 //$$CDS-header$$
   2
   3 #ifndef __CDS_CONTAINER_MSQUEUE_H
   4 #define __CDS_CONTAINER_MSQUEUE_H
   5
   6 #include <memory>
   7 #include <functional>   // ref
   8 #include <cds/intrusive/msqueue.h>
   9 #include <cds/container/details/base.h>
  10
  11 namespace cds { namespace container {
  12
  13     /// MSQueue related definitions
  14     /** @ingroup cds_nonintrusive_helper
  15     */
  16     namespace msqueue {
  17         /// Internal statistics
  18         template <typename Counter = cds::intrusive::msqueue::stat<>::counter_type >
  19         using stat = cds::intrusive::msqueue::stat< Counter >;
  20
  21         /// Dummy internal statistics
  22         typedef cds::intrusive::msqueue::empty_stat empty_stat;
  23
  24         /// MSQueue default type traits
  25         struct traits
  26         {
  27             /// Node allocator
  28             typedef CDS_DEFAULT_ALLOCATOR       allocator;
  29
  30             /// Back-off strategy
  31             typedef cds::backoff::empty         back_off;
  32
  33             /// Item counting feature; by default, disabled. Use \p cds::atomicity::item_counter to enable item counting
  34             typedef atomicity::empty_item_counter   item_counter;
  35
  36             /// Internal statistics (by default, disabled)
  37             /**
  38                 Possible option value are: \p msqueue::stat, \p msqueue::empty_stat (the default),
  39                 user-provided class that supports \p %msqueue::stat interface.
  40             */
  41             typedef msqueue::empty_stat         stat;
  42
  43             /// C++ memory ordering model
  44             /**
  45                 Can be \p opt::v::relaxed_ordering (relaxed memory model, the default)
  46                 or \p opt::v::sequential_consistent (sequentially consisnent memory model).
  47             */
  48             typedef opt::v::relaxed_ordering    memory_model;
  49
  50             /// Alignment of internal queue data. Default is \p opt::cache_line_alignment
  51             enum { alignment = opt::cache_line_alignment };
  52         };
  53
  54         /// Metafunction converting option list to \p msqueue::traits
  55         /**
  56             This is a wrapper for <tt> cds::opt::make_options< type_traits, Options...> </tt>
  57             Supported \p Options are:
  58             - opt::allocator - allocator (like \p std::allocator) used for allocating queue nodes. Default is \ref CDS_DEFAULT_ALLOCATOR
  59             - opt::back_off - back-off strategy used, default is \p cds::backoff::empty.
  60             - opt::item_counter - the type of item counting feature. Default is \p cds::atomicity::empty_item_counter (item counting disabled)
  61                 To enable item counting use \p cds::atomicity::item_counter
  62             - opt::stat - the type to gather internal statistics.
  63                 Possible statistics types are: \p msqueue::stat, \p msqueue::empty_stat, user-provided class that supports \p %msqueue::stat interface.
  64                 Default is \p %msqueue::empty_stat.
  65             - opt::alignment - the alignment for internal queue data. Default is \p opt::cache_line_alignment
  66             - opt::memory_model - C++ memory ordering model. Can be \p opt::v::relaxed_ordering (relaxed memory model, the default)
  67                 or \p opt::v::sequential_consistent (sequentially consisnent memory model).
  68
  69             Example: declare \p %MSQueue with item counting and internal statistics
  70             \code
  71             typedef cds::container::MSQueue< cds::gc::HP, Foo,
  72                 typename cds::container::msqueue::make_traits<
  73                     cds::opt::item_counte< cds::atomicity::item_counter >,
  74                     cds::opt::stat< cds::intrusive::msqueue::stat<> >
  75                 >::type
  76             > myQueue;
  77             \endcode
  78         */
  79         template <typename... Options>
  80         struct make_traits {
  81 #   ifdef CDS_DOXYGEN_INVOKED
  82             typedef implementation_defined type;   ///< Metafunction result
  83 #   else
  84             typedef typename cds::opt::make_options<
  85                 typename cds::opt::find_type_traits< traits, Options... >::type
  86                 , Options...
  87             >::type type;
  88 #   endif
  89         };
  90     } // namespace msqueue
  91
  92     //@cond
  93     namespace details {
  94         template <typename GC, typename T, typename Traits>
  95         struct make_msqueue
  96         {
  97             typedef GC gc;
  98             typedef T value_type;
  99             typedef Traits traits;
 100
 101             struct node_type: public intrusive::msqueue::node< gc >
 102             {
 103                 value_type  m_value;
 104
 105                 node_type( value_type const& val )
 106                     : m_value( val )
 107                 {}
 108
 109                 template <typename... Args>
 110                 node_type( Args&&... args )
 111                     : m_value( std::forward<Args>(args)...)
 112                 {}
 113             };
 114
 115             typedef typename traits::allocator::template rebind<node_type>::other allocator_type;
 116             typedef cds::details::Allocator< node_type, allocator_type >           cxx_allocator;
 117
 118             struct node_deallocator
 119             {
 120                 void operator ()( node_type * pNode )
 121                 {
 122                     cxx_allocator().Delete( pNode );
 123                 }
 124             };
 125
 126             struct intrusive_traits : public traits
 127             {
 128                 typedef cds::intrusive::base_hook< cds::opt::gc<gc> > hook;
 129                 typedef node_deallocator disposer;
 130             };
 131
 132             typedef intrusive::MSQueue< gc, node_type, intrusive_traits > type;
 133         };
 134     }
 135     //@endcond
 136
 137     /// Michael & Scott lock-free queue
 138     /** @ingroup cds_nonintrusive_queue
 139         It is non-intrusive version of Michael & Scott's queue algorithm based on intrusive implementation
 140         \p cds::intrusive::MSQueue.
 141
 142         Template arguments:
 143         - \p GC - garbage collector type: \p gc::HP, \p gc::DHP
 144         - \p T is a type stored in the queue.
 145         - \p Traits - queue traits, default is \p msqueue::traits. You can use \p msqueue::make_traits
 146             metafunction to make your traits or just derive your traits from \p %msqueue::traits:
 147             \code
 148             struct myTraits: public cds::container::msqueue::traits {
 149                 typedef cds::intrusive::msqueue::stat<> stat;
 150                 typedef cds::atomicity::item_counter    item_counter;
 151             };
 152             typedef cds::container::MSQueue< cds::gc::HP, Foo, myTraits > myQueue;
 153
 154             // Equivalent make_traits example:
 155             typedef cds::container::MSQueue< cds::gc::HP, Foo,
 156                 typename cds::container::msqueue::make_traits<
 157                     cds::opt::stat< cds::container::msqueue::stat<> >,
 158                     cds::opt::item_counter< cds::atomicity::item_counter >
 159                 >::type
 160             > myQueue;
 161             \endcode
 162     */
 163     template <typename GC, typename T, typename Traits>
 164     class MSQueue:
 165 #ifdef CDS_DOXYGEN_INVOKED
 166         intrusive::MSQueue< GC, cds::intrusive::msqueue::node< T >, Traits >
 167 #else
 168         details::make_msqueue< GC, T, Traits >::type
 169 #endif
 170     {
 171         //@cond
 172         typedef details::make_msqueue< GC, T, Traits > maker;
 173         typedef typename maker::type base_class;
 174         //@endcond
 175
 176     public:
 177         /// Rebind template arguments
 178         template <typename GC2, typename T2, typename Traits2>
 179         struct rebind {
 180             typedef MSQueue< GC2, T2, Traits2> other   ;   ///< Rebinding result
 181         };
 182
 183     public:
 184         typedef T value_type; ///< Value type stored in the queue
 185         typedef typename base_class::gc             gc;             ///< Garbage collector used
 186         typedef typename base_class::back_off       back_off;       ///< Back-off strategy used
 187         typedef typename maker::allocator_type      allocator_type; ///< Allocator type used for allocate/deallocate the nodes
 188         typedef typename base_class::item_counter   item_counter;   ///< Item counting policy used
 189         typedef typename base_class::stat           stat;           ///< Internal statistics policy used
 190         typedef typename base_class::memory_model   memory_model;   ///< Memory ordering. See cds::opt::memory_model option
 191
 192     protected:
 193         typedef typename maker::node_type  node_type   ;   ///< queue node type (derived from \p intrusive::msqueue::node)
 194
 195         //@cond
 196         typedef typename maker::cxx_allocator     cxx_allocator;
 197         typedef typename maker::node_deallocator  node_deallocator;   // deallocate node
 198         typedef typename base_class::node_traits    node_traits;
 199         //@endcond
 200
 201     protected:
 202         ///@cond
 203         static node_type * alloc_node()
 204         {
 205             return cxx_allocator().New();
 206         }
 207         static node_type * alloc_node( value_type const& val )
 208         {
 209             return cxx_allocator().New( val );
 210         }
 211         template <typename... Args>
 212         static node_type * alloc_node_move( Args&&... args )
 213         {
 214             return cxx_allocator().MoveNew( std::forward<Args>( args )... );
 215         }
 216         static void free_node( node_type * p )
 217         {
 218             node_deallocator()( p );
 219         }
 220
 221         struct node_disposer {
 222             void operator()( node_type * pNode )
 223             {
 224                 free_node( pNode );
 225             }
 226         };
 227         typedef std::unique_ptr< node_type, node_disposer >     scoped_node_ptr;
 228         //@endcond
 229
 230     public:
 231         /// Initializes empty queue
 232         MSQueue()
 233         {}
 234
 235         /// Destructor clears the queue
 236         ~MSQueue()
 237         {}
 238
 239         /// Returns queue's item count (see \ref intrusive::MSQueue::size for explanation)
 240         size_t size() const
 241         {
 242             return base_class::size();
 243         }
 244
 245         /// Returns reference to internal statistics
 246         const stat& statistics() const
 247         {
 248             return base_class::statistics();
 249         }
 250
 251         /// Enqueues \p val value into the queue.
 252         /**
 253             The function makes queue node in dynamic memory calling copy constructor for \p val
 254             and then it calls intrusive::MSQueue::enqueue.
 255             Returns \p true if success, \p false otherwise.
 256         */
 257         bool enqueue( value_type const& val )
 258         {
 259             scoped_node_ptr p( alloc_node(val) );
 260             if ( base_class::enqueue( *p ) ) {
 261                 p.release();
 262                 return true;
 263             }
 264             return false;
 265         }
 266
 267         /// Enqueues \p data to queue using a functor
 268         /**
 269             \p Func is a functor called to create node.
 270             The functor \p f takes one argument - a reference to a new node of type \ref value_type:
 271             \code
 272             cds:container::MSQueue< cds::gc::HP, Foo > myQueue;
 273             Bar bar;
 274             myQueue.enqueue_with( [&bar]( Foo& dest ) { dest = bar; } );
 275             \endcode
 276         */
 277         template <typename Func>
 278         bool enqueue_with( Func f )
 279         {
 280             scoped_node_ptr p( alloc_node() );
 281             f( p->m_value );
 282             if ( base_class::enqueue( *p )) {
 283                 p.release();
 284                 return true;
 285             }
 286             return false;
 287         }
 288
 289         /// Enqueues data of type \ref value_type constructed from <tt>std::forward<Args>(args)...</tt>
 290         template <typename... Args>
 291         bool emplace( Args&&... args )
 292         {
 293             scoped_node_ptr p( alloc_node_move( std::forward<Args>( args )... ) );
 294             if ( base_class::enqueue( *p ) ) {
 295                 p.release();
 296                 return true;
 297             }
 298             return false;
 299         }
 300
 301         /// Synonym for \ref enqueue function
 302         bool push( value_type const& val )
 303         {
 304             return enqueue( val );
 305         }
 306
 307         /// Synonym for \p enqueue_with() function
 308         template <typename Func>
 309         bool push_with( Func f )
 310         {
 311             return enqueue_with( f );
 312         }
 313
 314         /// Dequeues a value using a functor
 315         /**
 316             \p Func is a functor called to copy dequeued value.
 317             The functor takes one argument - a reference to removed node:
 318             \code
 319             cds:container::MSQueue< cds::gc::HP, Foo > myQueue;
 320             Bar bar;
 321             myQueue.dequeue_with( [&bar]( Foo& src ) { bar = std::move( src );});
 322             \endcode
 323             The functor is called only is the queue is not empty.
 324         */
 325         template <typename Func>
 326         bool dequeue_with( Func f )
 327         {
 328             typename base_class::dequeue_result res;
 329             if ( base_class::do_dequeue( res )) {
 330                 f( node_traits::to_value_ptr( *res.pNext )->m_value );
 331                 base_class::dispose_result( res );
 332                 return true;
 333             }
 334             return false;
 335         }
 336
 337         /// Dequeues a value from the queue
 338         /**
 339             If queue is not empty, the function returns \p true, \p dest contains copy of
 340             dequeued value. The assignment operator for type \ref value_type is invoked.
 341             If queue is empty, the function returns \p false, \p dest is unchanged.
 342         */
 343         bool dequeue( value_type& dest )
 344         {
 345             typedef cds::details::trivial_assign<value_type, value_type> functor;
 346             return dequeue( dest, functor() );
 347         }
 348
 349         /// Synonym for \ref dequeue function
 350         bool pop( value_type& dest )
 351         {
 352             return dequeue( dest );
 353         }
 354
 355         /// Synonym for \p dequeue_with() function
 356         template <typename Func>
 357         bool pop_with( Func f )
 358         {
 359             return dequeue_with( f );
 360         }
 361
 362         /// Checks if the queue is empty
 363         bool empty() const
 364         {
 365             return base_class::empty();
 366         }
 367
 368         /// Clear the queue
 369         /**
 370             The function repeatedly calls \ref dequeue until it returns \p nullptr.
 371         */
 372         void clear()
 373         {
 374             base_class::clear();
 375         }
 376     };
 377
 378 }}  // namespace cds::container
 379
 380 #endif  // #ifndef __CDS_CONTAINER_MSQUEUE_H