3 #ifndef __CDS_CONTAINER_IMPL_ELLEN_BINTREE_SET_H
4 #define __CDS_CONTAINER_IMPL_ELLEN_BINTREE_SET_H
7 #include <cds/container/details/ellen_bintree_base.h>
8 #include <cds/intrusive/impl/ellen_bintree.h>
9 #include <cds/container/details/guarded_ptr_cast.h>
11 namespace cds { namespace container {
13 /// Set based on Ellen's et al binary search tree
14 /** @ingroup cds_nonintrusive_set
15 @ingroup cds_nonintrusive_tree
16 @anchor cds_container_EllenBinTreeSet
19 - [2010] F.Ellen, P.Fatourou, E.Ruppert, F.van Breugel "Non-blocking Binary Search Tree"
21 %EllenBinTreeSet is an unbalanced leaf-oriented binary search tree that implements the <i>set</i>
22 abstract data type. Nodes maintains child pointers but not parent pointers.
23 Every internal node has exactly two children, and all data of type \p T currently in
24 the tree are stored in the leaves. Internal nodes of the tree are used to direct \p find
25 operation along the path to the correct leaf. The keys (of \p Key type) stored in internal nodes
26 may or may not be in the set. \p Key type is a subset of \p T type.
27 There should be exactly defined a key extracting functor for converting object of type \p T to
28 object of type \p Key.
30 Due to \p extract_min and \p extract_max member functions the \p %EllenBinTreeSet can act as
31 a <i>priority queue</i>. In this case you should provide unique compound key, for example,
32 the priority value plus some uniformly distributed random value.
34 @warning Recall the tree is <b>unbalanced</b>. The complexity of operations is <tt>O(log N)</tt>
35 for uniformly distributed random keys, but in worst case the complexity is <tt>O(N)</tt>.
37 @note In the current implementation we do not use helping technique described in original paper.
38 So, the current implementation is near to fine-grained lock-based tree.
39 Helping will be implemented in future release
41 <b>Template arguments</b> :
42 - \p GC - safe memory reclamation (i.e. light-weight garbage collector) type, like cds::gc::HP, cds::gc::PTB
43 Note that cds::gc::HRC is not supported.
44 - \p Key - key type, a subset of \p T
45 - \p T - type to be stored in tree's leaf nodes.
46 - \p Traits - type traits. See ellen_bintree::type_traits for explanation.
48 It is possible to declare option-based tree with ellen_bintree::make_set_traits metafunction
49 instead of \p Traits template argument.
50 Template argument list \p Options of ellen_bintree::make_set_traits metafunction are:
51 - ellen_bintree::key_extractor - key extracting functor, mandatory option. The functor has the following prototype:
53 struct key_extractor {
54 void operator ()( Key& dest, T const& src );
57 It should initialize \p dest key from \p src data. The functor is used to initialize internal nodes.
58 - opt::compare - key compare functor. No default functor is provided.
59 If the option is not specified, \p %opt::less is used.
60 - opt::less - specifies binary predicate used for key compare. At least \p %opt::compare or \p %opt::less should be defined.
61 - opt::item_counter - the type of item counting feature. Default is \ref atomicity::empty_item_counter that is no item counting.
62 - opt::memory_model - C++ memory ordering model. Can be opt::v::relaxed_ordering (relaxed memory model, the default)
63 or opt::v::sequential_consistent (sequentially consisnent memory model).
64 - opt::allocator - the allocator used for \ref ellen_bintree::node "leaf nodes" which contains data.
65 Default is \ref CDS_DEFAULT_ALLOCATOR.
66 - opt::node_allocator - the allocator used for internal nodes. Default is \ref CDS_DEFAULT_ALLOCATOR.
67 - ellen_bintree::update_desc_allocator - an allocator of \ref ellen_bintree::update_desc "update descriptors",
68 default is \ref CDS_DEFAULT_ALLOCATOR.
69 Note that update descriptor is helping data structure with short lifetime and it is good candidate for pooling.
70 The number of simultaneously existing descriptors is a relatively small number limited the number of threads
71 working with the tree and GC buffer size.
72 Therefore, a bounded lock-free container like \p cds::container::VyukovMPMCCycleQueue is good choice for the free-list
73 of update descriptors, see cds::memory::vyukov_queue_pool free-list implementation.
74 Also notice that size of update descriptor is not dependent on the type of data
75 stored in the tree so single free-list object can be used for several EllenBinTree-based object.
76 - opt::stat - internal statistics. Available types: ellen_bintree::stat, ellen_bintree::empty_stat (the default)
78 @note Do not include <tt><cds/container/impl/ellen_bintree_set.h></tt> header file directly.
79 There are header file for each GC type:
80 - <tt><cds/container/ellen_bintree_set_hp.h></tt> - for Hazard Pointer GC cds::gc::HP
81 - <tt><cds/container/ellen_bintree_set_ptb.h></tt> - for Pass-the-Buck GC cds::gc::PTB
82 - <tt><cds/container/ellen_bintree_set_rcu.h></tt> - for RCU GC
83 (see \ref cds_container_EllenBinTreeSet_rcu "RCU-based EllenBinTreeSet")
85 @anchor cds_container_EllenBinTreeSet_less
86 <b>Predicate requirements</b>
88 opt::less, opt::compare and other predicates using with member fuctions should accept at least parameters
89 of type \p T and \p Key in any combination.
90 For example, for \p Foo struct with \p std::string key field the appropiate \p less functor is:
99 bool operator()( Foo const& v1, Foo const& v2 ) const
100 { return v1.m_strKey < v2.m_strKey ; }
102 bool operator()( Foo const& v, std::string const& s ) const
103 { return v.m_strKey < s ; }
105 bool operator()( std::string const& s, Foo const& v ) const
106 { return s < v.m_strKey ; }
108 // Support comparing std::string and char const *
109 bool operator()( std::string const& s, char const * p ) const
110 { return s.compare(p) < 0 ; }
112 bool operator()( Foo const& v, char const * p ) const
113 { return v.m_strKey.compare(p) < 0 ; }
115 bool operator()( char const * p, std::string const& s ) const
116 { return s.compare(p) > 0; }
118 bool operator()( char const * p, Foo const& v ) const
119 { return v.m_strKey.compare(p) > 0; }
127 #ifdef CDS_DOXYGEN_INVOKED
128 class Traits = ellen_bintree::type_traits
133 class EllenBinTreeSet
134 #ifdef CDS_DOXYGEN_INVOKED
135 : public cds::intrusive::EllenBinTree< GC, Key, T, Traits >
137 : public ellen_bintree::details::make_ellen_bintree_set< GC, Key, T, Traits >::type
141 typedef ellen_bintree::details::make_ellen_bintree_set< GC, Key, T, Traits > maker;
142 typedef typename maker::type base_class;
146 typedef GC gc ; ///< Garbage collector
147 typedef Key key_type ; ///< type of a key stored in internal nodes; key is a part of \p value_type
148 typedef T value_type ; ///< type of value stored in the binary tree
149 typedef Traits options ; ///< Traits template parameter
151 # ifdef CDS_DOXYGEN_INVOKED
152 typedef implementation_defined key_comparator ; ///< key compare functor based on opt::compare and opt::less option setter.
154 typedef typename maker::intrusive_type_traits::compare key_comparator;
156 typedef typename base_class::item_counter item_counter ; ///< Item counting policy used
157 typedef typename base_class::memory_model memory_model ; ///< Memory ordering. See cds::opt::memory_model option
158 typedef typename base_class::stat stat ; ///< internal statistics type
159 typedef typename options::key_extractor key_extractor ; ///< key extracting functor
161 typedef typename options::allocator allocator_type ; ///< Allocator for leaf nodes
162 typedef typename base_class::node_allocator node_allocator ; ///< Internal node allocator
163 typedef typename base_class::update_desc_allocator update_desc_allocator ; ///< Update descriptor allocator
167 typedef typename maker::cxx_leaf_node_allocator cxx_leaf_node_allocator;
168 typedef typename base_class::value_type leaf_node;
169 typedef typename base_class::internal_node internal_node;
171 typedef std::unique_ptr< leaf_node, typename maker::leaf_deallocator > scoped_node_ptr;
176 typedef cds::gc::guarded_ptr< gc, leaf_node, value_type, details::guarded_ptr_cast_set<leaf_node, value_type> > guarded_ptr;
179 /// Default constructor
183 //static_assert( (std::is_same<gc, cds::gc::HP>::value || std::is_same<gc, cds::gc::PTB>::value), "GC must be cds::gc::HP or cds:gc::PTB" );
192 The function creates a node with copy of \p val value
193 and then inserts the node created into the set.
195 The type \p Q should contain at least the complete key for the node.
196 The object of \ref value_type should be constructible from a value of type \p Q.
197 In trivial case, \p Q is equal to \ref value_type.
199 Returns \p true if \p val is inserted into the set, \p false otherwise.
201 template <typename Q>
202 bool insert( Q const& val )
204 scoped_node_ptr sp( cxx_leaf_node_allocator().New( val ));
205 if ( base_class::insert( *sp.get() )) {
214 The function allows to split creating of new item into two part:
215 - create item with key only
216 - insert new item into the set
217 - if inserting is success, calls \p f functor to initialize value-fields of \p val.
219 The functor signature is:
221 void func( value_type& val );
223 where \p val is the item inserted. User-defined functor \p f should guarantee that during changing
224 \p val no any other changes could be made on this set's item by concurrent threads.
225 The user-defined functor is called only if the inserting is success. It may be passed by reference
228 template <typename Q, typename Func>
229 bool insert( Q const& val, Func f )
231 scoped_node_ptr sp( cxx_leaf_node_allocator().New( val ));
232 if ( base_class::insert( *sp.get(), [&f]( leaf_node& val ) { f( val.m_Value ); } )) {
239 /// Ensures that the item exists in the set
241 The operation performs inserting or changing data with lock-free manner.
243 If the \p val key not found in the set, then the new item created from \p val
244 is inserted into the set. Otherwise, the functor \p func is called with the item found.
245 The functor \p Func should be a function with signature:
247 void func( bool bNew, value_type& item, const Q& val );
252 void operator()( bool bNew, value_type& item, const Q& val );
257 - \p bNew - \p true if the item has been inserted, \p false otherwise
258 - \p item - item of the set
259 - \p val - argument \p key passed into the \p ensure function
261 The functor may change non-key fields of the \p item; however, \p func must guarantee
262 that during changing no any other modifications could be made on this item by concurrent threads.
264 You may pass \p func argument by reference using \p std::ref.
266 Returns <tt> std::pair<bool, bool> </tt> where \p first is true if operation is successfull,
267 \p second is true if new item has been added or \p false if the item with \p key
268 already is in the set.
270 template <typename Q, typename Func>
271 std::pair<bool, bool> ensure( const Q& val, Func func )
273 scoped_node_ptr sp( cxx_leaf_node_allocator().New( val ));
274 std::pair<bool, bool> bRes = base_class::ensure( *sp,
275 [&func, &val](bool bNew, leaf_node& node, leaf_node&){ func( bNew, node.m_Value, val ); });
276 if ( bRes.first && bRes.second )
281 /// Inserts data of type \ref value_type constructed with <tt>std::forward<Args>(args)...</tt>
283 Returns \p true if inserting successful, \p false otherwise.
285 template <typename... Args>
286 bool emplace( Args&&... args )
288 scoped_node_ptr sp( cxx_leaf_node_allocator().New( std::forward<Args>(args)... ));
289 if ( base_class::insert( *sp.get() )) {
296 /// Delete \p key from the set
297 /** \anchor cds_nonintrusive_EllenBinTreeSet_erase_val
299 The item comparator should be able to compare the type \p value_type
302 Return \p true if key is found and deleted, \p false otherwise
304 template <typename Q>
305 bool erase( Q const& key )
307 return base_class::erase( key );
310 /// Deletes the item from the set using \p pred predicate for searching
312 The function is an analog of \ref cds_nonintrusive_EllenBinTreeSet_erase_val "erase(Q const&)"
313 but \p pred is used for key comparing.
314 \p Less functor has the interface like \p std::less.
315 \p Less must imply the same element order as the comparator used for building the set.
317 template <typename Q, typename Less>
318 bool erase_with( Q const& key, Less pred )
320 return base_class::erase_with( key, cds::details::predicate_wrapper< leaf_node, Less, typename maker::value_accessor >());
323 /// Delete \p key from the set
324 /** \anchor cds_nonintrusive_EllenBinTreeSet_erase_func
326 The function searches an item with key \p key, calls \p f functor
327 and deletes the item. If \p key is not found, the functor is not called.
329 The functor \p Func interface:
332 void operator()(value_type const& val);
335 The functor may be passed by reference using <tt>boost:ref</tt>
337 Since the key of MichaelHashSet's \p value_type is not explicitly specified,
338 template parameter \p Q defines the key type searching in the list.
339 The list item comparator should be able to compare the type \p T of list item
342 Return \p true if key is found and deleted, \p false otherwise
344 template <typename Q, typename Func>
345 bool erase( Q const& key, Func f )
347 return base_class::erase( key, [&f]( leaf_node const& node) { f( node.m_Value ); } );
350 /// Deletes the item from the set using \p pred predicate for searching
352 The function is an analog of \ref cds_nonintrusive_EllenBinTreeSet_erase_func "erase(Q const&, Func)"
353 but \p pred is used for key comparing.
354 \p Less functor has the interface like \p std::less.
355 \p Less must imply the same element order as the comparator used for building the set.
357 template <typename Q, typename Less, typename Func>
358 bool erase_with( Q const& key, Less pred, Func f )
360 return base_class::erase_with( key, cds::details::predicate_wrapper< leaf_node, Less, typename maker::value_accessor >(),
361 [&f]( leaf_node const& node) { f( node.m_Value ); } );
364 /// Extracts an item with minimal key from the set
366 If the set is not empty, the function returns \p true, \p result contains a pointer to minimum value.
367 If the set is empty, the function returns \p false, \p result is left unchanged.
369 @note Due the concurrent nature of the set, the function extracts <i>nearly</i> minimum key.
370 It means that the function gets leftmost leaf of the tree and tries to unlink it.
371 During unlinking, a concurrent thread may insert an item with key less than leftmost item's key.
372 So, the function returns the item with minimum key at the moment of tree traversing.
374 The guarded pointer \p dest prevents deallocation of returned item,
375 see cds::gc::guarded_ptr for explanation.
376 @note Each \p guarded_ptr object uses the GC's guard that can be limited resource.
378 bool extract_min( guarded_ptr& result )
380 return base_class::extract_min_( result.guard() );
383 /// Extracts an item with maximal key from the set
385 If the set is not empty, the function returns \p true, \p result contains a pointer to maximal value.
386 If the set is empty, the function returns \p false, \p result is left unchanged.
388 @note Due the concurrent nature of the set, the function extracts <i>nearly</i> maximal key.
389 It means that the function gets rightmost leaf of the tree and tries to unlink it.
390 During unlinking, a concurrent thread may insert an item with key great than leftmost item's key.
391 So, the function returns the item with maximum key at the moment of tree traversing.
393 The guarded pointer \p dest prevents deallocation of returned item,
394 see cds::gc::guarded_ptr for explanation.
395 @note Each \p guarded_ptr object uses the GC's guard that can be limited resource.
397 bool extract_max( guarded_ptr& result )
399 return base_class::extract_max_( result.guard() );
402 /// Extracts an item from the tree
403 /** \anchor cds_nonintrusive_EllenBinTreeSet_extract
404 The function searches an item with key equal to \p key in the tree,
405 unlinks it, and returns pointer to an item found in \p result parameter.
406 If the item is not found the function returns \p false.
408 The guarded pointer \p dest prevents deallocation of returned item,
409 see cds::gc::guarded_ptr for explanation.
410 @note Each \p guarded_ptr object uses the GC's guard that can be limited resource.
412 template <typename Q>
413 bool extract( guarded_ptr& result, Q const& key )
415 return base_class::extract_( result.guard(), key );
418 /// Extracts an item from the set using \p pred for searching
420 The function is an analog of \ref cds_nonintrusive_EllenBinTreeSet_extract "extract(guarded_ptr& dest, Q const&)"
421 but \p pred is used for key compare.
422 \p Less has the interface like \p std::less.
423 \p pred must imply the same element order as the comparator used for building the set.
425 template <typename Q, typename Less>
426 bool extract_with( guarded_ptr& result, Q const& key, Less pred )
428 return base_class::extract_with_( result.guard(), key,
429 cds::details::predicate_wrapper< leaf_node, Less, typename maker::value_accessor >());
432 /// Find the key \p val
434 @anchor cds_nonintrusive_EllenBinTreeSet_find_func
436 The function searches the item with key equal to \p val and calls the functor \p f for item found.
437 The interface of \p Func functor is:
440 void operator()( value_type& item, Q& val );
443 where \p item is the item found, \p val is the <tt>find</tt> function argument.
445 You may pass \p f argument by reference using \p std::ref.
447 The functor may change non-key fields of \p item. Note that the functor is only guarantee
448 that \p item cannot be disposed during functor is executing.
449 The functor does not serialize simultaneous access to the set's \p item. If such access is
450 possible you must provide your own synchronization schema on item level to exclude unsafe item modifications.
452 The \p val argument is non-const since it can be used as \p f functor destination i.e., the functor
453 can modify both arguments.
455 Note the hash functor specified for class \p Traits template parameter
456 should accept a parameter of type \p Q that may be not the same as \p value_type.
458 The function returns \p true if \p val is found, \p false otherwise.
460 template <typename Q, typename Func>
461 bool find( Q& val, Func f )
463 return base_class::find( val, [&f]( leaf_node& node, Q& v ) { f( node.m_Value, v ); });
466 /// Finds the key \p val using \p pred predicate for searching
468 The function is an analog of \ref cds_nonintrusive_EllenBinTreeSet_find_func "find(Q&, Func)"
469 but \p pred is used for key comparing.
470 \p Less functor has the interface like \p std::less.
471 \p Less must imply the same element order as the comparator used for building the set.
473 template <typename Q, typename Less, typename Func>
474 bool find_with( Q& val, Less pred, Func f )
476 return base_class::find_with( val, cds::details::predicate_wrapper< leaf_node, Less, typename maker::value_accessor >(),
477 [&f]( leaf_node& node, Q& v ) { f( node.m_Value, v ); } );
480 /// Find the key \p val
481 /** @anchor cds_nonintrusive_EllenBinTreeSet_find_cfunc
483 The function searches the item with key equal to \p val and calls the functor \p f for item found.
484 The interface of \p Func functor is:
487 void operator()( value_type& item, Q const& val );
490 where \p item is the item found, \p val is the <tt>find</tt> function argument.
492 You may pass \p f argument by reference using \p std::ref.
494 The functor may change non-key fields of \p item. Note that the functor is only guarantee
495 that \p item cannot be disposed during functor is executing.
496 The functor does not serialize simultaneous access to the set's \p item. If such access is
497 possible you must provide your own synchronization schema on item level to exclude unsafe item modifications.
499 Note the hash functor specified for class \p Traits template parameter
500 should accept a parameter of type \p Q that may be not the same as \p value_type.
502 The function returns \p true if \p val is found, \p false otherwise.
504 template <typename Q, typename Func>
505 bool find( Q const& val, Func f )
507 return base_class::find( val, [&f]( leaf_node& node, Q const& v ) { f( node.m_Value, v ); });
510 /// Finds the key \p val using \p pred predicate for searching
512 The function is an analog of \ref cds_nonintrusive_EllenBinTreeSet_find_cfunc "find(Q const&, Func)"
513 but \p pred is used for key comparing.
514 \p Less functor has the interface like \p std::less.
515 \p Less must imply the same element order as the comparator used for building the set.
517 template <typename Q, typename Less, typename Func>
518 bool find_with( Q const& val, Less pred, Func f )
520 return base_class::find_with( val, cds::details::predicate_wrapper< leaf_node, Less, typename maker::value_accessor >(),
521 [&f]( leaf_node& node, Q const& v ) { f( node.m_Value, v ); } );
524 /// Find the key \p val
525 /** @anchor cds_nonintrusive_EllenBinTreeSet_find_val
527 The function searches the item with key equal to \p val
528 and returns \p true if it is found, and \p false otherwise.
530 Note the hash functor specified for class \p Traits template parameter
531 should accept a parameter of type \p Q that may be not the same as \ref value_type.
533 template <typename Q>
534 bool find( Q const & val )
536 return base_class::find( val );
539 /// Finds the key \p val using \p pred predicate for searching
541 The function is an analog of \ref cds_nonintrusive_EllenBinTreeSet_find_val "find(Q const&)"
542 but \p pred is used for key comparing.
543 \p Less functor has the interface like \p std::less.
544 \p Less must imply the same element order as the comparator used for building the set.
546 template <typename Q, typename Less>
547 bool find_with( Q const& val, Less pred )
549 return base_class::find_with( val, cds::details::predicate_wrapper< leaf_node, Less, typename maker::value_accessor >());
552 /// Finds \p key and returns the item found
553 /** @anchor cds_nonintrusive_EllenBinTreeSet_get
554 The function searches the item with key equal to \p key and returns the item found in \p result parameter.
555 The function returns \p true if \p key is found, \p false otherwise.
557 The guarded pointer \p dest prevents deallocation of returned item,
558 see cds::gc::guarded_ptr for explanation.
559 @note Each \p guarded_ptr object uses the GC's guard that can be limited resource.
561 template <typename Q>
562 bool get( guarded_ptr& result, Q const& key )
564 return base_class::get_( result.guard(), key );
567 /// Finds \p key with predicate \p pred and returns the item found
569 The function is an analog of \ref cds_nonintrusive_EllenBinTreeSet_get "get(guarded_ptr&, Q const&)"
570 but \p pred is used for key comparing.
571 \p Less functor has the interface like \p std::less.
572 \p pred must imply the same element order as the comparator used for building the set.
574 template <typename Q, typename Less>
575 bool get_with( guarded_ptr& result, Q const& key, Less pred )
577 return base_class::get_with_( result.guard(), key,
578 cds::details::predicate_wrapper< leaf_node, Less, typename maker::value_accessor >() );
581 /// Clears the set (non-atomic)
583 The function unlink all items from the tree.
584 The function is not atomic, thus, in multi-threaded environment with parallel insertions
588 assert( set.empty() );
590 the assertion could be raised.
592 For each leaf the \ref disposer will be called after unlinking.
599 /// Checks if the set is empty
602 return base_class::empty();
605 /// Returns item count in the set
607 Only leaf nodes containing user data are counted.
609 The value returned depends on item counter type provided by \p Traits template parameter.
610 If it is atomicity::empty_item_counter this function always returns 0.
611 Therefore, the function is not suitable for checking the tree emptiness, use \ref empty
612 member function for this purpose.
616 return base_class::size();
619 /// Returns const reference to internal statistics
620 stat const& statistics() const
622 return base_class::statistics();
625 /// Checks internal consistency (not atomic, not thread-safe)
627 The debugging function to check internal consistency of the tree.
629 bool check_consistency() const
631 return base_class::check_consistency();
635 }} // namespace cds::container
637 #endif // #ifndef __CDS_CONTAINER_IMPL_ELLEN_BINTREE_SET_H