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