3 #ifndef CDSLIB_CONTAINER_MICHAEL_MAP_RCU_H
4 #define CDSLIB_CONTAINER_MICHAEL_MAP_RCU_H
6 #include <cds/container/details/michael_map_base.h>
7 #include <cds/details/allocator.h>
9 namespace cds { namespace container {
11 /// Michael's hash map (template specialization for \ref cds_urcu_desc "RCU")
12 /** @ingroup cds_nonintrusive_map
13 \anchor cds_nonintrusive_MichaelHashMap_rcu
16 - [2002] Maged Michael "High performance dynamic lock-free hash tables and list-based sets"
18 Michael's hash table algorithm is based on lock-free ordered list and it is very simple.
19 The main structure is an array \p T of size \p M. Each element in \p T is basically a pointer
20 to a hash bucket, implemented as a singly linked list. The array of buckets cannot be dynamically expanded.
21 However, each bucket may contain unbounded number of items.
23 Template parameters are:
24 - \p RCU - one of \ref cds_urcu_gc "RCU type"
25 - \p OrderedList - ordered key-value list implementation used as bucket for hash map, for example, \p MichaelKVList.
26 The ordered list implementation specifies the \p Key and \p Value types stored in the hash-map, the reclamation
27 schema \p GC used by hash-map, the comparison functor for the type \p Key and other features specific for
29 - \p Traits - map traits, default is \p michael_map::traits.
30 Instead of defining \p Traits struct you may use option-based syntax with \p michael_map::make_traits metafunction
32 Many of the class function take a key argument of type \p K that in general is not \p key_type.
33 \p key_type and an argument of template type \p K must meet the following requirements:
34 - \p key_type should be constructible from value of type \p K;
35 - the hash functor should be able to calculate correct hash value from argument \p key of type \p K:
36 <tt> hash( key_type(key) ) == hash( key ) </tt>
37 - values of type \p key_type and \p K should be comparable
41 The tips about how to use Michael's map see \ref cds_nonintrusive_MichaelHashMap_how_touse "MichaelHashMap".
42 Remember, that you should include RCU-related header file (for example, <tt>cds/urcu/general_buffered.h</tt>)
43 before including <tt>cds/container/michael_map_rcu.h</tt>.
48 #ifdef CDS_DOXYGEN_INVOKED
49 class Traits = michael_map::traits
54 class MichaelHashMap< cds::urcu::gc< RCU >, OrderedList, Traits >
57 typedef cds::urcu::gc< RCU > gc; ///< RCU used as garbage collector
58 typedef OrderedList bucket_type; ///< type of ordered list used as a bucket implementation
59 typedef Traits traits; ///< Map traits
61 typedef typename bucket_type::key_type key_type ; ///< key type
62 typedef typename bucket_type::mapped_type mapped_type ; ///< value type
63 typedef typename bucket_type::value_type value_type ; ///< key/value pair stored in the list
64 typedef typename bucket_type::key_comparator key_comparator ; ///< key comparison functor
66 /// Hash functor for \ref key_type and all its derivatives that you use
67 typedef typename cds::opt::v::hash_selector< typename traits::hash >::type hash;
68 typedef typename traits::item_counter item_counter; ///< Item counter type
70 /// Bucket table allocator
71 typedef cds::details::Allocator< bucket_type, typename traits::allocator > bucket_table_allocator;
73 typedef typename bucket_type::rcu_lock rcu_lock; ///< RCU scoped lock
74 typedef typename bucket_type::exempt_ptr exempt_ptr; ///< pointer to extracted node
75 /// Group of \p extract_xxx functions require external locking if underlying ordered list requires that
76 static CDS_CONSTEXPR const bool c_bExtractLockExternal = bucket_type::c_bExtractLockExternal;
77 /// Type of \p get() member function return value
78 typedef typename bucket_type::raw_ptr raw_ptr;
81 typedef cds::container::michael_map::implementation_tag implementation_tag;
85 item_counter m_ItemCounter; ///< Item counter
86 hash m_HashFunctor; ///< Hash functor
87 bucket_type * m_Buckets; ///< bucket table
91 const size_t m_nHashBitmask;
96 /// Calculates hash value of \p key
98 size_t hash_value( Q const& key ) const
100 return m_HashFunctor( key ) & m_nHashBitmask;
103 /// Returns the bucket (ordered list) for \p key
104 template <typename Q>
105 bucket_type& bucket( Q const& key )
107 return m_Buckets[ hash_value( key ) ];
109 template <typename Q>
110 bucket_type const& bucket( Q const& key ) const
112 return m_Buckets[ hash_value( key ) ];
118 \p IsConst - constness boolean flag
120 The forward iterator for Michael's map is based on \p OrderedList forward iterator and has the following features:
121 - it has no post-increment operator, only pre-increment
122 - it iterates items in unordered fashion
123 - The iterator cannot be moved across thread boundary since it may contain GC's guard that is thread-private GC data.
124 - Iterator ensures thread-safety even if you delete the item that iterator points to. However, in case of concurrent
125 deleting operations it is no guarantee that you iterate all item in the map.
127 Therefore, the use of iterators in concurrent environment is not good idea. Use the iterator for the concurrent container
128 for debug purpose only.
130 template <bool IsConst>
131 class iterator_type: private cds::intrusive::michael_set::details::iterator< bucket_type, IsConst >
134 typedef cds::intrusive::michael_set::details::iterator< bucket_type, IsConst > base_class;
135 friend class MichaelHashMap;
140 //typedef typename base_class::bucket_type bucket_type;
141 typedef typename base_class::bucket_ptr bucket_ptr;
142 typedef typename base_class::list_iterator list_iterator;
144 //typedef typename bucket_type::key_type key_type;
148 /// Value pointer type (const for const_iterator)
149 typedef typename cds::details::make_const_type<typename MichaelHashMap::mapped_type, IsConst>::pointer value_ptr;
150 /// Value reference type (const for const_iterator)
151 typedef typename cds::details::make_const_type<typename MichaelHashMap::mapped_type, IsConst>::reference value_ref;
153 /// Key-value pair pointer type (const for const_iterator)
154 typedef typename cds::details::make_const_type<typename MichaelHashMap::value_type, IsConst>::pointer pair_ptr;
155 /// Key-value pair reference type (const for const_iterator)
156 typedef typename cds::details::make_const_type<typename MichaelHashMap::value_type, IsConst>::reference pair_ref;
160 iterator_type( list_iterator const& it, bucket_ptr pFirst, bucket_ptr pLast )
161 : base_class( it, pFirst, pLast )
172 iterator_type( const iterator_type& src )
176 /// Dereference operator
177 pair_ptr operator ->() const
179 assert( base_class::m_pCurBucket != nullptr );
180 return base_class::m_itList.operator ->();
183 /// Dereference operator
184 pair_ref operator *() const
186 assert( base_class::m_pCurBucket != nullptr );
187 return base_class::m_itList.operator *();
191 iterator_type& operator ++()
193 base_class::operator++();
197 /// Assignment operator
198 iterator_type& operator = (const iterator_type& src)
200 base_class::operator =(src);
204 /// Returns current bucket (debug function)
205 bucket_ptr bucket() const
207 return base_class::bucket();
210 /// Equality operator
212 bool operator ==(iterator_type<C> const& i )
214 return base_class::operator ==( i );
216 /// Equality operator
218 bool operator !=(iterator_type<C> const& i )
220 return !( *this == i );
226 typedef iterator_type< false > iterator;
228 /// Const forward iterator
229 typedef iterator_type< true > const_iterator;
231 /// Returns a forward iterator addressing the first element in a map
233 For empty map \code begin() == end() \endcode
237 return iterator( m_Buckets[0].begin(), m_Buckets, m_Buckets + bucket_count() );
240 /// Returns an iterator that addresses the location succeeding the last element in a map
242 Do not use the value returned by <tt>end</tt> function to access any item.
243 The returned value can be used only to control reaching the end of the map.
244 For empty map \code begin() == end() \endcode
248 return iterator( m_Buckets[bucket_count() - 1].end(), m_Buckets + bucket_count() - 1, m_Buckets + bucket_count() );
251 /// Returns a forward const iterator addressing the first element in a map
253 const_iterator begin() const
255 return get_const_begin();
257 const_iterator cbegin() const
259 return get_const_begin();
263 /// Returns an const iterator that addresses the location succeeding the last element in a map
265 const_iterator end() const
267 return get_const_end();
269 const_iterator cend() const
271 return get_const_end();
277 const_iterator get_const_begin() const
279 return const_iterator( const_cast<bucket_type const&>(m_Buckets[0]).begin(), m_Buckets, m_Buckets + bucket_count() );
281 const_iterator get_const_end() const
283 return const_iterator( const_cast<bucket_type const&>(m_Buckets[bucket_count() - 1]).end(), m_Buckets + bucket_count() - 1, m_Buckets + bucket_count() );
288 /// Initializes the map
289 /** @copydetails cds_nonintrusive_MichaelHashMap_hp_ctor
292 size_t nMaxItemCount, ///< estimation of max item count in the hash map
293 size_t nLoadFactor ///< load factor: estimation of max number of items in the bucket
294 ) : m_nHashBitmask( michael_map::details::init_hash_bitmask( nMaxItemCount, nLoadFactor ))
296 // GC and OrderedList::gc must be the same
297 static_assert( std::is_same<gc, typename bucket_type::gc>::value, "GC and OrderedList::gc must be the same");
299 // atomicity::empty_item_counter is not allowed as a item counter
300 static_assert( !std::is_same<item_counter, cds::atomicity::empty_item_counter>::value,
301 "cds::atomicity::empty_item_counter is not allowed as a item counter");
303 m_Buckets = bucket_table_allocator().NewArray( bucket_count() );
306 /// Clears hash map and destroys it
310 bucket_table_allocator().Delete( m_Buckets, bucket_count() );
313 /// Inserts new node with key and default value
315 The function creates a node with \p key and default value, and then inserts the node created into the map.
318 - The \p key_type should be constructible from value of type \p K.
319 In trivial case, \p K is equal to \ref key_type.
320 - The \p mapped_type should be default-constructible.
322 The function applies RCU lock internally.
324 Returns \p true if inserting successful, \p false otherwise.
326 template <typename K>
327 bool insert( const K& key )
329 const bool bRet = bucket( key ).insert( key );
337 The function creates a node with copy of \p val value
338 and then inserts the node created into the map.
341 - The \p key_type should be constructible from \p key of type \p K.
342 - The \p mapped_type should be constructible from \p val of type \p V.
344 The function applies RCU lock internally.
346 Returns \p true if \p val is inserted into the map, \p false otherwise.
348 template <typename K, typename V>
349 bool insert( K const& key, V const& val )
351 const bool bRet = bucket( key ).insert( key, val );
357 /// Inserts new node and initialize it by a functor
359 This function inserts new node with key \p key and if inserting is successful then it calls
360 \p func functor with signature
363 void operator()( value_type& item );
367 The argument \p item of user-defined functor \p func is the reference
368 to the map's item inserted:
369 - <tt>item.first</tt> is a const reference to item's key that cannot be changed.
370 - <tt>item.second</tt> is a reference to item's value that may be changed.
372 The user-defined functor is called only if inserting is successful.
374 The key_type should be constructible from value of type \p K.
376 The function allows to split creating of new item into two part:
377 - create item from \p key;
378 - insert new item into the map;
379 - if inserting is successful, initialize the value of item by calling \p func functor
381 This can be useful if complete initialization of object of \p mapped_type is heavyweight and
382 it is preferable that the initialization should be completed only if inserting is successful.
384 The function applies RCU lock internally.
386 @warning For \ref cds_nonintrusive_MichaelKVList_rcu "MichaelKVList" as the bucket see \ref cds_intrusive_item_creating "insert item troubleshooting".
387 \ref cds_nonintrusive_LazyKVList_rcu "LazyKVList" provides exclusive access to inserted item and does not require any node-level
390 template <typename K, typename Func>
391 bool insert_with( const K& key, Func func )
393 const bool bRet = bucket( key ).insert_with( key, func );
400 /// Ensures that the \p key exists in the map
402 The operation performs inserting or changing data with lock-free manner.
404 If the \p key not found in the map, then the new item created from \p key
405 is inserted into the map (note that in this case the \ref key_type should be
406 constructible from type \p K).
407 Otherwise, the functor \p func is called with item found.
408 The functor \p Func may be a function with signature:
410 void func( bool bNew, value_type& item );
415 void operator()( bool bNew, value_type& item );
420 - \p bNew - \p true if the item has been inserted, \p false otherwise
421 - \p item - item of the list
423 The functor may change any fields of the \p item.second that is \ref mapped_type.
425 The function applies RCU lock internally.
427 Returns <tt> std::pair<bool, bool> </tt> where \p first is true if operation is successfull,
428 \p second is true if new item has been added or \p false if the item with \p key
429 already is in the list.
431 @warning For \ref cds_nonintrusive_MichaelKVList_rcu "MichaelKVList" as the bucket see \ref cds_intrusive_item_creating "insert item troubleshooting".
432 \ref cds_nonintrusive_LazyKVList_rcu "LazyKVList" provides exclusive access to inserted item and does not require any node-level
435 template <typename K, typename Func>
436 std::pair<bool, bool> ensure( K const& key, Func func )
438 std::pair<bool, bool> bRet = bucket( key ).ensure( key, func );
439 if ( bRet.first && bRet.second )
444 /// For key \p key inserts data of type \p mapped_type created from \p args
446 \p key_type should be constructible from type \p K
448 Returns \p true if inserting successful, \p false otherwise.
450 template <typename K, typename... Args>
451 bool emplace( K&& key, Args&&... args )
453 const bool bRet = bucket( key ).emplace( std::forward<K>(key), std::forward<Args>(args)... );
459 /// Deletes \p key from the map
460 /** \anchor cds_nonintrusive_MichaelMap_rcu_erase_val
462 RCU \p synchronize method can be called. RCU should not be locked.
464 Return \p true if \p key is found and deleted, \p false otherwise
466 template <typename K>
467 bool erase( const K& key )
469 const bool bRet = bucket( key ).erase( key );
475 /// Deletes the item from the map using \p pred predicate for searching
477 The function is an analog of \ref cds_nonintrusive_MichaelMap_rcu_erase_val "erase(K const&)"
478 but \p pred is used for key comparing.
479 \p Less predicate has the interface like \p std::less.
480 \p Less must imply the same element order as the comparator used for building the map.
482 template <typename K, typename Less>
483 bool erase_with( const K& key, Less pred )
485 const bool bRet = bucket( key ).erase_with( key, pred );
491 /// Deletes \p key from the map
492 /** \anchor cds_nonintrusive_MichaelMap_rcu_erase_func
494 The function searches an item with key \p key, calls \p f functor
495 and deletes the item. If \p key is not found, the functor is not called.
497 The functor \p Func interface:
500 void operator()(value_type& item) { ... }
504 RCU \p synchronize method can be called. RCU should not be locked.
506 Return \p true if key is found and deleted, \p false otherwise
508 template <typename K, typename Func>
509 bool erase( const K& key, Func f )
511 const bool bRet = bucket( key ).erase( key, f );
517 /// Deletes the item from the map using \p pred predicate for searching
519 The function is an analog of \ref cds_nonintrusive_MichaelMap_rcu_erase_func "erase(K const&, Func)"
520 but \p pred is used for key comparing.
521 \p Less functor has the interface like \p std::less.
522 \p Less must imply the same element order as the comparator used for building the map.
524 template <typename K, typename Less, typename Func>
525 bool erase_with( const K& key, Less pred, Func f )
527 const bool bRet = bucket( key ).erase_with( key, pred, f );
533 /// Extracts an item from the map
534 /** \anchor cds_nonintrusive_MichaelHashMap_rcu_extract
535 The function searches an item with key equal to \p key,
536 unlinks it from the map, and returns \ref cds::urcu::exempt_ptr "exempt_ptr" pointer to the item found.
537 If the item is not found the function return an empty \p exempt_ptr.
539 The function just excludes the key from the map and returns a pointer to item found.
540 Depends on \p bucket_type you should or should not lock RCU before calling of this function:
541 - for the set based on \ref cds_nonintrusive_MichaelList_rcu "MichaelList" RCU should not be locked
542 - for the set based on \ref cds_nonintrusive_LazyList_rcu "LazyList" RCU should be locked
543 See ordered list implementation for details.
546 #include <cds/urcu/general_buffered.h>
547 #include <cds/container/michael_kvlist_rcu.h>
548 #include <cds/container/michael_map_rcu.h>
550 typedef cds::urcu::gc< general_buffered<> > rcu;
551 typedef cds::container::MichaelKVList< rcu, int, Foo > rcu_michael_list;
552 typedef cds::container::MichaelHashMap< rcu, rcu_michael_list, foo_traits > rcu_michael_map;
554 rcu_michael_map theMap;
557 rcu_michael_map::exempt_ptr p;
559 // For MichaelList we should not lock RCU
561 // Note that you must not delete the item found inside the RCU lock
562 p = theMap.extract( 10 );
564 // do something with p
568 // We may safely release p here
569 // release() passes the pointer to RCU reclamation cycle
573 template <typename K>
574 exempt_ptr extract( K const& key )
576 exempt_ptr p = bucket( key ).extract( key );
582 /// Extracts an item from the map using \p pred predicate for searching
584 The function is an analog of \p extract(K const&) but \p pred is used for key comparing.
585 \p Less functor has the interface like \p std::less.
586 \p pred must imply the same element order as the comparator used for building the map.
588 template <typename K, typename Less>
589 exempt_ptr extract_with( K const& key, Less pred )
591 exempt_ptr p = bucket( key ).extract_with( key, pred );
597 /// Finds the key \p key
598 /** \anchor cds_nonintrusive_MichaelMap_rcu_find_cfunc
600 The function searches the item with key equal to \p key and calls the functor \p f for item found.
601 The interface of \p Func functor is:
604 void operator()( value_type& item );
607 where \p item is the item found.
609 The functor may change \p item.second. Note that the functor is only guarantee
610 that \p item cannot be disposed during functor is executing.
611 The functor does not serialize simultaneous access to the map's \p item. If such access is
612 possible you must provide your own synchronization schema on item level to exclude unsafe item modifications.
614 The function applies RCU lock internally.
616 The function returns \p true if \p key is found, \p false otherwise.
618 template <typename K, typename Func>
619 bool find( K const& key, Func f )
621 return bucket( key ).find( key, f );
624 /// Finds the key \p val using \p pred predicate for searching
626 The function is an analog of \ref cds_nonintrusive_MichaelMap_rcu_find_cfunc "find(K const&, Func)"
627 but \p pred is used for key comparing.
628 \p Less functor has the interface like \p std::less.
629 \p Less must imply the same element order as the comparator used for building the map.
631 template <typename K, typename Less, typename Func>
632 bool find_with( K const& key, Less pred, Func f )
634 return bucket( key ).find_with( key, pred, f );
637 /// Finds the key \p key
638 /** \anchor cds_nonintrusive_MichaelMap_rcu_find_val
640 The function searches the item with key equal to \p key
641 and returns \p true if it is found, and \p false otherwise.
643 The function applies RCU lock internally.
645 template <typename K>
646 bool find( K const& key )
648 return bucket( key ).find( key );
651 /// Finds the key \p val using \p pred predicate for searching
653 The function is an analog of \ref cds_nonintrusive_MichaelMap_rcu_find_val "find(K const&)"
654 but \p pred is used for key comparing.
655 \p Less functor has the interface like \p std::less.
656 \p Less must imply the same element order as the comparator used for building the map.
658 template <typename K, typename Less>
659 bool find_with( K const& key, Less pred )
661 return bucket( key ).find_with( key, pred );
664 /// Finds \p key and return the item found
665 /** \anchor cds_nonintrusive_MichaelHashMap_rcu_get
666 The function searches the item with key equal to \p key and returns the pointer to item found.
667 If \p key is not found it returns \p nullptr.
668 Note the type of returned value depends on underlying \p bucket_type.
669 For details, see documentation of ordered list you use.
671 Note the compare functor should accept a parameter of type \p K that can be not the same as \p key_type.
673 RCU should be locked before call of this function.
674 Returned item is valid only while RCU is locked:
676 typedef cds::container::MichaelHashMap< your_template_parameters > hash_map;
679 typename hash_map::raw_ptr gp;
682 hash_map::rcu_lock lock;
684 gp = theMap.get( 5 );
689 // Unlock RCU by rcu_lock destructor
690 // gp can be reclaimed at any time after RCU has been unlocked
694 template <typename K>
695 raw_ptr get( K const& key )
697 return bucket( key ).get( key );
700 /// Finds \p key and return the item found
702 The function is an analog of \ref cds_nonintrusive_MichaelHashMap_rcu_get "get(K const&)"
703 but \p pred is used for comparing the keys.
705 \p Less functor has the semantics like \p std::less but should take arguments of type \ref key_type and \p K
707 \p pred must imply the same element order as the comparator used for building the map.
709 template <typename K, typename Less>
710 raw_ptr get_with( K const& key, Less pred )
712 return bucket( key ).get_with( key, pred );
715 /// Clears the map (not atomic)
717 The function erases all items from the map.
719 The function is not atomic. It cleans up each bucket and then resets the item counter to zero.
720 If there are a thread that performs insertion while \p clear is working the result is undefined in general case:
721 <tt> empty() </tt> may return \p true but the map may contain item(s).
722 Therefore, \p clear may be used only for debugging purposes.
724 RCU \p synchronize method can be called. RCU should not be locked.
728 for ( size_t i = 0; i < bucket_count(); ++i )
729 m_Buckets[i].clear();
730 m_ItemCounter.reset();
733 /// Checks if the map is empty
735 Emptiness is checked by item counting: if item count is zero then the map is empty.
736 Thus, the correct item counting is an important part of the map implementation.
743 /// Returns item count in the map
746 return m_ItemCounter;
749 /// Returns the size of hash table
751 Since \p %MichaelHashMap cannot dynamically extend the hash table size,
752 the value returned is an constant depending on object initialization parameters;
753 see \p MichaelHashMap::MichaelHashMap for explanation.
755 size_t bucket_count() const
757 return m_nHashBitmask + 1;
760 }} // namespace cds::container
762 #endif // ifndef CDSLIB_CONTAINER_MICHAEL_MAP_RCU_H