SynchronizedValue< T, LOCKTYPE > Class Template Reference

#include <synchronized.h>

Detailed Description

template<typename T, typename LOCKTYPE>
class maxon::SynchronizedValue< T, LOCKTYPE >

A SynchronizedValue<T, LOCKTYPE> stores a value of type T, protected by a lock of type LOCKTYPE. Aliases exist for the common lock types, so SynchronizedValue should not be used directly. Instead, use Synchronized<T> (Spinlock), RWSynchronized<T> (ARWLock).

Access to the value is enabled through the Read() and Write() functions. If possible, prefer using Synchronized over manually pairing locks with values, because there's less room for mistakes.

Template Parameters

T	Type of the contained value.
LOCKTYPE	Type of the lock value.

Classes
class	LockedReadPtr
class	LockedWritePtr

Public Types
using	ValueType = T
using	LockType = LOCKTYPE

Public Member Functions
	SynchronizedValue ()=default
	SynchronizedValue (const T &v)
	SynchronizedValue (T &&v)
	SynchronizedValue (const T &v, LOCKTYPE &&l)
	SynchronizedValue (T &&v, LOCKTYPE &&l)
template<typename ... ARGS>
	SynchronizedValue (IN_PLACE_TYPE, ARGS &&... args)
	SynchronizedValue (const typename std::conditional< TestForCopyFromMember< T >::isSupported, DummyParamType, SynchronizedValue >::type &src)
	SynchronizedValue (SynchronizedValue &&src)
SynchronizedValue &	operator= (const typename std::conditional< TestForCopyFromMember< T >::isSupported, DummyParamType, SynchronizedValue >::type &src)
Result< void >	CopyFrom (const typename std::conditional< TestForCopyFromMember< T >::isSupported, SynchronizedValue, DummyParamType >::type &src)
SynchronizedValue &	operator= (SynchronizedValue &&src)
LockedWritePtr	Write ()
template<typename F >
auto	Write (F &&func) -> decltype(func(_value))
template<typename U , typename F >
auto	Write (U &other, F &&func) -> decltype(func(_value, _value))
template<typename F >
auto	WriteAsync (F &&func) -> void
LockedReadPtr	Read () const
template<typename F >
auto	Read (F &&func) const -> decltype(func(_value))
template<typename U , typename F >
auto	Read (U &other, F &&func) -> decltype(func(_value, _value))
const T &	UnsynchronizedGet () const
T &	UnsynchronizedGet ()

Private Member Functions
template<typename U >
	SynchronizedValue (const SynchronizedValue &src, U &&)
template<typename U >
	SynchronizedValue (SynchronizedValue &&src, U &&)

Static Private Member Functions
template<typename L1 , typename L2 >
static void	AcquireLockPair (L1 &sg1, L2 &sg2)

Private Attributes
T	_value
LOCKTYPE	_lock

Member Typedef Documentation

ValueType

using ValueType = T

LockType

using LockType = LOCKTYPE

Constructor & Destructor Documentation

SynchronizedValue() [1/10]

SynchronizedValue ( const SynchronizedValue< T, LOCKTYPE > &  src, U &&    )

private

SynchronizedValue() [2/10]

SynchronizedValue ( SynchronizedValue< T, LOCKTYPE > &&  src, U &&    )

private

SynchronizedValue() [3/10]

SynchronizedValue ( )

default

Default constructor. Creates a Synchronized with a default constructed value.

SynchronizedValue() [4/10]

SynchronizedValue ( const T &  v )

explicit

Copy-from-value constructor. Initializes the contained value with a copy of v.

SynchronizedValue() [5/10]

SynchronizedValue ( T &&  v )

explicit

Move-from-value constructor. Initializes the contained value by moving from v.

SynchronizedValue() [6/10]

SynchronizedValue	(	const T &	v,
		LOCKTYPE &&	l
	)

Copy-from-value constructor. Initializes the contained value with a copy of v and constructs the internal lock from l.

SynchronizedValue() [7/10]

SynchronizedValue	(	T &&	v,
		LOCKTYPE &&	l
	)

Move-from-value constructor. Initializes the contained value by moving from v and constructs the internal lock from l.

SynchronizedValue() [8/10]

SynchronizedValue ( IN_PLACE_TYPE  , ARGS &&...  args  )

explicit

Emplace constructor. Constructs the contained value in-place with given arguments, i.e. T thisValue(std::forward<ARGS>(args) ...). For complex types that cannot be moved or copied.

SynchronizedValue() [9/10]

SynchronizedValue

(

const typename std::conditional< TestForCopyFromMember< T >::isSupported, DummyParamType, SynchronizedValue< T, LOCKTYPE > >::type &

src

)

Copy constructor. Initializes the contained value with a copy of the value of src. src is locked for reading during the operation.

SynchronizedValue() [10/10]

SynchronizedValue

(

SynchronizedValue< T, LOCKTYPE > &&

src

)

Move constructor. Initializes the contained value by moving from the value of src. src is locked for writing during the operation.

Member Function Documentation

operator=() [1/2]

SynchronizedValue& operator=

(

const typename std::conditional< TestForCopyFromMember< T >::isSupported, DummyParamType, SynchronizedValue< T, LOCKTYPE > >::type &

src

)

Copy assignment. Assigns the contained value to a copy of the value of src. During this operation, this is locked for writing and src is locked for reading.

CopyFrom()

Result<void> CopyFrom

(

const typename std::conditional< TestForCopyFromMember< T >::isSupported, SynchronizedValue< T, LOCKTYPE >, DummyParamType >::type &

src

)

operator=() [2/2]

SynchronizedValue& operator=

(

SynchronizedValue< T, LOCKTYPE > &&

src

)

Move assignment. Assigns the contained value by moving from the value of src. During this operation, this and src are locked for writing.

Write() [1/3]

LockedWritePtr Write

(

)

Returns a locked write pointer to the synchronized value. On creation, the respective lock is acquired. This may involve waiting, if the lock is already taken. During the lifetime of the pointer, the lock remains taken. The synchronized value can be accessed through the pointer. On destruction, the lock is released.

Example:

Synchronized<String> v;
// ...
*v.Write() = "Hello"_s;
DiagnosticOutput("@", *v);
v.Write()->Flush();

Note that for each temporary pointer, the lock is acquired and released again. You may also store the locked pointer to chain multiple operations:

Synchronized<BaseArray<Int>> v;
// ...
MAXON_SCOPE
{
  auto p = v.Write();
  p->Append(1) iferr_return;
  p->Append(2) iferr_return;
}

This is equivalent to using ScopedLock.

Write() [2/3]

auto Write

(

F &&

func

)

-> decltype(func(_value))

Executes a given function that can safely modify the inner value. It 1. acquires the lock, 2. calls the function and passes a reference to the value as argument, 3. releases the lock. The function should have a signature equivalent to

R func(T&);

Example:

Synchronized<BaseArray<Int>> v;
// ...
v.Write([] (auto& t)
  {
    iferr_scope;
    t.Append(1) iferr_return;
    t.Append(2) iferr_return;
    return OK;
  }) iferr_return;
}

Parameters

[in]

func

Function that gets write access to the contained value.

Write() [3/3]

auto Write	(	U &	other,
		F &&	func
	)		-> decltype(func(_value, _value))

A variant of Write that takes a second synchronized value. It 1. acquires both locks in order of their addresses, 2. calls the function and passes reference to both values as arguments, 3. releases the locks. This ensures no deadlocks can occur when trying to acquire two locks manually in different orders. The function should have a signature equivalent to

R func(T&, U&);

Example:

Synchronized<Int> v1;
Synchronized<Int> v2;
// ...
v1.Write([] (v2, auto& t1, auto& t2)
  {
    t1 = 1;
    t2 = 2;
    return OK;
  }) iferr_return;
}

Parameters

[in]	other	Another synchronized value.
[in]	func	Function that gets write access to the contained value.

WriteAsync()

auto WriteAsync

(

F &&

func

)

-> void

Executes a given function that can safely modify the inner value, potentially in an asynchronous way. It 1. acquires the lock in some thread, 2. calls the function in that thread and passes a reference to the value as argument, 3. releases the lock. The function should have a signature equivalent to

void func(T&);

Note that for locks (like Spinlock), WriteAsync will always be executed synchronously. However if you use a Serializer for LOCKTYPE, asynchronous execution may happen.

Parameters

[in]

func

Function that gets asynchronous write access to the contained value.

Read() [1/3]

LockedReadPtr Read

(

)

const

Similar to Write, but only provides read-access to the contained value. In other words, the value the locked pointer can access is of type

const T* 

.

Read() [2/3]

auto Read

(

F &&

func

)

const -> decltype(func(_value))

Similar to Write, but only provides read-access to the contained value. The function should have a signature equivalent to

R func(const T&);

Read() [3/3]

auto Read	(	U &	other,
		F &&	func
	)		-> decltype(func(_value, _value))

Similar to Write, but only provides read-access to the contained values. The function should have a signature equivalent to

R func(const T&, const U&);

UnsynchronizedGet() [1/2]

const T& UnsynchronizedGet

(

)

const

Returns the contained value without any synchronization. Use carefully.

UnsynchronizedGet() [2/2]

T& UnsynchronizedGet

(

)

Returns the contained value without any synchronization. Use carefully.

AcquireLockPair()

static void AcquireLockPair ( L1 &  sg1, L2 &  sg2  )

staticprivate

Member Data Documentation

_value

T _value

private

_lock

LOCKTYPE _lock

mutableprivate