2 This file is a part of libcds - Concurrent Data Structures library
4 (C) Copyright Maxim Khizhinsky (libcds.dev@gmail.com) 2006-2017
6 Source code repo: http://github.com/khizmax/libcds/
7 Download: http://sourceforge.net/projects/libcds/files/
9 Redistribution and use in source and binary forms, with or without
10 modification, are permitted provided that the following conditions are met:
12 * Redistributions of source code must retain the above copyright notice, this
13 list of conditions and the following disclaimer.
15 * Redistributions in binary form must reproduce the above copyright notice,
16 this list of conditions and the following disclaimer in the documentation
17 and/or other materials provided with the distribution.
19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 #ifndef CDSLIB_CONTAINER_MICHAEL_MAP_NOGC_H
32 #define CDSLIB_CONTAINER_MICHAEL_MAP_NOGC_H
34 #include <cds/container/details/michael_map_base.h>
35 #include <cds/gc/nogc.h>
36 #include <cds/details/allocator.h>
38 namespace cds { namespace container {
40 /// Michael's hash map (template specialization for \p cds::gc::nogc)
41 /** @ingroup cds_nonintrusive_map
42 \anchor cds_nonintrusive_MichaelHashMap_nogc
44 This specialization is so-called append-only when no item
45 reclamation may be performed. The class does not support deleting of map item.
47 See @ref cds_nonintrusive_MichaelHashMap_hp "MichaelHashMap" for description of template parameters.
51 #ifdef CDS_DOXYGEN_INVOKED
52 class Traits = michael_map::traits
57 class MichaelHashMap<cds::gc::nogc, OrderedList, Traits>
60 typedef cds::gc::nogc gc; ///< No garbage collector
61 typedef OrderedList ordered_list; ///< type of ordered list used as a bucket implementation
62 typedef Traits traits; ///< Map traits
64 typedef typename ordered_list::key_type key_type; ///< key type
65 typedef typename ordered_list::mapped_type mapped_type; ///< type of value to be stored in the map
66 typedef typename ordered_list::value_type value_type; ///< Pair used as the some functor's argument
68 typedef typename ordered_list::key_comparator key_comparator; ///< key comparing functor
70 /// Hash functor for \ref key_type and all its derivatives that you use
71 typedef typename cds::opt::v::hash_selector< typename traits::hash >::type hash;
72 typedef typename traits::item_counter item_counter; ///< Item counter type
73 typedef typename traits::allocator allocator; ///< Bucket table allocator
75 #ifdef CDS_DOXYGEN_INVOKED
76 typedef typename ordered_list::stat stat; ///< Internal statistics
79 // GC and OrderedList::gc must be the same
80 static_assert(std::is_same<gc, typename ordered_list::gc>::value, "GC and OrderedList::gc must be the same");
82 // atomicity::empty_item_counter is not allowed as a item counter
83 static_assert(!std::is_same<item_counter, atomicity::empty_item_counter>::value,
84 "cds::atomicity::empty_item_counter is not allowed as a item counter");
88 typedef typename ordered_list::template select_stat_wrapper< typename ordered_list::stat > bucket_stat;
90 typedef typename ordered_list::template rebind_traits<
91 cds::opt::item_counter< cds::atomicity::empty_item_counter >
92 , cds::opt::stat< typename bucket_stat::wrapped_stat >
93 >::type internal_bucket_type;
95 /// Bucket table allocator
96 typedef typename allocator::template rebind< internal_bucket_type >::other bucket_table_allocator;
98 typedef typename internal_bucket_type::iterator bucket_iterator;
99 typedef typename internal_bucket_type::const_iterator bucket_const_iterator;
104 typedef typename bucket_stat::stat stat;
109 const size_t m_nHashBitmask;
110 item_counter m_ItemCounter; ///< Item counter
111 hash m_HashFunctor; ///< Hash functor
112 internal_bucket_type* m_Buckets; ///< bucket table
113 stat m_Stat; ///< Internal statistics
118 template <bool IsConst>
119 class iterator_type: private cds::intrusive::michael_set::details::iterator< internal_bucket_type, IsConst >
121 typedef cds::intrusive::michael_set::details::iterator< internal_bucket_type, IsConst > base_class;
122 friend class MichaelHashMap;
125 typedef typename base_class::bucket_ptr bucket_ptr;
126 typedef typename base_class::list_iterator list_iterator;
129 /// Value pointer type (const for const_iterator)
130 typedef typename cds::details::make_const_type<typename MichaelHashMap::mapped_type, IsConst>::pointer value_ptr;
131 /// Value reference type (const for const_iterator)
132 typedef typename cds::details::make_const_type<typename MichaelHashMap::mapped_type, IsConst>::reference value_ref;
134 /// Key-value pair pointer type (const for const_iterator)
135 typedef typename cds::details::make_const_type<typename MichaelHashMap::value_type, IsConst>::pointer pair_ptr;
136 /// Key-value pair reference type (const for const_iterator)
137 typedef typename cds::details::make_const_type<typename MichaelHashMap::value_type, IsConst>::reference pair_ref;
140 iterator_type( list_iterator const& it, bucket_ptr pFirst, bucket_ptr pLast )
141 : base_class( it, pFirst, pLast )
151 iterator_type( const iterator_type& src )
155 /// Dereference operator
156 pair_ptr operator ->() const
158 assert( base_class::m_pCurBucket != nullptr );
159 return base_class::m_itList.operator ->();
162 /// Dereference operator
163 pair_ref operator *() const
165 assert( base_class::m_pCurBucket != nullptr );
166 return base_class::m_itList.operator *();
170 iterator_type& operator ++()
172 base_class::operator++();
176 /// Assignment operator
177 iterator_type& operator = (const iterator_type& src)
179 base_class::operator =(src);
183 /// Returns current bucket (debug function)
184 bucket_ptr bucket() const
186 return base_class::bucket();
189 /// Equality operator
191 bool operator ==(iterator_type<C> const& i ) const
193 return base_class::operator ==( i );
195 /// Equality operator
197 bool operator !=(iterator_type<C> const& i ) const
199 return !( *this == i );
205 ///@name Forward iterators
209 The forward iterator for Michael's map is based on \p OrderedList forward iterator and has some features:
210 - it has no post-increment operator
211 - it iterates items in unordered fashion
213 The iterator interface:
217 // Default constructor
221 iterator( iterator const& src );
223 // Dereference operator
224 value_type * operator ->() const;
226 // Dereference operator
227 value_type& operator *() const;
229 // Preincrement operator
230 iterator& operator ++();
232 // Assignment operator
233 iterator& operator = (iterator const& src);
235 // Equality operators
236 bool operator ==(iterator const& i ) const;
237 bool operator !=(iterator const& i ) const;
241 typedef iterator_type< false > iterator;
243 /// Const forward iterator
244 typedef iterator_type< true > const_iterator;
246 /// Returns a forward iterator addressing the first element in a set
248 For empty set \code begin() == end() \endcode
252 return iterator( m_Buckets[0].begin(), m_Buckets, m_Buckets + bucket_count());
255 /// Returns an iterator that addresses the location succeeding the last element in a set
257 Do not use the value returned by <tt>end</tt> function to access any item.
258 The returned value can be used only to control reaching the end of the set.
259 For empty set \code begin() == end() \endcode
263 return iterator( m_Buckets[bucket_count() - 1].end(), m_Buckets + bucket_count() - 1, m_Buckets + bucket_count());
266 /// Returns a forward const iterator addressing the first element in a set
267 const_iterator begin() const
269 return get_const_begin();
272 /// Returns a forward const iterator addressing the first element in a set
273 const_iterator cbegin() const
275 return get_const_begin();
278 /// Returns an const iterator that addresses the location succeeding the last element in a set
279 const_iterator end() const
281 return get_const_end();
284 /// Returns an const iterator that addresses the location succeeding the last element in a set
285 const_iterator cend() const
287 return get_const_end();
292 /// Initialize the map
294 The Michael's hash map is non-expandable container. You should point the average count of items \p nMaxItemCount
295 when you create an object.
296 \p nLoadFactor parameter defines average count of items per bucket and it should be small number between 1 and 10.
297 Remember, since the bucket implementation is an ordered list, searching in the bucket is linear [<tt>O(nLoadFactor)</tt>].
298 Note, that many popular STL hash map implementation uses load factor 1.
300 The ctor defines hash table size as rounding <tt>nMacItemCount / nLoadFactor</tt> up to nearest power of two.
303 size_t nMaxItemCount, ///< estimation of max item count in the hash set
304 size_t nLoadFactor ///< load factor: estimation of max number of items in the bucket
305 ) : m_nHashBitmask( michael_map::details::init_hash_bitmask( nMaxItemCount, nLoadFactor ))
306 , m_Buckets( bucket_table_allocator().allocate( bucket_count()))
308 for ( auto it = m_Buckets, itEnd = m_Buckets + bucket_count(); it != itEnd; ++it )
309 construct_bucket<bucket_stat>( it );
312 /// Clears hash set and destroys it
316 for ( auto it = m_Buckets, itEnd = m_Buckets + bucket_count(); it != itEnd; ++it )
317 it->~internal_bucket_type();
318 bucket_table_allocator().deallocate( m_Buckets, bucket_count());
321 /// Inserts new node with key and default value
323 The function creates a node with \p key and default value, and then inserts the node created into the map.
326 - The \ref key_type should be constructible from value of type \p K.
327 In trivial case, \p K is equal to \ref key_type.
328 - The \ref mapped_type should be default-constructible.
330 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
332 template <typename K>
333 iterator insert( const K& key )
335 internal_bucket_type& refBucket = bucket( key );
336 bucket_iterator it = refBucket.insert( key );
338 if ( it != refBucket.end()) {
340 return iterator( it, &refBucket, m_Buckets + bucket_count());
348 The function creates a node with copy of \p val value
349 and then inserts the node created into the map.
352 - The \ref key_type should be constructible from \p key of type \p K.
353 - The \ref mapped_type should be constructible from \p val of type \p V.
355 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
357 template <typename K, typename V>
358 iterator insert( K const& key, V const& val )
360 internal_bucket_type& refBucket = bucket( key );
361 bucket_iterator it = refBucket.insert( key, val );
363 if ( it != refBucket.end()) {
365 return iterator( it, &refBucket, m_Buckets + bucket_count());
371 /// Inserts new node and initialize it by a functor
373 This function inserts new node with key \p key and if inserting is successful then it calls
374 \p func functor with signature
377 void operator()( value_type& item );
381 The argument \p item of user-defined functor \p func is the reference
382 to the map's item inserted. <tt>item.second</tt> is a reference to item's value that may be changed.
384 The user-defined functor it is called only if the inserting is successful.
385 The \p key_type should be constructible from value of type \p K.
387 The function allows to split creating of new item into two part:
388 - create item from \p key;
389 - insert new item into the map;
390 - if inserting is successful, initialize the value of item by calling \p f functor
392 This can be useful if complete initialization of object of \p mapped_type is heavyweight and
393 it is preferable that the initialization should be completed only if inserting is successful.
395 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
397 @warning For \ref cds_nonintrusive_MichaelKVList_nogc "MichaelKVList" as the bucket see \ref cds_intrusive_item_creating "insert item troubleshooting".
398 \ref cds_nonintrusive_LazyKVList_nogc "LazyKVList" provides exclusive access to inserted item and does not require any node-level
401 template <typename K, typename Func>
402 iterator insert_with( const K& key, Func func )
404 internal_bucket_type& refBucket = bucket( key );
405 bucket_iterator it = refBucket.insert_with( key, func );
407 if ( it != refBucket.end()) {
409 return iterator( it, &refBucket, m_Buckets + bucket_count());
415 /// For key \p key inserts data of type \p mapped_type created from \p args
417 \p key_type should be constructible from type \p K
419 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
421 template <typename K, typename... Args>
422 iterator emplace( K&& key, Args&&... args )
424 internal_bucket_type& refBucket = bucket( key );
425 bucket_iterator it = refBucket.emplace( std::forward<K>(key), std::forward<Args>(args)... );
427 if ( it != refBucket.end()) {
429 return iterator( it, &refBucket, m_Buckets + bucket_count());
437 If \p key is not in the map and \p bAllowInsert is \p true, the function inserts a new item.
438 Otherwise, the function returns an iterator pointing to the item found.
440 Returns <tt> std::pair<iterator, bool> </tt> where \p first is an iterator pointing to
441 item found or inserted (if inserting is not allowed and \p key is not found, the iterator will be \p end()),
443 \p second is true if new item has been added or \p false if the item
444 already is in the map.
446 @warning For \ref cds_nonintrusive_MichaelKVList_nogc "MichaelKVList" as the bucket see \ref cds_intrusive_item_creating "insert item troubleshooting".
447 \ref cds_nonintrusive_LazyKVList_nogc "LazyKVList" provides exclusive access to inserted item and does not require any node-level
450 template <typename K>
451 std::pair<iterator, bool> update( const K& key, bool bAllowInsert = true )
453 internal_bucket_type& refBucket = bucket( key );
454 std::pair<bucket_iterator, bool> ret = refBucket.update( key, bAllowInsert );
458 else if ( ret.first == refBucket.end())
459 return std::make_pair( end(), false );
460 return std::make_pair( iterator( ret.first, &refBucket, m_Buckets + bucket_count()), ret.second );
463 template <typename K>
464 CDS_DEPRECATED("ensure() is deprecated, use update()")
465 std::pair<iterator, bool> ensure( K const& key )
467 return update( key, true );
471 /// Checks whether the map contains \p key
473 The function searches the item with key equal to \p key
474 and returns an iterator pointed to item found and \ref end() otherwise
476 template <typename K>
477 iterator contains( K const& key )
479 internal_bucket_type& refBucket = bucket( key );
480 bucket_iterator it = refBucket.contains( key );
482 if ( it != refBucket.end())
483 return iterator( it, &refBucket, m_Buckets + bucket_count());
488 template <typename K>
489 CDS_DEPRECATED("deprecated, use contains()")
490 iterator find( K const& key )
492 return contains( key );
496 /// Checks whether the map contains \p key using \p pred predicate for searching
498 The function is an analog of <tt>contains( key )</tt> but \p pred is used for key comparing.
499 \p Less functor has the interface like \p std::less.
500 \p pred must imply the same element order as the comparator used for building the map.
501 Hash functor specified in \p Traits should accept parameters of type \p K.
503 template <typename K, typename Less>
504 iterator contains( K const& key, Less pred )
506 internal_bucket_type& refBucket = bucket( key );
507 bucket_iterator it = refBucket.contains( key, pred );
509 if ( it != refBucket.end())
510 return iterator( it, &refBucket, m_Buckets + bucket_count());
515 template <typename K, typename Less>
516 CDS_DEPRECATED("deprecated, use contains()")
517 iterator find_with( K const& key, Less pred )
519 return contains( key, pred );
523 /// Clears the map (not atomic)
526 for ( size_t i = 0; i < bucket_count(); ++i )
527 m_Buckets[i].clear();
528 m_ItemCounter.reset();
531 /// Checks whether the map is empty
533 Emptiness is checked by item counting: if item count is zero then the map is empty.
534 Thus, the correct item counting feature is an important part of Michael's map implementation.
541 /// Returns item count in the map
544 return m_ItemCounter;
547 /// Returns const reference to internal statistics
548 stat const& statistics() const
553 /// Returns the size of hash table
555 Since \p %MichaelHashMap cannot dynamically extend the hash table size,
556 the value returned is an constant depending on object initialization parameters;
557 see \p MichaelHashMap::MichaelHashMap for explanation.
559 size_t bucket_count() const
561 return m_nHashBitmask + 1;
566 /// Calculates hash value of \p key
567 template <typename K>
568 size_t hash_value( K const & key ) const
570 return m_HashFunctor( key ) & m_nHashBitmask;
573 /// Returns the bucket (ordered list) for \p key
574 template <typename K>
575 internal_bucket_type& bucket( K const& key )
577 return m_Buckets[hash_value( key )];
583 const_iterator get_const_begin() const
585 return const_iterator( const_cast<internal_bucket_type const&>(m_Buckets[0]).begin(), m_Buckets, m_Buckets + bucket_count());
587 const_iterator get_const_end() const
589 return const_iterator( const_cast<internal_bucket_type const&>(m_Buckets[bucket_count() - 1]).end(), m_Buckets + bucket_count() - 1, m_Buckets + bucket_count());
592 template <typename Stat>
593 typename std::enable_if< Stat::empty >::type construct_bucket( internal_bucket_type* bucket )
595 new (bucket) internal_bucket_type;
598 template <typename Stat>
599 typename std::enable_if< !Stat::empty >::type construct_bucket( internal_bucket_type* bucket )
601 new (bucket) internal_bucket_type( m_Stat );
605 }} // namespace cds::container
607 #endif // ifndef CDSLIB_CONTAINER_MICHAEL_MAP_NOGC_H