3 #ifndef CDSLIB_CONTAINER_OPTIMISTIC_QUEUE_H
4 #define CDSLIB_CONTAINER_OPTIMISTIC_QUEUE_H
7 #include <cds/intrusive/optimistic_queue.h>
8 #include <cds/container/details/base.h>
10 namespace cds { namespace container {
12 /// OptimisticQueue related definitions
13 /** @ingroup cds_nonintrusive_helper
15 namespace optimistic_queue {
16 /// Internal statistics
17 template <typename Counter = cds::intrusive::optimistic_queue::stat<>::counter_type >
18 using stat = cds::intrusive::optimistic_queue::stat< Counter >;
20 /// Dummy internal statistics
21 typedef cds::intrusive::optimistic_queue::empty_stat empty_stat;
23 /// MSQueue default type traits
27 typedef CDS_DEFAULT_ALLOCATOR allocator;
30 typedef cds::backoff::empty back_off;
32 /// Item counting feature; by default, disabled. Use \p cds::atomicity::item_counter to enable item counting
33 typedef atomicity::empty_item_counter item_counter;
35 /// Internal statistics (by default, disabled)
37 Possible option value are: \p optimistic_queue::stat, \p optimistic_queue::empty_stat (the default),
38 user-provided class that supports \p %optimistic_queue::stat interface.
40 typedef optimistic_queue::empty_stat stat;
42 /// C++ memory ordering model
44 Can be \p opt::v::relaxed_ordering (relaxed memory model, the default)
45 or \p opt::v::sequential_consistent (sequentially consisnent memory model).
47 typedef opt::v::relaxed_ordering memory_model;
49 /// Alignment of internal queue data. Default is \p opt::cache_line_alignment
50 enum { alignment = opt::cache_line_alignment };
53 /// Metafunction converting option list to \p msqueue::traits
55 Supported \p Options are:
56 - opt::allocator - allocator (like \p std::allocator) used for allocating queue nodes. Default is \ref CDS_DEFAULT_ALLOCATOR
57 - opt::back_off - back-off strategy used, default is \p cds::backoff::empty.
58 - opt::item_counter - the type of item counting feature. Default is \p cds::atomicity::empty_item_counter (item counting disabled)
59 To enable item counting use \p cds::atomicity::item_counter
60 - opt::stat - the type to gather internal statistics.
61 Possible statistics types are: \p optimistic_queue::stat, \p optimistic_queue::empty_stat,
62 user-provided class that supports \p %optimistic_queue::stat interface.
63 Default is \p %optimistic_queue::empty_stat.
64 - opt::alignment - the alignment for internal queue data. Default is \p opt::cache_line_alignment
65 - opt::memory_model - C++ memory ordering model. Can be \p opt::v::relaxed_ordering (relaxed memory model, the default)
66 or \p opt::v::sequential_consistent (sequentially consisnent memory model).
68 Example: declare \p OptimisticQueue with item counting and internal statistics
70 typedef cds::container::OptimisticQueue< cds::gc::HP, Foo,
71 typename cds::container::optimistic_queue::make_traits<
72 cds::opt::item_counter< cds::atomicity::item_counter >,
73 cds::opt::stat< cds::container::optimistic_queue::stat<> >
78 template <typename... Options>
80 # ifdef CDS_DOXYGEN_INVOKED
81 typedef implementation_defined type; ///< Metafunction result
83 typedef typename cds::opt::make_options<
84 typename cds::opt::find_type_traits< traits, Options... >::type
89 } // namespace optimistic_queue
93 template <typename GC, typename T, typename Traits>
94 struct make_optimistic_queue
98 typedef Traits traits;
100 struct node_type: public cds::intrusive::optimistic_queue::node< gc >
104 node_type( value_type const& val )
108 template <typename... Args>
109 node_type( Args&&... args )
110 : m_value( std::forward<Args>(args)...)
114 typedef typename traits::allocator::template rebind<node_type>::other allocator_type;
115 typedef cds::details::Allocator< node_type, allocator_type > cxx_allocator;
117 struct node_deallocator
119 void operator ()( node_type * pNode )
121 cxx_allocator().Delete( pNode );
125 struct intrusive_traits : public traits
127 typedef cds::intrusive::optimistic_queue::base_hook< opt::gc<gc> > hook;
128 typedef node_deallocator disposer;
129 static CDS_CONSTEXPR const opt::link_check_type link_checker = cds::intrusive::optimistic_queue::traits::link_checker;
132 typedef intrusive::OptimisticQueue< gc, node_type, intrusive_traits > type;
134 } // namespace details
138 /** @ingroup cds_nonintrusive_queue
139 Implementation of Ladan-Mozes & Shavit optimistic queue algorithm.
140 - [2008] Edya Ladan-Mozes, Nir Shavit "An Optimistic Approach to Lock-Free FIFO Queues"
143 - \p GC - garbage collector type: \p gc::HP, \p gc::DHP.
144 - \p T - type of values to be stored in the queue
145 - \p Traits - queue traits, default is \p optimistic_queue::traits. You can use \p optimistic_queue::make_traits
146 metafunction to make your traits or just derive your traits from \p %optimistic_queue::traits:
148 struct myTraits: public cds::container::optimistic_queue::traits {
149 typedef cds::intrusive::optimistic_queue::stat<> stat;
150 typedef cds::atomicity::item_counter item_counter;
152 typedef cds::container::OptimisticQueue< cds::gc::HP, Foo, myTraits > myQueue;
154 // Equivalent make_traits example:
155 typedef cds::container::OptimisticQueue< cds::gc::HP, Foo,
156 typename cds::container::optimistic_queue::make_traits<
157 cds::opt::stat< cds::container::optimistic_queue::stat<> >,
158 cds::opt::item_counter< cds::atomicity::item_counter >
163 template <typename GC, typename T, typename Traits = optimistic_queue::traits >
164 class OptimisticQueue:
165 #ifdef CDS_DOXYGEN_INVOKED
166 private intrusive::OptimisticQueue< GC, cds::intrusive::optimistic_queue::node< T >, Traits >
168 private details::make_optimistic_queue< GC, T, Traits >::type
172 typedef details::make_optimistic_queue< GC, T, Traits > maker;
173 typedef typename maker::type base_class;
177 /// Rebind template arguments
178 template <typename GC2, typename T2, typename Traits2>
180 typedef OptimisticQueue< GC2, T2, Traits2 > other ; ///< Rebinding result
184 typedef GC gc; ///< Garbage collector
185 typedef T value_type; ///< Value type to be stored in the queue
186 typedef Traits traits; ///< Queue traits
188 typedef typename base_class::back_off back_off; ///< Back-off strategy used
189 typedef typename maker::allocator_type allocator_type; ///< Allocator type used for allocate/deallocate the nodes
190 typedef typename base_class::item_counter item_counter; ///< Item counting policy used
191 typedef typename base_class::stat stat; ///< Internal statistics policy used
192 typedef typename base_class::memory_model memory_model; ///< Memory ordering. See \p cds::opt::memory_model option
194 static CDS_CONSTEXPR const size_t c_nHazardPtrCount = base_class::c_nHazardPtrCount; ///< Count of hazard pointer required for the algorithm
198 typedef typename maker::node_type node_type; ///< queue node type (derived from intrusive::optimistic_queue::node)
199 typedef typename maker::cxx_allocator cxx_allocator;
200 typedef typename maker::node_deallocator node_deallocator; // deallocate node
201 typedef typename base_class::node_traits node_traits;
206 static node_type * alloc_node()
208 return cxx_allocator().New();
210 static node_type * alloc_node( const value_type& val )
212 return cxx_allocator().New( val );
214 template <typename... Args>
215 static node_type * alloc_node_move( Args&&... args )
217 return cxx_allocator().MoveNew( std::forward<Args>( args )... );
219 static void free_node( node_type * p )
221 node_deallocator()( p );
224 struct node_disposer {
225 void operator()( node_type * pNode )
230 typedef std::unique_ptr< node_type, node_disposer > scoped_node_ptr;
234 /// Initializes empty queue
238 /// Destructor clears the queue
242 /// Enqueues \p val value into the queue.
244 The function makes queue node in dynamic memory calling copy constructor for \p val
245 and then it calls \p intrusive::OptimisticQueue::enqueue.
246 Returns \p true if success, \p false otherwise.
248 bool enqueue( const value_type& val )
250 scoped_node_ptr p( alloc_node(val));
251 if ( base_class::enqueue( *p )) {
258 /// Enqueues \p data to queue using a functor
260 \p Func is a functor called to create node.
261 The functor \p f takes one argument - a reference to a new node of type \ref value_type :
263 cds::container::OptimisticQueue< cds::gc::HP, Foo > myQueue;
265 myQueue.enqueue_with( [&bar]( Foo& dest ) { dest = bar; } );
268 template <typename Func>
269 bool enqueue_with( Func f )
271 scoped_node_ptr p( alloc_node() );
273 if ( base_class::enqueue( *p )) {
280 /// Enqueues data of type \ref value_type constructed with <tt>std::forward<Args>(args)...</tt>
281 template <typename... Args>
282 bool emplace( Args&&... args )
284 scoped_node_ptr p( alloc_node_move( std::forward<Args>(args)... ));
285 if ( base_class::enqueue( *p )) {
292 /// Synonym for \p enqueue() function
293 bool push( const value_type& val )
295 return enqueue( val );
298 /// Synonym for \p enqueue_with() function
299 template <typename Func>
300 bool push_with( Func f )
302 return enqueue_with( f );
305 /// Dequeues a value from the queue
307 If queue is not empty, the function returns \p true, \p dest contains copy of
308 dequeued value. The assignment operator for type \p value_type is invoked.
310 If queue is empty, the function returns \p false, \p dest is unchanged.
312 bool dequeue( value_type& dest )
314 return dequeue_with( [&dest]( value_type& src ) { dest = src; } );
317 /// Dequeues a value using a functor
319 \p Func is a functor called to copy dequeued value.
320 The functor takes one argument - a reference to removed node:
322 cds:container::OptimisticQueue< cds::gc::HP, Foo > myQueue;
324 myQueue.dequeue_with( [&bar]( Foo& src ) { bar = std::move( src );});
326 The functor is called only if the queue is not empty.
328 template <typename Func>
329 bool dequeue_with( Func f )
331 typename base_class::dequeue_result res;
332 if ( base_class::do_dequeue( res ) ) {
333 f( node_traits::to_value_ptr( *res.pNext )->m_value );
335 base_class::dispose_result( res );
342 /// Synonym for \ref dequeue() function
343 bool pop( value_type& dest )
345 return dequeue( dest );
348 /// Synonym for template version of \p dequeue_with() function
349 template <typename Func>
350 bool pop_with( Func f )
352 return dequeue_with( f );
355 /// Checks if the queue is empty
358 return base_class::empty();
363 The function repeatedly calls \ref dequeue until it returns \p nullptr.
370 /// Returns queue's item count
371 /** \copydetails cds::intrusive::OptimisticQueue::size()
375 return base_class::size();
378 /// Returns reference to internal statistics
379 const stat& statistics() const
381 return base_class::statistics();
385 }} // namespace cds::container
387 #endif //#ifndef CDSLIB_CONTAINER_OPTIMISTIC_QUEUE_H