This class template defines a fully thread‐safe container that provides a mapping from keys (of template parameter type KEY) to their associated mapped values (of template parameter type VALUE).

Synopsis

Declared in <bdlcc_stripedunorderedmap.h>

template<
    class KEY,
    class VALUE,
    class HASH = bsl::hash<KEY>,
    class EQUAL = bsl::equal_to<KEY>>
class StripedUnorderedMap;

Description

The buckets of this hash map are guarded by numStripes reader‐writer locks, a value specified on construction. Partitioning the buckets among several locks allows greater overall concurrency than a bsl::unordered_map object guarded by a single lock.

The interface is inspired by, but not identical to that of bsl::unordered_map. Notably absent are iterators, which are of limited practicality in the typical use case because they are readily invalidated when the map population is open to modification by multiple threads.

Type Aliases

Name

Description

EraseIfValuePredicate

An alias to a function meeting the following contract: ` /// Return true if the specified value is to be removed from /// the container, and false otherwise. Note that this /// functor can not change the values associated with value. bool eraseIfValuePredicate(const VALUE& value); `

KVType

Value type of a bulk insert entry.

ReadOnlyVisitorFunction

An alias to a function meeting the following contract: ` /// Visit the specified value attribute associated with the /// specified key. Return true if this function may be /// called on additional elements, and false otherwise (i.e., /// if no other elements should be visited). Note that this /// functor can not change the value associated with key /// and value. bool visitorFunction(const VALUE& value, const KEY& key); `

VisitorFunction

An alias to a function meeting the following contract: ` /// Visit the specified value attribute associated with the /// specified key. Return true if this function may be /// called on additional elements, and false otherwise (i.e., /// if no other elements should be visited). Note that this /// functor can change the value associated with key. bool visitorFunction(VALUE *value, const KEY& key); `

Enums

Name

Description

Unnamed enum

Default sizing constants for this map.

Member Functions

Name

Description

StripedUnorderedMap [constructor]

Create an empty StripedUnorderedMap object, a fully thread‐safe hash map where access is partitioned into "stripes" (a group of buckets protected a reader‐writer mutex). Optionally specify numInitialBuckets and numStripes which define the minimum number of buckets and the (fixed) number of stripes in this map. Optionally specify a basicAllocator used to supply memory. If basicAllocator is 0, the currently installed default allocator is used. The hash map has rehash enabled. Note that the number of stripes will not change after construction, but the number of buckets may (unless rehashing is disabled via disableRehash).

allocator

Return the allocator used by this hash map to supply memory. Note that if no allocator was supplied at construction the default allocator installed at that time is used.

bucketCount

Return the number of buckets in the array of buckets maintained by this hash map. Note that unless rehash is disabled, the value returned may be obsolete by the time it is received.

bucketIndex

Return the index of the bucket, in the array of buckets maintained by this hash map, where elements having the specified key are inserted. Note that unless rehash is disabled, the value returned may be obsolete at the time it is returned.

bucketSize

Return the number of elements contained in the bucket at the specified index in the array of buckets maintained by this hash map. The behavior is undefined unless 0 <= index < bucketCount(). Note that unless rehash is disabled the value returned may be obsolete by the time it is returned.

clear

Remove all elements from this hash map. If rehash is in progress, block until it completes.

disableRehash

Prevent future rehash until enableRehash is called.

empty

Return true if this hash map contains no elements, and false otherwise.

enableRehash

Allow rehash. If conditions warrant, rehash will be started by the next method call that observes the load factor is exceeded (see {Concurrent Rehash}). Note that calling maxLoadFactor(maxLoadFactor()) (i.e., setting the maximum load factor to its current value) will trigger a rehash if needed but otherwise does not change the hash map.

equalFunction

Return (a copy of) the key‐equality functor used by this hash map. The returned function will return true if two KEY objects have the same value, and false otherwise.

erase

Erase from this hash map the element having the specified key. Return 1 on success and 0 if key does not exist. Note that the returned value equals the number of elements removed.

eraseBulk

Erase from this hash map elements in this hash map having any of the values in the keys contained between the specified first (inclusive) and last (exclusive) random‐access iterators. The iterators provide read access to a sequence of KEY objects. All erasures are done by the calling thread and the order of erasure is not specified. Return the number of elements removed. The behavior is undefined unless first <= last. Note that the map may not have an element for every value in keys.

eraseIf

Remove from this hash map the element, if any, having the specified key, where specified predicate holds true. Return the number of elements erased.

getValue

Load, into the specified *value, the value attribute of the element in this hash map having the specified key. Return 1 on success and 0 if key does not exist in this hash map. Note that the return value equals the number of values returned.

hashFunction

Return (a copy of) the unary hash functor used by this hash map. The return function will generate a hash value (of type std::size_t) for a KEY object.

insert

insert overloads

insertBulk

Insert into this hash map elements having the key‐value pairs obtained between the specified first (inclusive) and last (exclusive) random‐access iterators. The iterators provide read access to a sequence of bsl::pair<KEY, VALUE> objects. If an element having one of the keys already exists in this hash map, set the value attribute to the corresponding value from data. All insertions are done by the calling thread and the order of insertion is not specified. Return the number of elements inserted. The behavior is undefined unless first <= last.

isRehashEnabled

Return true if rehash is enabled, or false otherwise.

loadFactor

Return the current quotient of the size of this hash map and the number of buckets. Note that the load factor is a measure of container "fullness"; that is, a high load factor typically implies many collisions (many elements landing in the same bucket) and that decreases performance. See {Rehash Control}.

maxLoadFactor

Return the maximum load factor allowed for this hash map. If an insert operation would cause the load factor to exceed the maxLoadFactor() and rehashing is enabled, then that insert increases the number of buckets and rehashes the elements of the container into that larger set of buckets. See {Rehash Control}.

numStripes

Return the number of stripes in the hash.

rehash

Recreate this hash map to one having at least the specified numBuckets. This operation is a no‐op if any of the following are true: 1) rehash is disabled; 2) numBuckets less or equals the current number of buckets. See {Rehash}.

setComputedValue

Invoke the specified visitor on the value associated with the specified key. The visitor will be passed the address of the value, and key. If key is not in the map, value will be default constructed. That is, visitor must be invocable with the VisitorFunction signature: ` bool visitor(VALUE *value, const Key& key); ` If no element in the map has key, insert (key, VALUE()) and invoke visitor with value pointing to the default constructed value. Return 1 if key was found and visitor returned true, 0 if key was not found, and ‐1 if key was found and visitor returned false. visitor, when invoked, has exclusive access (i.e., write access) to the element. The behavior is undefined if hash map manipulators and getValue* methods are invoked from within visitor, as it may lead to a deadlock. Note that the return value equals the number of elements found having key. Also note that a return value of 0 implies that an element was inserted.

setValue

setValue overloads

size

Return the current number of elements in this hash map.

update

Call the specified visitor with the element (if one exists) in this hash map having the specified key. That is: ` bool visitor(&value, key); ` Return the number of elements updated or ‐1 if visitor returned false. visitor has exclusive access (i.e., write access) the element for during its invocation. The behavior is undefined if hash map manipulators and getValue* methods are invoked from within visitor, as it may lead to a deadlock.

visit

visit overloads

visitReadOnly

visitReadOnly overloads

Created with MrDocs