SynchronizedValue< T, LockType > Class Template Reference

Overview

template<typename T, typename LockType>
class etcpal::SynchronizedValue< T, LockType >

A value bundled with a lock that guards all access to it.

The wrapped value can only be reached through an RAII handle that holds the lock, so it cannot be accessed without synchronization. See the synchronized_value (Synchronized Values) module overview for an example.

Template Parameters

T	The type of the guarded value.
LockType	The type of lock guarding the value. Must provide bool Lock(), bool TryLock(int timeout_ms), and Unlock() (e.g. etcpal::Mutex or etcpal::RecursiveMutex; defaults to etcpal::Mutex). TryLock() and Unlock() are called from noexcept contexts and must not throw; report failure by return value.

Public Member Functions
template<typename... Args, typename = typename std::enable_if< std::is_constructible<T, Args&&...>::value && !std::is_same<typename std::decay<typename detail::FirstType<Args...>::type>::type, SynchronizedValue>::value>::type>
	SynchronizedValue (Args &&... args) noexcept(std::is_nothrow_constructible< T, Args... >::value)
	Construct the guarded value in place, forwarding the given arguments to its constructor. More...
Unsafe Access
Access the value or lock directly, without locking. Use with care.
T &	GetValueUnsafe () noexcept
LockType &	GetLockUnsafe () noexcept
Locked Access
Obtain an RAII handle that holds the lock for as long as the handle exists.
StrictLockPtr< T, LockType >	operator-> ()
	Lock the value and access a member of it for the duration of the enclosing expression. More...
ConstStrictLockPtr< T, LockType >	operator-> () const
	Lock the value and access a member of it for the duration of the enclosing expression. More...
StrictLockPtr< T, LockType >	Synchronize ()
	Lock the value, returning a handle that holds the lock until it is destroyed. More...
ConstStrictLockPtr< T, LockType >	Synchronize () const
	Lock the value, returning a handle that holds the lock until it is destroyed. More...
Non-blocking Locked Access
Try to acquire the lock, waiting up to timeout_ms. Check OwnsLock() (or operator bool) on the result. timeout_ms follows EtcPal timeout semantics. Where the lock supports timed locking (see SupportsTimedLock) it is passed straight to the underlying etcpal_*_timed_lock() call: 0 polls, a positive value waits up to that long, and a negative value (ETCPAL_WAIT_FOREVER) blocks until the lock is acquired. On platforms without timed-lock support, etcpal_*_timed_lock() ignores the timeout and blocks indefinitely for any nonzero value, so this always polls there instead. Parameters timeout_ms How long to wait for the lock, in milliseconds. Defaults to 0 (poll, return immediately).
UniqueLockPtr< T, LockType >	TryToSynchronize (int timeout_ms=0) noexcept
ConstUniqueLockPtr< T, LockType >	TryToSynchronize (int timeout_ms=0) const noexcept
Unique Locked Access
Obtain a UniqueLockPtr handle in a specific acquisition mode, mirroring Boost's unique_synchronize()/defer_synchronize()/adopt_synchronize().
UniqueLockPtr< T, LockType >	UniqueSynchronize ()
	Lock the value, returning a handle that can also Unlock(), re-Lock(), or Release() it. More...
ConstUniqueLockPtr< T, LockType >	UniqueSynchronize () const
UniqueLockPtr< T, LockType >	DeferSynchronize () noexcept
	Reference the value without locking; acquire later with Lock() or TryLock() on the handle.
ConstUniqueLockPtr< T, LockType >	DeferSynchronize () const noexcept
UniqueLockPtr< T, LockType >	AdoptSynchronize () noexcept
	Adopt the lock, which the calling thread must already hold, into a handle that will release it.
ConstUniqueLockPtr< T, LockType >	AdoptSynchronize () const noexcept
Visitation
Invoke a callable with the guarded value held under lock for the call's duration. func must not return a reference (enforced at compile time): the lock is released when Apply returns, so a returned reference into the guarded value would escape it unguarded. Parameters func A callable taking a reference to the guarded value. Returns Whatever func returns. Exceptions std::runtime_error if lock could not be acquired.
template<typename F >
decltype(auto)	Apply (F &&func)
template<typename F >
decltype(auto)	Apply (F &&func) const

Friends
class	ConstStrictLockPtr< T, LockType >
class	StrictLockPtr< T, LockType >
class	ConstUniqueLockPtr< T, LockType >
class	UniqueLockPtr< T, LockType >

Constructor & Destructor Documentation

SynchronizedValue()

SynchronizedValue ( Args &&...  args )

inlineexplicitnoexcept

Construct the guarded value in place, forwarding the given arguments to its constructor.

Excluded from overload resolution when T is not constructible from the arguments (so std::is_constructible reports accurately) and for a single SynchronizedValue argument, so that copy/move attempts select the implicitly-deleted copy constructor (and get a clear diagnostic) instead of trying to construct T from a SynchronizedValue.

Member Function Documentation

operator->() [1/2]

StrictLockPtr<T, LockType> operator-> ( )

inline

Lock the value and access a member of it for the duration of the enclosing expression.

Exceptions

std::runtime_error

if lock could not be acquired.

operator->() [2/2]

ConstStrictLockPtr<T, LockType> operator-> ( ) const

inline

Lock the value and access a member of it for the duration of the enclosing expression.

Exceptions

std::runtime_error

if lock could not be acquired.

Synchronize() [1/2]

StrictLockPtr<T, LockType> Synchronize ( )

inline

Lock the value, returning a handle that holds the lock until it is destroyed.

Exceptions

std::runtime_error

if lock could not be acquired.

Synchronize() [2/2]

ConstStrictLockPtr<T, LockType> Synchronize ( ) const

inline

Lock the value, returning a handle that holds the lock until it is destroyed.

Exceptions

std::runtime_error

if lock could not be acquired.

UniqueSynchronize()

UniqueLockPtr<T, LockType> UniqueSynchronize ( )

inline

Lock the value, returning a handle that can also Unlock(), re-Lock(), or Release() it.

Exceptions

std::runtime_error

if lock could not be acquired.

---

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

• include/etcpal/cpp/synchronized_value.h