3 #ifndef CDSLIB_CONTAINER_SPLIT_LIST_MAP_NOGC_H
4 #define CDSLIB_CONTAINER_SPLIT_LIST_MAP_NOGC_H
6 #include <cds/container/split_list_set_nogc.h>
7 #include <cds/details/binary_functor_wrapper.h>
9 namespace cds { namespace container {
11 /// Split-ordered list map (template specialization for gc::nogc)
12 /** @ingroup cds_nonintrusive_map
13 \anchor cds_nonintrusive_SplitListMap_nogc
15 This specialization is so-called append-only.
16 The map does not support the removal of list item.
18 See \ref cds_nonintrusive_SplitListMap_hp "SplitListMap" for description of template parameters.
20 @warning Many member functions return an iterator pointing to an item.
21 The iterator can be used to set up field of the item,
22 but you should provide an exclusive access to it,
23 see \ref cds_intrusive_item_creating "insert item troubleshooting".
28 #ifdef CDS_DOXYGEN_INVOKED
29 class Traits = split_list::traits
34 class SplitListMap<cds::gc::nogc, Key, Value, Traits>:
35 protected container::SplitListSet<
37 std::pair<Key const, Value>,
38 split_list::details::wrap_map_traits<Key, Value, Traits>
42 typedef container::SplitListSet<
44 std::pair<Key const, Value>,
45 split_list::details::wrap_map_traits<Key, Value, Traits>
49 typedef cds::gc::nogc gc; ///< Garbage collector
50 typedef Key key_type; ///< key type
51 typedef Value mapped_type; ///< type of value stored in the map
53 typedef std::pair<key_type const, mapped_type> value_type ; ///< Pair type
54 typedef typename base_class::ordered_list ordered_list; ///< Underlying ordered list class
55 typedef typename base_class::key_comparator key_comparator; ///< key comparison functor
57 typedef typename base_class::hash hash; ///< Hash functor for \ref key_type
58 typedef typename base_class::item_counter item_counter; ///< Item counter type
59 typedef typename base_class::stat stat; ///< Internal statistics
63 typedef typename base_class::traits::key_accessor key_accessor;
67 /// Forward iterator (see \p SplitListSet::iterator)
69 Remember, the iterator <tt>operator -> </tt> and <tt>operator *</tt> returns \ref value_type pointer and reference.
70 To access item key and value use <tt>it->first</tt> and <tt>it->second</tt> respectively.
72 typedef typename base_class::iterator iterator;
74 /// Const forward iterator (see SplitListSet::const_iterator)
75 typedef typename base_class::const_iterator const_iterator;
77 /// Returns a forward iterator addressing the first element in a map
79 For empty set \code begin() == end() \endcode
83 return base_class::begin();
86 /// Returns an iterator that addresses the location succeeding the last element in a map
88 Do not use the value returned by <tt>end</tt> function to access any item.
89 The returned value can be used only to control reaching the end of the set.
90 For empty set \code begin() == end() \endcode
94 return base_class::end();
97 /// Returns a forward const iterator addressing the first element in a map
99 const_iterator begin() const
101 return base_class::begin();
103 const_iterator cbegin() const
105 return base_class::cbegin();
109 /// Returns an const iterator that addresses the location succeeding the last element in a map
111 const_iterator end() const
113 return base_class::end();
115 const_iterator cend() const
117 return base_class::cend();
122 /// Initialize split-ordered map of default capacity
124 The default capacity is defined in bucket table constructor.
125 See \p intrusive::split_list::expandable_bucket_table, \p intrusive::split_list::static_ducket_table
126 which selects by \p intrusive::split_list::traits::dynamic_bucket_table.
132 /// Initialize split-ordered map
134 size_t nItemCount ///< estimated average item count
135 , size_t nLoadFactor = 1 ///< load factor - average item count per bucket. Small integer up to 10, default is 1.
137 : base_class( nItemCount, nLoadFactor )
141 /// Inserts new node with key and default value
143 The function creates a node with \p key and default value, and then inserts the node created into the map.
146 - The \p key_type should be constructible from value of type \p K.
147 In trivial case, \p K is equal to \ref key_type.
148 - The \p mapped_type should be default-constructible.
150 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
152 template <typename K>
153 iterator insert( K const& key )
155 //TODO: pass arguments by reference (make_pair makes copy)
156 return base_class::insert( std::make_pair( key, mapped_type() ) );
161 The function creates a node with copy of \p val value
162 and then inserts the node created into the map.
165 - The \p key_type should be constructible from \p key of type \p K.
166 - The \p mapped_type should be constructible from \p val of type \p V.
168 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
170 template <typename K, typename V>
171 iterator insert( K const& key, V const& val )
173 //TODO: pass arguments by reference (make_pair makes copy)
174 return base_class::insert( std::make_pair( key, val ) );
177 /// Inserts new node and initialize it by a functor
179 This function inserts new node with key \p key and if inserting is successful then it calls
180 \p func functor with signature
183 void operator()( value_type& item );
187 The argument \p item of user-defined functor \p func is the reference
188 to the map's item inserted. \p item.second is a reference to item's value that may be changed.
189 User-defined functor \p func should guarantee that during changing item's value no any other changes
190 could be made on this map's item by concurrent threads.
191 The user-defined functor is called only if the inserting is successful.
193 The \p key_type should be constructible from value of type \p K.
195 The function allows to split creating of new item into two part:
196 - create item from \p key;
197 - insert new item into the map;
198 - if inserting is successful, initialize the value of item by calling \p f functor
200 This can be useful if complete initialization of object of \p mapped_type is heavyweight and
201 it is preferable that the initialization should be completed only if inserting is successful.
203 Returns an iterator pointed to inserted value, or \p end() if inserting is failed
205 template <typename K, typename Func>
206 iterator insert_with( const K& key, Func func )
208 iterator it = insert( key );
214 /// For key \p key inserts data of type \p mapped_type created in-place from \p args
216 \p key_type should be constructible from type \p K
218 Returns \p true if inserting successful, \p false otherwise.
220 template <typename K, typename... Args>
221 iterator emplace( K&& key, Args&&... args )
223 return base_class::emplace( std::forward<K>(key), std::move(mapped_type(std::forward<Args>(args)...)));
228 If \p key is not in the map and \p bAllowInsert is \p true, the function inserts a new item.
229 Otherwise, the function returns an iterator pointing to the item found.
231 Returns <tt> std::pair<iterator, bool> </tt> where \p first is an iterator pointing to
232 item found or inserted (if inserting is not allowed and \p key is not found, the iterator will be \p end()),
233 \p second is true if new item has been added or \p false if the item
234 already is in the map.
236 template <typename K>
237 std::pair<iterator, bool> update( K const& key, bool bAllowInsert = true )
239 //TODO: pass arguments by reference (make_pair makes copy)
240 return base_class::update( std::make_pair( key, mapped_type() ), bAllowInsert );
243 template <typename K>
244 CDS_DEPRECATED("ensure() is deprecated, use update()")
245 std::pair<iterator, bool> ensure( K const& key )
247 return update( key, true );
251 /// Checks whether the map contains \p key
253 The function searches the item with key equal to \p key
254 and returns an iterator pointed to item found and \ref end() otherwise
256 template <typename K>
257 iterator contains( K const& key )
259 return base_class::contains( key );
262 template <typename K>
263 CDS_DEPRECATED("deprecated, use contains()")
264 iterator find( K const& key )
266 return contains( key );
270 /// Checks whether the map contains \p key using \p pred predicate for searching
272 The function is an analog of <tt>contains( key )</tt> but \p pred is used for key comparing.
273 \p Less functor has the interface like \p std::less.
274 \p pred must imply the same element order as the comparator used for building the map.
276 template <typename K, typename Less>
277 iterator contains( K const& key, Less pred )
280 return base_class::contains( key, cds::details::predicate_wrapper<value_type, Less, key_accessor>() );
283 template <typename K, typename Less>
284 CDS_DEPRECATED("deprecated, use contains()")
285 iterator find_with( K const& key, Less pred )
287 return contains( key, pred );
291 /// Checks if the map is empty
293 Emptiness is checked by item counting: if item count is zero then the map is empty.
294 Thus, the correct item counting feature is an important part of Michael's map implementation.
298 return base_class::empty();
301 /// Returns item count in the map
304 return base_class::size();
307 /// Returns internal statistics
308 stat const& statistics() const
310 return base_class::statistics();
313 }} // namespace cds::container
316 #endif // #ifndef CDSLIB_CONTAINER_SPLIT_LIST_MAP_NOGC_H