3 #ifndef CDSLIB_CONTAINER_MICHAEL_MAP_NOGC_H
4 #define CDSLIB_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 \p cds::gc::nogc)
13 /** @ingroup cds_nonintrusive_map
14 \anchor cds_nonintrusive_MichaelHashMap_nogc
16 This specialization is so-called append-only 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.
23 #ifdef CDS_DOXYGEN_INVOKED
24 class Traits = michael_map::traits
29 class MichaelHashMap<cds::gc::nogc, OrderedList, Traits>
32 typedef cds::gc::nogc gc; ///< No garbage collector
33 typedef OrderedList bucket_type; ///< type of ordered list used as a bucket implementation
34 typedef Traits traits; ///< Map traits
36 typedef typename bucket_type::key_type key_type; ///< key type
37 typedef typename bucket_type::mapped_type mapped_type; ///< type of value to be stored in the map
38 typedef typename bucket_type::value_type value_type; ///< Pair used as the some functor's argument
40 typedef typename bucket_type::key_comparator key_comparator; ///< key comparing functor
42 /// Hash functor for \ref key_type and all its derivatives that you use
43 typedef typename cds::opt::v::hash_selector< typename traits::hash >::type hash;
44 typedef typename traits::item_counter item_counter; ///< Item counter type
46 /// Bucket table allocator
47 typedef cds::details::Allocator< bucket_type, typename traits::allocator > bucket_table_allocator;
50 typedef cds::container::michael_map::implementation_tag implementation_tag;
55 typedef typename bucket_type::iterator bucket_iterator;
56 typedef typename bucket_type::const_iterator bucket_const_iterator;
60 item_counter m_ItemCounter; ///< Item counter
61 hash m_HashFunctor; ///< Hash functor
62 bucket_type * m_Buckets; ///< bucket table
66 const size_t m_nHashBitmask;
71 /// Calculates hash value of \p key
72 size_t hash_value( key_type const & key ) const
74 return m_HashFunctor( key ) & m_nHashBitmask;
77 /// Returns the bucket (ordered list) for \p key
78 bucket_type& bucket( key_type const& key )
80 return m_Buckets[ hash_value( key ) ];
87 \p IsConst - constness boolean flag
89 The forward iterator for Michael's map is based on \p OrderedList forward iterator and has some features:
90 - it has no post-increment operator, only pre-increment
91 - it iterates items in unordered fashion
93 template <bool IsConst>
94 class iterator_type: private cds::intrusive::michael_set::details::iterator< bucket_type, IsConst >
97 typedef cds::intrusive::michael_set::details::iterator< bucket_type, IsConst > base_class;
98 friend class MichaelHashMap;
103 //typedef typename base_class::bucket_type bucket_type;
104 typedef typename base_class::bucket_ptr bucket_ptr;
105 typedef typename base_class::list_iterator list_iterator;
107 //typedef typename bucket_type::key_type key_type;
111 /// Value pointer type (const for const_iterator)
112 typedef typename cds::details::make_const_type<typename MichaelHashMap::mapped_type, IsConst>::pointer value_ptr;
113 /// Value reference type (const for const_iterator)
114 typedef typename cds::details::make_const_type<typename MichaelHashMap::mapped_type, IsConst>::reference value_ref;
116 /// Key-value pair pointer type (const for const_iterator)
117 typedef typename cds::details::make_const_type<typename MichaelHashMap::value_type, IsConst>::pointer pair_ptr;
118 /// Key-value pair reference type (const for const_iterator)
119 typedef typename cds::details::make_const_type<typename MichaelHashMap::value_type, IsConst>::reference pair_ref;
123 iterator_type( list_iterator const& it, bucket_ptr pFirst, bucket_ptr pLast )
124 : base_class( it, pFirst, pLast )
135 iterator_type( const iterator_type& src )
139 /// Dereference operator
140 pair_ptr operator ->() const
142 assert( base_class::m_pCurBucket != nullptr );
143 return base_class::m_itList.operator ->();
146 /// Dereference operator
147 pair_ref operator *() const
149 assert( base_class::m_pCurBucket != nullptr );
150 return base_class::m_itList.operator *();
154 iterator_type& operator ++()
156 base_class::operator++();
160 /// Assignment operator
161 iterator_type& operator = (const iterator_type& src)
163 base_class::operator =(src);
167 /// Returns current bucket (debug function)
168 bucket_ptr bucket() const
170 return base_class::bucket();
173 /// Equality operator
175 bool operator ==(iterator_type<C> const& i ) const
177 return base_class::operator ==( i );
179 /// Equality operator
181 bool operator !=(iterator_type<C> const& i ) const
183 return !( *this == i );
190 typedef iterator_type< false > iterator;
192 /// Const forward iterator
193 typedef iterator_type< true > const_iterator;
195 /// Returns a forward iterator addressing the first element in a set
197 For empty set \code begin() == end() \endcode
201 return iterator( m_Buckets[0].begin(), m_Buckets, m_Buckets + bucket_count() );
204 /// Returns an iterator that addresses the location succeeding the last element in a set
206 Do not use the value returned by <tt>end</tt> function to access any item.
207 The returned value can be used only to control reaching the end of the set.
208 For empty set \code begin() == end() \endcode
212 return iterator( m_Buckets[bucket_count() - 1].end(), m_Buckets + bucket_count() - 1, m_Buckets + bucket_count() );
215 /// Returns a forward const iterator addressing the first element in a set
217 const_iterator begin() const
219 return get_const_begin();
221 const_iterator cbegin() const
223 return get_const_begin();
227 /// Returns an const iterator that addresses the location succeeding the last element in a set
229 const_iterator end() const
231 return get_const_end();
233 const_iterator cend() const
235 return get_const_end();
241 const_iterator get_const_begin() const
243 return const_iterator( const_cast<bucket_type const&>(m_Buckets[0]).begin(), m_Buckets, m_Buckets + bucket_count() );
245 const_iterator get_const_end() const
247 return const_iterator( const_cast<bucket_type const&>(m_Buckets[bucket_count() - 1]).end(), m_Buckets + bucket_count() - 1, m_Buckets + bucket_count() );
252 /// Initialize the map
253 /** @copydetails cds_nonintrusive_MichaelHashMap_hp_ctor
256 size_t nMaxItemCount, ///< estimation of max item count in the hash set
257 size_t nLoadFactor ///< load factor: estimation of max number of items in the bucket
258 ) : m_nHashBitmask( michael_map::details::init_hash_bitmask( nMaxItemCount, nLoadFactor ))
260 // GC and OrderedList::gc must be the same
261 static_assert( std::is_same<gc, typename bucket_type::gc>::value, "GC and OrderedList::gc must be the same");
263 // atomicity::empty_item_counter is not allowed as a item counter
264 static_assert( !std::is_same<item_counter, atomicity::empty_item_counter>::value,
265 "cds::atomicity::empty_item_counter is not allowed as a item counter");
267 m_Buckets = bucket_table_allocator().NewArray( bucket_count() );
270 /// Clears hash set and destroys it
274 bucket_table_allocator().Delete( m_Buckets, bucket_count() );
277 /// Inserts new node with key and default value
279 The function creates a node with \p key and default value, and then inserts the node created into the map.
282 - The \ref key_type should be constructible from value of type \p K.
283 In trivial case, \p K is equal to \ref key_type.
284 - The \ref mapped_type should be default-constructible.
286 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
288 template <typename K>
289 iterator insert( const K& key )
291 bucket_type& refBucket = bucket( key );
292 bucket_iterator it = refBucket.insert( key );
294 if ( it != refBucket.end() ) {
296 return iterator( it, &refBucket, m_Buckets + bucket_count() );
304 The function creates a node with copy of \p val value
305 and then inserts the node created into the map.
308 - The \ref key_type should be constructible from \p key of type \p K.
309 - The \ref mapped_type should be constructible from \p val of type \p V.
311 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
313 template <typename K, typename V>
314 iterator insert( K const& key, V const& val )
316 bucket_type& refBucket = bucket( key );
317 bucket_iterator it = refBucket.insert( key, val );
319 if ( it != refBucket.end() ) {
321 return iterator( it, &refBucket, m_Buckets + bucket_count() );
327 /// Inserts new node and initialize it by a functor
329 This function inserts new node with key \p key and if inserting is successful then it calls
330 \p func functor with signature
333 void operator()( value_type& item );
337 The argument \p item of user-defined functor \p func is the reference
338 to the map's item inserted. <tt>item.second</tt> is a reference to item's value that may be changed.
340 The user-defined functor it is called only if the inserting is successful.
341 The \p key_type should be constructible from value of type \p K.
343 The function allows to split creating of new item into two part:
344 - create item from \p key;
345 - insert new item into the map;
346 - if inserting is successful, initialize the value of item by calling \p f functor
348 This can be useful if complete initialization of object of \p mapped_type is heavyweight and
349 it is preferable that the initialization should be completed only if inserting is successful.
351 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
353 @warning For \ref cds_nonintrusive_MichaelKVList_nogc "MichaelKVList" as the bucket see \ref cds_intrusive_item_creating "insert item troubleshooting".
354 \ref cds_nonintrusive_LazyKVList_nogc "LazyKVList" provides exclusive access to inserted item and does not require any node-level
357 template <typename K, typename Func>
358 iterator insert_with( const K& key, Func func )
360 bucket_type& refBucket = bucket( key );
361 bucket_iterator it = refBucket.insert_with( key, func );
363 if ( it != refBucket.end() ) {
365 return iterator( it, &refBucket, m_Buckets + bucket_count() );
371 /// For key \p key inserts data of type \p mapped_type created from \p args
373 \p key_type should be constructible from type \p K
375 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
377 template <typename K, typename... Args>
378 iterator emplace( K&& key, Args&&... args )
380 bucket_type& refBucket = bucket( key );
381 bucket_iterator it = refBucket.emplace( std::forward<K>(key), std::forward<Args>(args)... );
383 if ( it != refBucket.end() ) {
385 return iterator( it, &refBucket, m_Buckets + bucket_count() );
391 /// Ensures that the key \p key exists in the map
393 The operation inserts new item if the key \p key is not found in the map.
394 Otherwise, the function returns an iterator that points to item found.
396 Returns <tt> std::pair<iterator, bool> </tt> where \p first is an iterator pointing to
397 item found or inserted, \p second is true if new item has been added or \p false if the item
398 already is in the list.
400 @warning For \ref cds_nonintrusive_MichaelKVList_nogc "MichaelKVList" as the bucket see \ref cds_intrusive_item_creating "insert item troubleshooting".
401 \ref cds_nonintrusive_LazyKVList_nogc "LazyKVList" provides exclusive access to inserted item and does not require any node-level
404 template <typename K>
405 std::pair<iterator, bool> ensure( const K& key )
407 bucket_type& refBucket = bucket( key );
408 std::pair<bucket_iterator, bool> ret = refBucket.ensure( key );
413 return std::make_pair( iterator( ret.first, &refBucket, m_Buckets + bucket_count() ), ret.second );
416 /// Find the key \p key
417 /** \anchor cds_nonintrusive_MichaelMap_nogc_find
419 The function searches the item with key equal to \p key
420 and returns an iterator pointed to item found if the key is found,
421 and \ref end() otherwise
423 template <typename K>
424 iterator find( const K& key )
426 bucket_type& refBucket = bucket( key );
427 bucket_iterator it = refBucket.find( key );
429 if ( it != refBucket.end() )
430 return iterator( it, &refBucket, m_Buckets + bucket_count() );
435 /// Finds the key \p val using \p pred predicate for searching
437 The function is an analog of \ref cds_nonintrusive_MichaelMap_nogc_find "find(K const&)"
438 but \p pred is used for key comparing.
439 \p Less functor has the interface like \p std::less.
440 \p Less must imply the same element order as the comparator used for building the map.
442 template <typename K, typename Less>
443 iterator find_with( const K& key, Less pred )
445 bucket_type& refBucket = bucket( key );
446 bucket_iterator it = refBucket.find_with( key, pred );
448 if ( it != refBucket.end() )
449 return iterator( it, &refBucket, m_Buckets + bucket_count() );
454 /// Clears the map (not atomic)
457 for ( size_t i = 0; i < bucket_count(); ++i )
458 m_Buckets[i].clear();
459 m_ItemCounter.reset();
462 /// Checks whether the map is empty
464 Emptiness is checked by item counting: if item count is zero then the map is empty.
465 Thus, the correct item counting feature is an important part of Michael's map implementation.
472 /// Returns item count in the map
475 return m_ItemCounter;
478 /// Returns the size of hash table
480 Since \p %MichaelHashMap cannot dynamically extend the hash table size,
481 the value returned is an constant depending on object initialization parameters;
482 see \p MichaelHashMap::MichaelHashMap for explanation.
484 size_t bucket_count() const
486 return m_nHashBitmask + 1;
489 }} // namespace cds::container
491 #endif // ifndef CDSLIB_CONTAINER_MICHAEL_MAP_NOGC_H