2 This file is a part of libcds - Concurrent Data Structures library
4 (C) Copyright Maxim Khizhinsky (libcds.dev@gmail.com) 2006-2016
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 bucket_type; ///< type of ordered list used as a bucket implementation
62 typedef Traits traits; ///< Map traits
64 typedef typename bucket_type::key_type key_type; ///< key type
65 typedef typename bucket_type::mapped_type mapped_type; ///< type of value to be stored in the map
66 typedef typename bucket_type::value_type value_type; ///< Pair used as the some functor's argument
68 typedef typename bucket_type::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
74 /// Bucket table allocator
75 typedef cds::details::Allocator< bucket_type, typename traits::allocator > bucket_table_allocator;
79 typedef typename bucket_type::iterator bucket_iterator;
80 typedef typename bucket_type::const_iterator bucket_const_iterator;
84 item_counter m_ItemCounter; ///< Item counter
85 hash m_HashFunctor; ///< Hash functor
86 bucket_type * m_Buckets; ///< bucket table
90 const size_t m_nHashBitmask;
95 /// Calculates hash value of \p key
96 size_t hash_value( key_type const & key ) const
98 return m_HashFunctor( key ) & m_nHashBitmask;
101 /// Returns the bucket (ordered list) for \p key
102 bucket_type& bucket( key_type const& key )
104 return m_Buckets[ hash_value( key ) ];
111 \p IsConst - constness boolean flag
113 The forward iterator for Michael's map is based on \p OrderedList forward iterator and has some features:
114 - it has no post-increment operator, only pre-increment
115 - it iterates items in unordered fashion
117 template <bool IsConst>
118 class iterator_type: private cds::intrusive::michael_set::details::iterator< bucket_type, IsConst >
121 typedef cds::intrusive::michael_set::details::iterator< bucket_type, IsConst > base_class;
122 friend class MichaelHashMap;
127 //typedef typename base_class::bucket_type bucket_type;
128 typedef typename base_class::bucket_ptr bucket_ptr;
129 typedef typename base_class::list_iterator list_iterator;
131 //typedef typename bucket_type::key_type key_type;
135 /// Value pointer type (const for const_iterator)
136 typedef typename cds::details::make_const_type<typename MichaelHashMap::mapped_type, IsConst>::pointer value_ptr;
137 /// Value reference type (const for const_iterator)
138 typedef typename cds::details::make_const_type<typename MichaelHashMap::mapped_type, IsConst>::reference value_ref;
140 /// Key-value pair pointer type (const for const_iterator)
141 typedef typename cds::details::make_const_type<typename MichaelHashMap::value_type, IsConst>::pointer pair_ptr;
142 /// Key-value pair reference type (const for const_iterator)
143 typedef typename cds::details::make_const_type<typename MichaelHashMap::value_type, IsConst>::reference pair_ref;
147 iterator_type( list_iterator const& it, bucket_ptr pFirst, bucket_ptr pLast )
148 : base_class( it, pFirst, pLast )
159 iterator_type( const iterator_type& src )
163 /// Dereference operator
164 pair_ptr operator ->() const
166 assert( base_class::m_pCurBucket != nullptr );
167 return base_class::m_itList.operator ->();
170 /// Dereference operator
171 pair_ref operator *() const
173 assert( base_class::m_pCurBucket != nullptr );
174 return base_class::m_itList.operator *();
178 iterator_type& operator ++()
180 base_class::operator++();
184 /// Assignment operator
185 iterator_type& operator = (const iterator_type& src)
187 base_class::operator =(src);
191 /// Returns current bucket (debug function)
192 bucket_ptr bucket() const
194 return base_class::bucket();
197 /// Equality operator
199 bool operator ==(iterator_type<C> const& i ) const
201 return base_class::operator ==( i );
203 /// Equality operator
205 bool operator !=(iterator_type<C> const& i ) const
207 return !( *this == i );
214 typedef iterator_type< false > iterator;
216 /// Const forward iterator
217 typedef iterator_type< true > const_iterator;
219 /// Returns a forward iterator addressing the first element in a set
221 For empty set \code begin() == end() \endcode
225 return iterator( m_Buckets[0].begin(), m_Buckets, m_Buckets + bucket_count() );
228 /// Returns an iterator that addresses the location succeeding the last element in a set
230 Do not use the value returned by <tt>end</tt> function to access any item.
231 The returned value can be used only to control reaching the end of the set.
232 For empty set \code begin() == end() \endcode
236 return iterator( m_Buckets[bucket_count() - 1].end(), m_Buckets + bucket_count() - 1, m_Buckets + bucket_count() );
239 /// Returns a forward const iterator addressing the first element in a set
241 const_iterator begin() const
243 return get_const_begin();
245 const_iterator cbegin() const
247 return get_const_begin();
251 /// Returns an const iterator that addresses the location succeeding the last element in a set
253 const_iterator end() const
255 return get_const_end();
257 const_iterator cend() const
259 return get_const_end();
265 const_iterator get_const_begin() const
267 return const_iterator( const_cast<bucket_type const&>(m_Buckets[0]).begin(), m_Buckets, m_Buckets + bucket_count() );
269 const_iterator get_const_end() const
271 return const_iterator( const_cast<bucket_type const&>(m_Buckets[bucket_count() - 1]).end(), m_Buckets + bucket_count() - 1, m_Buckets + bucket_count() );
276 /// Initialize the map
278 The Michael's hash map is non-expandable container. You should point the average count of items \p nMaxItemCount
279 when you create an object.
280 \p nLoadFactor parameter defines average count of items per bucket and it should be small number between 1 and 10.
281 Remember, since the bucket implementation is an ordered list, searching in the bucket is linear [<tt>O(nLoadFactor)</tt>].
282 Note, that many popular STL hash map implementation uses load factor 1.
284 The ctor defines hash table size as rounding <tt>nMacItemCount / nLoadFactor</tt> up to nearest power of two.
287 size_t nMaxItemCount, ///< estimation of max item count in the hash set
288 size_t nLoadFactor ///< load factor: estimation of max number of items in the bucket
289 ) : m_nHashBitmask( michael_map::details::init_hash_bitmask( nMaxItemCount, nLoadFactor ))
291 // GC and OrderedList::gc must be the same
292 static_assert( std::is_same<gc, typename bucket_type::gc>::value, "GC and OrderedList::gc must be the same");
294 // atomicity::empty_item_counter is not allowed as a item counter
295 static_assert( !std::is_same<item_counter, atomicity::empty_item_counter>::value,
296 "cds::atomicity::empty_item_counter is not allowed as a item counter");
298 m_Buckets = bucket_table_allocator().NewArray( bucket_count() );
301 /// Clears hash set and destroys it
305 bucket_table_allocator().Delete( m_Buckets, bucket_count() );
308 /// Inserts new node with key and default value
310 The function creates a node with \p key and default value, and then inserts the node created into the map.
313 - The \ref key_type should be constructible from value of type \p K.
314 In trivial case, \p K is equal to \ref key_type.
315 - The \ref mapped_type should be default-constructible.
317 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
319 template <typename K>
320 iterator insert( const K& key )
322 bucket_type& refBucket = bucket( key );
323 bucket_iterator it = refBucket.insert( key );
325 if ( it != refBucket.end() ) {
327 return iterator( it, &refBucket, m_Buckets + bucket_count() );
335 The function creates a node with copy of \p val value
336 and then inserts the node created into the map.
339 - The \ref key_type should be constructible from \p key of type \p K.
340 - The \ref mapped_type should be constructible from \p val of type \p V.
342 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
344 template <typename K, typename V>
345 iterator insert( K const& key, V const& val )
347 bucket_type& refBucket = bucket( key );
348 bucket_iterator it = refBucket.insert( key, val );
350 if ( it != refBucket.end() ) {
352 return iterator( it, &refBucket, m_Buckets + bucket_count() );
358 /// Inserts new node and initialize it by a functor
360 This function inserts new node with key \p key and if inserting is successful then it calls
361 \p func functor with signature
364 void operator()( value_type& item );
368 The argument \p item of user-defined functor \p func is the reference
369 to the map's item inserted. <tt>item.second</tt> is a reference to item's value that may be changed.
371 The user-defined functor it is called only if the inserting is successful.
372 The \p key_type should be constructible from value of type \p K.
374 The function allows to split creating of new item into two part:
375 - create item from \p key;
376 - insert new item into the map;
377 - if inserting is successful, initialize the value of item by calling \p f functor
379 This can be useful if complete initialization of object of \p mapped_type is heavyweight and
380 it is preferable that the initialization should be completed only if inserting is successful.
382 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
384 @warning For \ref cds_nonintrusive_MichaelKVList_nogc "MichaelKVList" as the bucket see \ref cds_intrusive_item_creating "insert item troubleshooting".
385 \ref cds_nonintrusive_LazyKVList_nogc "LazyKVList" provides exclusive access to inserted item and does not require any node-level
388 template <typename K, typename Func>
389 iterator insert_with( const K& key, Func func )
391 bucket_type& refBucket = bucket( key );
392 bucket_iterator it = refBucket.insert_with( key, func );
394 if ( it != refBucket.end() ) {
396 return iterator( it, &refBucket, m_Buckets + bucket_count() );
402 /// For key \p key inserts data of type \p mapped_type created from \p args
404 \p key_type should be constructible from type \p K
406 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
408 template <typename K, typename... Args>
409 iterator emplace( K&& key, Args&&... args )
411 bucket_type& refBucket = bucket( key );
412 bucket_iterator it = refBucket.emplace( std::forward<K>(key), std::forward<Args>(args)... );
414 if ( it != refBucket.end() ) {
416 return iterator( it, &refBucket, m_Buckets + bucket_count() );
424 If \p key is not in the map and \p bAllowInsert is \p true, the function inserts a new item.
425 Otherwise, the function returns an iterator pointing to the item found.
427 Returns <tt> std::pair<iterator, bool> </tt> where \p first is an iterator pointing to
428 item found or inserted (if inserting is not allowed and \p key is not found, the iterator will be \p end()),
430 \p second is true if new item has been added or \p false if the item
431 already is in the map.
433 @warning For \ref cds_nonintrusive_MichaelKVList_nogc "MichaelKVList" as the bucket see \ref cds_intrusive_item_creating "insert item troubleshooting".
434 \ref cds_nonintrusive_LazyKVList_nogc "LazyKVList" provides exclusive access to inserted item and does not require any node-level
437 template <typename K>
438 std::pair<iterator, bool> update( const K& key, bool bAllowInsert = true )
440 bucket_type& refBucket = bucket( key );
441 std::pair<bucket_iterator, bool> ret = refBucket.update( key, bAllowInsert );
445 else if ( ret.first == refBucket.end() )
446 return std::make_pair( end(), false );
447 return std::make_pair( iterator( ret.first, &refBucket, m_Buckets + bucket_count() ), ret.second );
450 template <typename K>
451 CDS_DEPRECATED("ensure() is deprecated, use update()")
452 std::pair<iterator, bool> ensure( K const& key )
454 return update( key, true );
458 /// Checks whether the map contains \p key
460 The function searches the item with key equal to \p key
461 and returns an iterator pointed to item found and \ref end() otherwise
463 template <typename K>
464 iterator contains( K const& key )
466 bucket_type& refBucket = bucket( key );
467 bucket_iterator it = refBucket.contains( key );
469 if ( it != refBucket.end() )
470 return iterator( it, &refBucket, m_Buckets + bucket_count() );
475 template <typename K>
476 CDS_DEPRECATED("deprecated, use contains()")
477 iterator find( K const& key )
479 return contains( key );
483 /// Checks whether the map contains \p key using \p pred predicate for searching
485 The function is an analog of <tt>contains( key )</tt> but \p pred is used for key comparing.
486 \p Less functor has the interface like \p std::less.
487 \p pred must imply the same element order as the comparator used for building the map.
489 template <typename K, typename Less>
490 iterator contains( K const& key, Less pred )
492 bucket_type& refBucket = bucket( key );
493 bucket_iterator it = refBucket.contains( key, pred );
495 if ( it != refBucket.end() )
496 return iterator( it, &refBucket, m_Buckets + bucket_count() );
501 template <typename K, typename Less>
502 CDS_DEPRECATED("deprecated, use contains()")
503 iterator find_with( K const& key, Less pred )
505 return contains( key, pred );
509 /// Clears the map (not atomic)
512 for ( size_t i = 0; i < bucket_count(); ++i )
513 m_Buckets[i].clear();
514 m_ItemCounter.reset();
517 /// Checks whether the map is empty
519 Emptiness is checked by item counting: if item count is zero then the map is empty.
520 Thus, the correct item counting feature is an important part of Michael's map implementation.
527 /// Returns item count in the map
530 return m_ItemCounter;
533 /// Returns the size of hash table
535 Since \p %MichaelHashMap cannot dynamically extend the hash table size,
536 the value returned is an constant depending on object initialization parameters;
537 see \p MichaelHashMap::MichaelHashMap for explanation.
539 size_t bucket_count() const
541 return m_nHashBitmask + 1;
544 }} // namespace cds::container
546 #endif // ifndef CDSLIB_CONTAINER_MICHAEL_MAP_NOGC_H