3 #ifndef __CDS_CONTAINER_MICHAEL_MAP_NOGC_H
4 #define __CDS_CONTAINER_MICHAEL_MAP_NOGC_H
6 #include <cds/container/details/michael_map_base.h>
7 #include <cds/gc/nogc.h>
8 #include <cds/details/allocator.h>
10 namespace cds { namespace container {
12 /// Michael's hash map (template specialization for gc::nogc)
13 /** @ingroup cds_nonintrusive_map
14 \anchor cds_nonintrusive_MichaelHashMap_nogc
16 This specialization is intended for so-called persistent usage when no item
17 reclamation may be performed. The class does not support deleting of map item.
19 See \ref cds_nonintrusive_MichaelHashMap_hp "MichaelHashMap" for description of template parameters.
21 The interface of the specialization is a little different.
25 #ifdef CDS_DOXYGEN_INVOKED
26 class Traits = michael_map::type_traits
31 class MichaelHashMap<gc::nogc, OrderedList, Traits>
34 typedef OrderedList bucket_type ; ///< type of ordered list used as a bucket implementation
35 typedef Traits options ; ///< Traits template parameters
37 typedef typename bucket_type::key_type key_type ; ///< key type
38 typedef typename bucket_type::mapped_type mapped_type ; ///< type of value stored in the list
39 typedef typename bucket_type::value_type value_type ; ///< Pair used as the some functor's argument
41 typedef gc::nogc gc ; ///< No garbage collector
42 typedef typename bucket_type::key_comparator key_comparator ; ///< key comparison functor
44 /// Hash functor for \ref key_type and all its derivatives that you use
45 typedef typename cds::opt::v::hash_selector< typename options::hash >::type hash;
46 typedef typename options::item_counter item_counter ; ///< Item counter type
48 /// Bucket table allocator
49 typedef cds::details::Allocator< bucket_type, typename options::allocator > bucket_table_allocator;
53 typedef typename bucket_type::iterator bucket_iterator;
54 typedef typename bucket_type::const_iterator bucket_const_iterator;
58 item_counter m_ItemCounter ; ///< Item counter
59 hash m_HashFunctor ; ///< Hash functor
61 bucket_type * m_Buckets ; ///< bucket table
65 const size_t m_nHashBitmask;
69 /// Calculates hash value of \p key
70 size_t hash_value( key_type const & key ) const
72 return m_HashFunctor( key ) & m_nHashBitmask;
75 /// Returns the bucket (ordered list) for \p key
76 bucket_type& bucket( key_type const& key )
78 return m_Buckets[ hash_value( key ) ];
85 \p IsConst - constness boolean flag
87 The forward iterator for Michael's map is based on \p OrderedList forward iterator and has some features:
88 - it has no post-increment operator, only pre-increment
89 - it iterates items in unordered fashion
91 template <bool IsConst>
92 class iterator_type: private cds::intrusive::michael_set::details::iterator< bucket_type, IsConst >
95 typedef cds::intrusive::michael_set::details::iterator< bucket_type, IsConst > base_class;
96 friend class MichaelHashMap;
101 //typedef typename base_class::bucket_type bucket_type;
102 typedef typename base_class::bucket_ptr bucket_ptr;
103 typedef typename base_class::list_iterator list_iterator;
105 //typedef typename bucket_type::key_type key_type;
109 /// Value pointer type (const for const_iterator)
110 typedef typename cds::details::make_const_type<typename MichaelHashMap::mapped_type, IsConst>::pointer value_ptr;
111 /// Value reference type (const for const_iterator)
112 typedef typename cds::details::make_const_type<typename MichaelHashMap::mapped_type, IsConst>::reference value_ref;
114 /// Key-value pair pointer type (const for const_iterator)
115 typedef typename cds::details::make_const_type<typename MichaelHashMap::value_type, IsConst>::pointer pair_ptr;
116 /// Key-value pair reference type (const for const_iterator)
117 typedef typename cds::details::make_const_type<typename MichaelHashMap::value_type, IsConst>::reference pair_ref;
121 iterator_type( list_iterator const& it, bucket_ptr pFirst, bucket_ptr pLast )
122 : base_class( it, pFirst, pLast )
133 iterator_type( const iterator_type& src )
137 /// Dereference operator
138 pair_ptr operator ->() const
140 assert( base_class::m_pCurBucket != nullptr );
141 return base_class::m_itList.operator ->();
144 /// Dereference operator
145 pair_ref operator *() const
147 assert( base_class::m_pCurBucket != nullptr );
148 return base_class::m_itList.operator *();
152 iterator_type& operator ++()
154 base_class::operator++();
158 /// Assignment operator
159 iterator_type& operator = (const iterator_type& src)
161 base_class::operator =(src);
165 /// Returns current bucket (debug function)
166 bucket_ptr bucket() const
168 return base_class::bucket();
171 /// Equality operator
173 bool operator ==(iterator_type<C> const& i )
175 return base_class::operator ==( i );
177 /// Equality operator
179 bool operator !=(iterator_type<C> const& i )
181 return !( *this == i );
188 typedef iterator_type< false > iterator;
190 /// Const forward iterator
191 typedef iterator_type< true > const_iterator;
193 /// Returns a forward iterator addressing the first element in a set
195 For empty set \code begin() == end() \endcode
199 return iterator( m_Buckets[0].begin(), m_Buckets, m_Buckets + bucket_count() );
202 /// Returns an iterator that addresses the location succeeding the last element in a set
204 Do not use the value returned by <tt>end</tt> function to access any item.
205 The returned value can be used only to control reaching the end of the set.
206 For empty set \code begin() == end() \endcode
210 return iterator( m_Buckets[bucket_count() - 1].end(), m_Buckets + bucket_count() - 1, m_Buckets + bucket_count() );
213 /// Returns a forward const iterator addressing the first element in a set
215 const_iterator begin() const
217 return get_const_begin();
219 const_iterator cbegin()
221 return get_const_begin();
225 /// Returns an const iterator that addresses the location succeeding the last element in a set
227 const_iterator end() const
229 return get_const_end();
231 const_iterator cend()
233 return get_const_end();
239 const_iterator get_const_begin() const
241 return const_iterator( const_cast<bucket_type const&>(m_Buckets[0]).begin(), m_Buckets, m_Buckets + bucket_count() );
243 const_iterator get_const_end() const
245 return const_iterator( const_cast<bucket_type const&>(m_Buckets[bucket_count() - 1]).end(), m_Buckets + bucket_count() - 1, m_Buckets + bucket_count() );
250 /// Initialize the map
252 The Michael's hash map is non-expandable container. You should point the average count of items \p nMaxItemCount
253 when you create an object.
254 \p nLoadFactor parameter defines average count of items per bucket and it should be small number between 1 and 10.
255 Remember, since the bucket implementation is an ordered list, searching in the bucket is linear [<tt>O(nLoadFactor)</tt>].
256 Note, that many popular STL hash map implementation uses load factor 1.
258 The ctor defines hash table size as rounding <tt>nMacItemCount / nLoadFactor</tt> up to nearest power of two.
261 size_t nMaxItemCount, ///< estimation of max item count in the hash set
262 size_t nLoadFactor ///< load factor: estimation of max number of items in the bucket
263 ) : m_nHashBitmask( michael_map::details::init_hash_bitmask( nMaxItemCount, nLoadFactor ))
265 // GC and OrderedList::gc must be the same
266 static_assert(( std::is_same<gc, typename bucket_type::gc>::value ), "GC and OrderedList::gc must be the same");
268 // atomicity::empty_item_counter is not allowed as a item counter
269 static_assert(( !std::is_same<item_counter, atomicity::empty_item_counter>::value ),"atomicity::empty_item_counter is not allowed as a item counter");
271 m_Buckets = bucket_table_allocator().NewArray( bucket_count() );
274 /// Clear hash set and destroy it
278 bucket_table_allocator().Delete( m_Buckets, bucket_count() );
281 /// Inserts new node with key and default value
283 The function creates a node with \p key and default value, and then inserts the node created into the map.
286 - The \ref key_type should be constructible from value of type \p K.
287 In trivial case, \p K is equal to \ref key_type.
288 - The \ref mapped_type should be default-constructible.
290 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
292 template <typename K>
293 iterator insert( const K& key )
295 bucket_type& refBucket = bucket( key );
296 bucket_iterator it = refBucket.insert( key );
298 if ( it != refBucket.end() ) {
300 return iterator( it, &refBucket, m_Buckets + bucket_count() );
308 The function creates a node with copy of \p val value
309 and then inserts the node created into the map.
312 - The \ref key_type should be constructible from \p key of type \p K.
313 - The \ref mapped_type should be constructible from \p val of type \p V.
315 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
317 template <typename K, typename V>
318 iterator insert( K const& key, V const& val )
320 bucket_type& refBucket = bucket( key );
321 bucket_iterator it = refBucket.insert( key, val );
323 if ( it != refBucket.end() ) {
325 return iterator( it, &refBucket, m_Buckets + bucket_count() );
331 /// Inserts new node and initialize it by a functor
333 This function inserts new node with key \p key and if inserting is successful then it calls
334 \p func functor with signature
337 void operator()( value_type& item );
341 The argument \p item of user-defined functor \p func is the reference
342 to the map's item inserted. <tt>item.second</tt> is a reference to item's value that may be changed.
343 User-defined functor \p func should guarantee that during changing item's value no any other changes
344 could be made on this map's item by concurrent threads.
345 The user-defined functor can be passed by reference using \p std::ref
346 and it is called only if the inserting is successful.
348 The key_type should be constructible from value of type \p K.
350 The function allows to split creating of new item into two part:
351 - create item from \p key;
352 - insert new item into the map;
353 - if inserting is successful, initialize the value of item by calling \p f functor
355 This can be useful if complete initialization of object of \p mapped_type is heavyweight and
356 it is preferable that the initialization should be completed only if inserting is successful.
358 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
360 template <typename K, typename Func>
361 iterator insert_key( const K& key, Func func )
363 bucket_type& refBucket = bucket( key );
364 bucket_iterator it = refBucket.insert_key( key, func );
366 if ( it != refBucket.end() ) {
368 return iterator( it, &refBucket, m_Buckets + bucket_count() );
374 /// For key \p key inserts data of type \ref mapped_type constructed with <tt>std::forward<Args>(args)...</tt>
376 \p key_type should be constructible from type \p K
378 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
380 template <typename K, typename... Args>
381 iterator emplace( K&& key, Args&&... args )
383 bucket_type& refBucket = bucket( key );
384 bucket_iterator it = refBucket.emplace( std::forward<K>(key), std::forward<Args>(args)... );
386 if ( it != refBucket.end() ) {
388 return iterator( it, &refBucket, m_Buckets + bucket_count() );
394 /// Ensures that the key \p key exists in the map
396 The operation inserts new item if the key \p key is not found in the map.
397 Otherwise, the function returns an iterator that points to item found.
399 Returns <tt> std::pair<iterator, bool> </tt> where \p first is an iterator pointing to
400 item found or inserted, \p second is true if new item has been added or \p false if the item
401 already is in the list.
403 template <typename K>
404 std::pair<iterator, bool> ensure( const K& key )
406 bucket_type& refBucket = bucket( key );
407 std::pair<bucket_iterator, bool> ret = refBucket.ensure( key );
412 return std::make_pair( iterator( ret.first, &refBucket, m_Buckets + bucket_count() ), ret.second );
415 /// Find the key \p key
416 /** \anchor cds_nonintrusive_MichaelMap_nogc_find
418 The function searches the item with key equal to \p key
419 and returns an iterator pointed to item found if the key is found,
420 and \ref end() otherwise
422 template <typename K>
423 iterator find( const K& key )
425 bucket_type& refBucket = bucket( key );
426 bucket_iterator it = refBucket.find( key );
428 if ( it != refBucket.end() )
429 return iterator( it, &refBucket, m_Buckets + bucket_count() );
434 /// Finds the key \p val using \p pred predicate for searching
436 The function is an analog of \ref cds_nonintrusive_MichaelMap_nogc_find "find(K const&)"
437 but \p pred is used for key comparing.
438 \p Less functor has the interface like \p std::less.
439 \p Less must imply the same element order as the comparator used for building the map.
441 template <typename K, typename Less>
442 iterator find_with( const K& key, Less pred )
444 bucket_type& refBucket = bucket( key );
445 bucket_iterator it = refBucket.find_with( key, pred );
447 if ( it != refBucket.end() )
448 return iterator( it, &refBucket, m_Buckets + bucket_count() );
453 /// Clears the map (non-atomic)
455 The function deletes all items from the map.
456 The function is not atomic. It cleans up each bucket and then resets the item counter to zero.
457 If there are a thread that performs insertion while \p clear is working the result is undefined in general case:
458 <tt> empty() </tt> may return \p true but the map may contain item(s).
462 for ( size_t i = 0; i < bucket_count(); ++i )
463 m_Buckets[i].clear();
464 m_ItemCounter.reset();
468 /// Checks if the map is empty
470 Emptiness is checked by item counting: if item count is zero then the map is empty.
471 Thus, the correct item counting feature is an important part of Michael's map implementation.
478 /// Returns item count in the map
481 return m_ItemCounter;
484 /// Returns the size of hash table
486 Since MichaelHashMap cannot dynamically extend the hash table size,
487 the value returned is an constant depending on object initialization parameters;
488 see MichaelHashMap::MichaelHashMap for explanation.
490 size_t bucket_count() const
492 return m_nHashBitmask + 1;
496 }} // namespace cds::container
498 #endif // ifndef __CDS_CONTAINER_MICHAEL_MAP_NOGC_H