v1::rcu< T, Allocator > Class Template Reference

#include <hikogui/concurrency/rcu.hpp>

Public Types
using	value_type = T
using	allocator_type = Allocator

Public Member Functions
constexpr	rcu (allocator_type allocator=allocator_type{}) noexcept
	Construct a new rcu object.
	rcu (rcu const &)=delete
	rcu (rcu &&)=delete
rcu &	operator= (rcu const &)=delete
rcu &	operator= (rcu &&)=delete
void	lock () const noexcept
	Lock the rcu pointer for reading.
void	unlock () const noexcept
	Unlock the rcu pointer for reading.
value_type const *	get () const noexcept
	get the rcu-pointer.
value_type const *	unsafe_get () noexcept
	get the rcu-pointer.
uint64_t	version () const noexcept
	The version of the lock.
size_t	capacity () const noexcept
	Number of objects that are currently allocated.
value_type *	exchange (value_type *ptr) noexcept
	Exchange the rcu-pointers.
value_type *	copy (value_type const *ptr) const noexcept
	Create a copy of the value at the given pointer.
value_type *	copy () const noexcept
	Create a copy of the value.
void	abort (value_type *ptr) const noexcept
	Abort a copy.
void	commit (value_type *ptr) noexcept
	Commit the copied value.
void	emplace (auto &&...args) noexcept
	Emplace a new value.
bool	empty () const noexcept
	operator bool () const noexcept
void	reset () noexcept
rcu &	operator= (nullptr_t) noexcept
void	add_old_copy (uint64_t old_version, value_type *old_ptr) noexcept
	Add an old copy.

Detailed Description

template<typename T, typename Allocator = std::allocator<T>>
class v1::rcu< T, Allocator >

Read-copy-update.

Template Parameters

T	The type managed by RCU.
Allocator	The allocator used to allocate objects of type T.

Constructor & Destructor Documentation

rcu()

template<typename T , typename Allocator = std::allocator<T>>

constexpr v1::rcu< T, Allocator >::rcu ( allocator_type allocator = allocator_type{} )

inlineconstexprnoexcept

Construct a new rcu object.

Note

The initial rcu will be a nullptr.

Parameters

allocator

The allocator to use.

Member Function Documentation

abort()

template<typename T , typename Allocator = std::allocator<T>>

void v1::rcu< T, Allocator >::abort ( value_type * ptr ) const

inlinenoexcept

Abort a copy.

Parameters

ptr	The pointer returned by copy().

add_old_copy()

template<typename T , typename Allocator = std::allocator<T>>

void v1::rcu< T, Allocator >::add_old_copy ( uint64_t old_version, value_type * old_ptr )

inlinenoexcept

Add an old copy.

This function will manage old copies. It will keep a list of copies that are still being used, and destroy and deallocate old copies that are no longer being used.

Parameters

old_version	The version when the pointer was exchanged.
old_ptr	The pointer that was exchanged, may be a nullptr.

capacity()

template<typename T , typename Allocator = std::allocator<T>>

size_t v1::rcu< T, Allocator >::capacity ( ) const

inlinenoexcept

Number of objects that are currently allocated.

This function is useful in tests to determine if the old copies are properly deallocated.

commit()

template<typename T , typename Allocator = std::allocator<T>>

void v1::rcu< T, Allocator >::commit ( value_type * ptr )

inlinenoexcept

Commit the copied value.

Parameters

ptr	The pointer returned by copy().

copy() [1/2]

template<typename T , typename Allocator = std::allocator<T>>

value_type * v1::rcu< T, Allocator >::copy ( ) const

inlinenoexcept

Create a copy of the value.

Note

This function takes an internal lock during copying of the current rcu-value.

It is undefined behavior if the internal value is a nullptr.

Returns

A pointer to newly allocated value and copy constructed from the current rcu-value.

copy() [2/2]

template<typename T , typename Allocator = std::allocator<T>>

value_type * v1::rcu< T, Allocator >::copy ( value_type const * ptr ) const

inlinenoexcept

Create a copy of the value at the given pointer.

Note

This function should be called while holding the lock.

It is undefined behavior to pass a nullptr as the argument

Parameters

ptr	The pointer to a value to copy.

Returns

A pointer to newly allocated and copy constructed value.

emplace()

template<typename T , typename Allocator = std::allocator<T>>

void v1::rcu< T, Allocator >::emplace ( auto &&... args )

inlinenoexcept

Emplace a new value.

This function will allocate and construct a new value, then replace the current value.

This function will also destroy and deallocate old values when no other threads are reading them.

Parameters

args	The arguments passed to the constructor of the value.

exchange()

template<typename T , typename Allocator = std::allocator<T>>

value_type * v1::rcu< T, Allocator >::exchange ( value_type * ptr )

inlinenoexcept

Exchange the rcu-pointers.

Note

This function should be called while holding the lock.

Parameters

ptr	The new pointer value, may be nullptr.

Returns

The old pointer value, may be nullptr.

get()

template<typename T , typename Allocator = std::allocator<T>>

value_type const * v1::rcu< T, Allocator >::get ( ) const

inlinenoexcept

get the rcu-pointer.

Note

A lock on the RCU should be held while dereferencing the returned pointer.

Returns

a const pointer to the current value.

lock()

template<typename T , typename Allocator = std::allocator<T>>

void v1::rcu< T, Allocator >::lock ( ) const

inlinenoexcept

Lock the rcu pointer for reading.

unlock()

template<typename T , typename Allocator = std::allocator<T>>

void v1::rcu< T, Allocator >::unlock ( ) const

inlinenoexcept

Unlock the rcu pointer for reading.

unsafe_get()

template<typename T , typename Allocator = std::allocator<T>>

value_type const * v1::rcu< T, Allocator >::unsafe_get ( )

inlinenoexcept

get the rcu-pointer.

Note

A lock on the RCU should be held while dereferencing the returned pointer.

This function is unsafe you must follow the rules in https://github.com/torvalds/linux/blob/master/Documentation/RCU/rcu_dereference.rst

Returns

a const pointer to the current value.

version()

template<typename T , typename Allocator = std::allocator<T>>

uint64_t v1::rcu< T, Allocator >::version ( ) const

inlinenoexcept

The version of the lock.

Note

This function should be called while holding the lock.

Returns

a version number used for add_old_copy().

---

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

• hikogui/src/hikogui/concurrency/rcu.hpp