userver: rcu::RcuMap< Key, Value, RcuMapTraits > Class Template Reference
Loading...
Searching...
No Matches
rcu::RcuMap< Key, Value, RcuMapTraits > Class Template Reference

#include <userver/rcu/rcu_map.hpp>

Detailed Description

template<typename Key, typename Value, typename RcuMapTraits>
class rcu::RcuMap< Key, Value, RcuMapTraits >

Map-like structure allowing RCU keyset updates.

Only keyset changes are thread-safe in scope of this class. Values are stored in shared_ptrs and are not copied during keyset change. The map itself is implemented as rcu::Variable, so every keyset change (e.g. insert or erase) triggers the whole map copying.

Note
No synchronization is provided for value access, it must be implemented by Value when necessary.

Example usage:

struct Data {
// Access to RcuMap content must be synchronized via std::atomic
// or other synchronization primitives
std::atomic<int> x{0};
std::atomic<bool> flag{false};
};
// If the key is not in the dictionary,
// then a default object will be created
map["123"]->x++;
map["other_data"]->flag = true;
ASSERT_EQ(map["123"]->x.load(), 1);
ASSERT_EQ(map["123"]->flag.load(), false);
ASSERT_EQ(map["other_data"]->x.load(), 0);
ASSERT_EQ(map["other_data"]->flag.load(), true);
See also
Synchronization Primitives

Definition at line 107 of file rcu_map.hpp.

Classes

struct  InsertReturnTypeImpl
 

Public Types

using Hash = typename RcuMapTraits::Hash
 
using KeyEqual = typename RcuMapTraits::KeyEqual
 
using MutexType = typename RcuMapTraits::MutexType
 
using ValuePtr = std::shared_ptr<Value>
 
using Iterator = RcuMapIterator<Key, Value, Value, RcuMapTraits>
 
using ConstValuePtr = std::shared_ptr<const Value>
 
using ConstIterator = RcuMapIterator<Key, Value, const Value, RcuMapTraits>
 
using RawMap = std::unordered_map<Key, ValuePtr, Hash, KeyEqual>
 
using Snapshot = std::unordered_map<Key, ConstValuePtr, Hash, KeyEqual>
 
using InsertReturnType = InsertReturnTypeImpl<ValuePtr>
 

Public Member Functions

 RcuMap (const RcuMap &)=delete
 
 RcuMap (RcuMap &&)=delete
 
RcuMapoperator= (const RcuMap &)=delete
 
RcuMapoperator= (RcuMap &&)=delete
 
size_t SizeApprox () const
 Returns an estimated size of the map at some point in time.
 
const ConstValuePtr operator[] (const Key &) const
 Returns a readonly value pointer by its key if exists.
 
const ValuePtr operator[] (const Key &)
 Returns a modifiable value pointer by key if exists or default-creates one.
 
InsertReturnType Insert (const Key &key, ValuePtr value)
 Inserts a new element into the container if there is no element with the key in the container. Returns a pair consisting of a pointer to the inserted element, or the already-existing element if no insertion happened, and a bool denoting whether the insertion took place.
 
template<typename... Args>
InsertReturnType Emplace (const Key &key, Args &&... args)
 Inserts a new element into the container constructed in-place with the given args if there is no element with the key in the container. Returns a pair consisting of a pointer to the inserted element, or the already-existing element if no insertion happened, and a bool denoting whether the insertion took place.
 
template<typename... Args>
InsertReturnType TryEmplace (const Key &key, Args &&... args)
 If a key equivalent to key already exists in the container, does nothing. Otherwise, behaves like Emplace except that the element is constructed as std::make_shared<Value>(std::piecewise_construct, std::forward_as_tuple(key), std::forward_as_tuple(std::forward<Args>(args)...)). Returns a pair consisting of a pointer to the inserted element, or the already-existing element if no insertion happened, and a bool denoting whether the insertion took place.
 
template<typename RawKey >
void InsertOrAssign (RawKey &&key, ValuePtr value)
 If a key equivalent to key already exists in the container, replaces the associated value. Otherwise, inserts a new pair into the map.
 
const ConstValuePtr Get (const Key &) const
 Returns a readonly value pointer by its key or an empty pointer.
 
const ValuePtr Get (const Key &)
 Returns a modifiable value pointer by key or an empty pointer.
 
bool Erase (const Key &)
 Removes a key from the map.
 
ValuePtr Pop (const Key &)
 Removes a key from the map returning its value.
 
void Clear ()
 Resets the map to an empty state.
 
void Assign (RawMap new_map)
 Replace current data by data from new_map.
 
rcu::WritablePtr< RawMap, RcuTraits > StartWrite ()
 Starts a transaction, used to perform a series of arbitrary changes to the map.
 
Snapshot GetSnapshot () const
 Returns a readonly copy of the map.
 
template<typename... Args>
RcuMap< K, V, RcuMapTraits >::InsertReturnType Emplace (const K &key, Args &&... args)
 
template<typename... Args>
RcuMap< K, V, RcuMapTraits >::InsertReturnType TryEmplace (const K &key, Args &&... args)
 
Iteration support

Keyset is fixed at the start of the iteration and is not affected by concurrent changes.

ConstIterator begin () const
 
ConstIterator end () const
 
Iterator begin ()
 
Iterator end ()
 

Member Typedef Documentation

◆ ConstIterator

template<typename Key , typename Value , typename RcuMapTraits >
using rcu::RcuMap< Key, Value, RcuMapTraits >::ConstIterator = RcuMapIterator<Key, Value, const Value, RcuMapTraits>

Definition at line 124 of file rcu_map.hpp.

◆ ConstValuePtr

template<typename Key , typename Value , typename RcuMapTraits >
using rcu::RcuMap< Key, Value, RcuMapTraits >::ConstValuePtr = std::shared_ptr<const Value>

Definition at line 123 of file rcu_map.hpp.

◆ Hash

template<typename Key , typename Value , typename RcuMapTraits >
using rcu::RcuMap< Key, Value, RcuMapTraits >::Hash = typename RcuMapTraits::Hash

Definition at line 118 of file rcu_map.hpp.

◆ InsertReturnType

template<typename Key , typename Value , typename RcuMapTraits >
using rcu::RcuMap< Key, Value, RcuMapTraits >::InsertReturnType = InsertReturnTypeImpl<ValuePtr>

Definition at line 127 of file rcu_map.hpp.

◆ Iterator

template<typename Key , typename Value , typename RcuMapTraits >
using rcu::RcuMap< Key, Value, RcuMapTraits >::Iterator = RcuMapIterator<Key, Value, Value, RcuMapTraits>

Definition at line 122 of file rcu_map.hpp.

◆ KeyEqual

template<typename Key , typename Value , typename RcuMapTraits >
using rcu::RcuMap< Key, Value, RcuMapTraits >::KeyEqual = typename RcuMapTraits::KeyEqual

Definition at line 119 of file rcu_map.hpp.

◆ MutexType

template<typename Key , typename Value , typename RcuMapTraits >
using rcu::RcuMap< Key, Value, RcuMapTraits >::MutexType = typename RcuMapTraits::MutexType

Definition at line 120 of file rcu_map.hpp.

◆ RawMap

template<typename Key , typename Value , typename RcuMapTraits >
using rcu::RcuMap< Key, Value, RcuMapTraits >::RawMap = std::unordered_map<Key, ValuePtr, Hash, KeyEqual>

Definition at line 125 of file rcu_map.hpp.

◆ Snapshot

template<typename Key , typename Value , typename RcuMapTraits >
using rcu::RcuMap< Key, Value, RcuMapTraits >::Snapshot = std::unordered_map<Key, ConstValuePtr, Hash, KeyEqual>

Definition at line 126 of file rcu_map.hpp.

◆ ValuePtr

template<typename Key , typename Value , typename RcuMapTraits >
using rcu::RcuMap< Key, Value, RcuMapTraits >::ValuePtr = std::shared_ptr<Value>

Definition at line 121 of file rcu_map.hpp.

Member Function Documentation

◆ Assign()

template<typename K , typename V , typename RcuMapTraits >
void rcu::RcuMap< K, V, RcuMapTraits >::Assign ( RawMap new_map)

Replace current data by data from new_map.

Definition at line 412 of file rcu_map.hpp.

◆ begin() [1/2]

template<typename K , typename V , typename RcuMapTraits >
RcuMap< K, V, RcuMapTraits >::Iterator rcu::RcuMap< K, V, RcuMapTraits >::begin ( )

Definition at line 256 of file rcu_map.hpp.

◆ begin() [2/2]

template<typename K , typename V , typename RcuMapTraits >
RcuMap< K, V, RcuMapTraits >::ConstIterator rcu::RcuMap< K, V, RcuMapTraits >::begin ( ) const

Definition at line 239 of file rcu_map.hpp.

◆ Clear()

template<typename K , typename V , typename RcuMapTraits >
void rcu::RcuMap< K, V, RcuMapTraits >::Clear ( )

Resets the map to an empty state.

Definition at line 407 of file rcu_map.hpp.

◆ Emplace() [1/2]

template<typename Key , typename Value , typename RcuMapTraits >
template<typename... Args>
RcuMap< K, V, RcuMapTraits >::InsertReturnType rcu::RcuMap< Key, Value, RcuMapTraits >::Emplace ( const K & key,
Args &&... args )

Definition at line 324 of file rcu_map.hpp.

◆ Emplace() [2/2]

template<typename Key , typename Value , typename RcuMapTraits >
template<typename... Args>
InsertReturnType rcu::RcuMap< Key, Value, RcuMapTraits >::Emplace ( const Key & key,
Args &&... args )

Inserts a new element into the container constructed in-place with the given args if there is no element with the key in the container. Returns a pair consisting of a pointer to the inserted element, or the already-existing element if no insertion happened, and a bool denoting whether the insertion took place.

Note
Copies the whole map if the key doesn't exist.

◆ end() [1/2]

template<typename K , typename V , typename RcuMapTraits >
RcuMap< K, V, RcuMapTraits >::Iterator rcu::RcuMap< K, V, RcuMapTraits >::end ( )

Definition at line 264 of file rcu_map.hpp.

◆ end() [2/2]

template<typename K , typename V , typename RcuMapTraits >
RcuMap< K, V, RcuMapTraits >::ConstIterator rcu::RcuMap< K, V, RcuMapTraits >::end ( ) const

Definition at line 248 of file rcu_map.hpp.

◆ Erase()

template<typename Key , typename Value , typename RcuMapTraits >
bool rcu::RcuMap< K, V, RcuMapTraits >::Erase ( const Key & )

Removes a key from the map.

Returns
whether the key was present
Note
Copies the whole map, might be slow for large maps.

Definition at line 384 of file rcu_map.hpp.

◆ GetSnapshot()

template<typename K , typename V , typename RcuMapTraits >
RcuMap< K, V, RcuMapTraits >::Snapshot rcu::RcuMap< K, V, RcuMapTraits >::GetSnapshot ( ) const

Returns a readonly copy of the map.

Note
Equivalent to {begin(), end()} construct, preferable for long-running operations.

Definition at line 424 of file rcu_map.hpp.

◆ Insert()

template<typename Key , typename Value , typename RcuMapTraits >
RcuMap< K, V, RcuMapTraits >::InsertReturnType rcu::RcuMap< K, V, RcuMapTraits >::Insert ( const Key & key,
ValuePtr value )

Inserts a new element into the container if there is no element with the key in the container. Returns a pair consisting of a pointer to the inserted element, or the already-existing element if no insertion happened, and a bool denoting whether the insertion took place.

Note
Copies the whole map if the key doesn't exist.

Definition at line 313 of file rcu_map.hpp.

◆ InsertOrAssign()

template<typename Key , typename Value , typename RcuMapTraits >
template<typename RawKey >
void rcu::RcuMap< Key, Value, RcuMapTraits >::InsertOrAssign ( RawKey && key,
RcuMap< Key, Value, RcuMapTraits >::ValuePtr value )

If a key equivalent to key already exists in the container, replaces the associated value. Otherwise, inserts a new pair into the map.

Definition at line 365 of file rcu_map.hpp.

◆ operator[]() [1/2]

template<typename Key , typename Value , typename RcuMapTraits >
const ValuePtr rcu::RcuMap< Key, Value, RcuMapTraits >::operator[] ( const Key & )

Returns a modifiable value pointer by key if exists or default-creates one.

Note
Copies the whole map if the key doesn't exist.

◆ operator[]() [2/2]

template<typename Key , typename Value , typename RcuMapTraits >
const ConstValuePtr rcu::RcuMap< Key, Value, RcuMapTraits >::operator[] ( const Key & ) const

Returns a readonly value pointer by its key if exists.

Exceptions
MissingKeyExceptionif the key is not present

◆ Pop()

template<typename Key , typename Value , typename RcuMapTraits >
RcuMap< K, V, RcuMapTraits >::ValuePtr rcu::RcuMap< K, V, RcuMapTraits >::Pop ( const Key & )

Removes a key from the map returning its value.

Returns
a value if the key was present, empty pointer otherwise
Note
Copies the whole map, might be slow for large maps.

Definition at line 396 of file rcu_map.hpp.

◆ SizeApprox()

template<typename K , typename V , typename RcuMapTraits >
size_t rcu::RcuMap< K, V, RcuMapTraits >::SizeApprox ( ) const

Returns an estimated size of the map at some point in time.

Definition at line 271 of file rcu_map.hpp.

◆ StartWrite()

template<typename K , typename V , typename RcuMapTraits >
auto rcu::RcuMap< K, V, RcuMapTraits >::StartWrite ( )

Starts a transaction, used to perform a series of arbitrary changes to the map.

The map is copied. Don't forget to Commit to apply the changes.

Definition at line 417 of file rcu_map.hpp.

◆ TryEmplace()

template<typename Key , typename Value , typename RcuMapTraits >
template<typename... Args>
RcuMap< K, V, RcuMapTraits >::InsertReturnType rcu::RcuMap< Key, Value, RcuMapTraits >::TryEmplace ( const K & key,
Args &&... args )

Definition at line 346 of file rcu_map.hpp.


The documentation for this class was generated from the following files: