#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};
    };
    rcu::RcuMap<std::string, Data> map;
 
    // 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 115 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

RcuMap &	operator= (const RcuMap &)=delete

RcuMap &	operator= (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 132 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 131 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 126 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 135 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 130 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 127 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 128 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 133 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 134 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 129 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 405 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 260 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 246 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 400 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 323 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 267 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 253 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 378 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 415 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 361 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

MissingKeyException if 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 390 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 274 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 410 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 343 of file rcu_map.hpp.

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

userver/rcu/fwd.hpp
userver/rcu/rcu_map.hpp

Detailed Description

Example usage:

Classes

Public Types

Public Member Functions

Member Typedef Documentation

◆ ConstIterator

◆ ConstValuePtr

◆ Hash

◆ InsertReturnType

◆ Iterator

◆ KeyEqual

◆ MutexType

◆ RawMap

◆ Snapshot

◆ ValuePtr

Member Function Documentation

◆ Assign()

◆ begin() [1/2]

◆ begin() [2/2]

◆ Clear()

◆ Emplace() [1/2]

◆ Emplace() [2/2]

◆ end() [1/2]

◆ end() [2/2]

◆ Erase()

◆ GetSnapshot()

◆ Insert()

◆ InsertOrAssign()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ Pop()

◆ SizeApprox()

◆ StartWrite()

◆ TryEmplace()