Map-like structure allowing RCU keyset updates. More...

#include <userver/rcu/rcu_map.hpp>

Classes
struct	InsertReturnTypeImpl

Public Types
using	ValuePtr = std::shared_ptr< Value >

using	Iterator = RcuMapIterator< Key, Value, Value >

using	ConstValuePtr = std::shared_ptr< const Value >

using	ConstIterator = RcuMapIterator< Key, Value, const Value >

using	RawMap = std::unordered_map< Key, ValuePtr >

using	Snapshot = std::unordered_map< Key, ConstValuePtr >

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 >	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 >::InsertReturnType	Emplace (const K &key, Args &&... args)

template<typename... Args>
RcuMap< K, V >::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 ()

Detailed Description

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

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 81 of file rcu_map.hpp.

Member Typedef Documentation

◆ ConstIterator

template<typename Key , typename Value >

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

Definition at line 93 of file rcu_map.hpp.

◆ ConstValuePtr

template<typename Key , typename Value >

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

Definition at line 92 of file rcu_map.hpp.

◆ InsertReturnType

template<typename Key , typename Value >

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

Definition at line 96 of file rcu_map.hpp.

◆ Iterator

template<typename Key , typename Value >

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

Definition at line 91 of file rcu_map.hpp.

◆ RawMap

template<typename Key , typename Value >

using rcu::RcuMap< Key, Value >::RawMap = std::unordered_map<Key, ValuePtr>

Definition at line 94 of file rcu_map.hpp.

◆ Snapshot

template<typename Key , typename Value >

using rcu::RcuMap< Key, Value >::Snapshot = std::unordered_map<Key, ConstValuePtr>

Definition at line 95 of file rcu_map.hpp.

◆ ValuePtr

template<typename Key , typename Value >

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

Definition at line 90 of file rcu_map.hpp.

Member Function Documentation

◆ Assign()

template<typename K , typename V >

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

Replace current data by data from new_map.

Definition at line 370 of file rcu_map.hpp.

◆ begin() [1/2]

template<typename K , typename V >

RcuMap< K, V >::Iterator rcu::RcuMap< K, V >::begin

Definition at line 221 of file rcu_map.hpp.

◆ begin() [2/2]

template<typename K , typename V >

RcuMap< K, V >::ConstIterator rcu::RcuMap< K, V >::begin

Definition at line 207 of file rcu_map.hpp.

◆ Clear()

template<typename K , typename V >

void rcu::RcuMap< K, V >::Clear

Resets the map to an empty state.

Definition at line 365 of file rcu_map.hpp.

◆ Emplace() [1/2]

template<typename Key , typename Value >

template<typename... Args>

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

Definition at line 285 of file rcu_map.hpp.

◆ Emplace() [2/2]

template<typename Key , typename Value >

template<typename... Args>

InsertReturnType rcu::RcuMap< Key, Value >::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 >

RcuMap< K, V >::Iterator rcu::RcuMap< K, V >::end

Definition at line 228 of file rcu_map.hpp.

◆ end() [2/2]

template<typename K , typename V >

RcuMap< K, V >::ConstIterator rcu::RcuMap< K, V >::end

Definition at line 214 of file rcu_map.hpp.

◆ Erase()

template<typename Key , typename Value >

bool rcu::RcuMap< K, V >::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 343 of file rcu_map.hpp.

◆ GetSnapshot()

template<typename K , typename V >

RcuMap< K, V >::Snapshot rcu::RcuMap< K, V >::GetSnapshot

Returns a readonly copy of the map.

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

Definition at line 380 of file rcu_map.hpp.

◆ Insert()

template<typename Key , typename Value >

RcuMap< K, V >::InsertReturnType rcu::RcuMap< K, V >::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 275 of file rcu_map.hpp.

◆ InsertOrAssign()

template<typename Key , typename Value >

template<typename RawKey >

void rcu::RcuMap< Key, Value >::InsertOrAssign	(	RawKey &&	key,
		RcuMap< Key, Value >::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 326 of file rcu_map.hpp.

◆ operator[]() [1/2]

template<typename Key , typename Value >

const ValuePtr rcu::RcuMap< Key, Value >::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 >

const ConstValuePtr rcu::RcuMap< Key, Value >::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 >

RcuMap< K, V >::ValuePtr rcu::RcuMap< K, V >::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 355 of file rcu_map.hpp.

◆ SizeApprox()

template<typename K , typename V >

size_t rcu::RcuMap< K, V >::SizeApprox

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

Definition at line 235 of file rcu_map.hpp.

◆ StartWrite()

template<typename K , typename V >

rcu::WritablePtr< typename RcuMap< K, V >::RawMap > rcu::RcuMap< K, V >::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 375 of file rcu_map.hpp.

◆ TryEmplace()

template<typename Key , typename Value >

template<typename... Args>

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

Definition at line 306 of file rcu_map.hpp.

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

userver/rcu/rcu_map.hpp

Classes

Public Types

Public Member Functions

Detailed Description

Example usage:

Member Typedef Documentation

◆ ConstIterator

◆ ConstValuePtr

◆ InsertReturnType

◆ Iterator

◆ 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()