ConstUniqueLockPtr< T, LockType > Class Template Reference

Overview

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

An RAII handle for read-only access whose lock may or may not be held.

Returned by SynchronizedValue::TryToSynchronize() and the *Synchronize() factories, or constructed directly in blocking, adopting, deferred, or try-to-lock mode. Acquisition can fail (or be deferred), so always check OwnsLock() (or operator bool) before dereferencing; accessing the value while the handle does not own the lock is undefined behavior. The lock, if owned, is released on destruction or by Unlock(). Move-only.

Template Parameters

T	The type of the guarded value.
LockType	The type of lock guarding the value.

Inheritance diagram for ConstUniqueLockPtr< T, LockType >:

Public Member Functions
	ConstUniqueLockPtr (const SynchronizedValue< T, LockType > &sync)
	Lock the given SynchronizedValue for read-only access, blocking until the lock is acquired. More...
	ConstUniqueLockPtr (const SynchronizedValue< T, LockType > &sync, AdoptLockTag) noexcept
	Adopt the given SynchronizedValue's lock, which the calling thread must already hold.
	ConstUniqueLockPtr (const SynchronizedValue< T, LockType > &sync, DeferLockTag) noexcept
	Reference the given SynchronizedValue without acquiring the lock.
	ConstUniqueLockPtr (const SynchronizedValue< T, LockType > &sync, TryToLockTag, int timeout_ms=0) noexcept
	Try to lock the given SynchronizedValue, waiting up to timeout_ms; check OwnsLock() for the result. More...
	ConstUniqueLockPtr (const ConstUniqueLockPtr &)=delete
ConstUniqueLockPtr &	operator= (const ConstUniqueLockPtr &)=delete
ConstUniqueLockPtr &	operator= (ConstUniqueLockPtr &&)=delete
	ConstUniqueLockPtr (ConstUniqueLockPtr &&other) noexcept
	Move ownership from another handle, which is left empty.
	~ConstUniqueLockPtr () noexcept
	Release the lock if owned.
	operator bool () const noexcept
	Whether this handle currently owns the lock.
bool	OwnsLock () const noexcept
	Whether this handle currently owns the lock.
void	Unlock () noexcept
	Release the lock early, if owned. Does nothing otherwise.
void	Lock ()
	Acquire the lock, blocking until it is available. More...
bool	TryLock (int timeout_ms=0)
	Try to acquire the lock, waiting up to timeout_ms. More...
void	Release () noexcept
	Disassociate from the lock without unlocking it; the caller becomes responsible for the lock.
const T &	operator* () const
	Get a reference to the guarded value. More...
const T *	operator-> () const
	Access a member of the guarded value. More...

Protected Attributes
const SynchronizedValue< T, LockType > *	sync_
bool	owns_

Friends
class	ConstStrictLockPtr< T, LockType >

Constructor & Destructor Documentation

ConstUniqueLockPtr() [1/2]

ConstUniqueLockPtr ( const SynchronizedValue< T, LockType > &  sync )

inlineexplicit

Lock the given SynchronizedValue for read-only access, blocking until the lock is acquired.

Exceptions

std::runtime_error

if lock could not be acquired.

ConstUniqueLockPtr() [2/2]

ConstUniqueLockPtr ( const SynchronizedValue< T, LockType > &  sync, TryToLockTag  , int  timeout_ms = 0  )

inlinenoexcept

Try to lock the given SynchronizedValue, waiting up to timeout_ms; check OwnsLock() for the result.

timeout_ms has the same semantics as TryLock().

Member Function Documentation

Lock()

void Lock ( )

inline

Acquire the lock, blocking until it is available.

Exceptions

std::runtime_error

if this handle already owns the lock, no longer references one, or locking failed.

operator*()

const T& operator* ( ) const

inline

Get a reference to the guarded value.

Exceptions

std::runtime_error

if this handle does not own the lock.

operator->()

const T* operator-> ( ) const

inline

Access a member of the guarded value.

Exceptions

std::runtime_error

if this handle does not own the lock.

TryLock()

bool TryLock ( int  timeout_ms = 0 )

inline

Try to acquire the lock, waiting up to timeout_ms.

timeout_ms follows EtcPal timeout semantics, with the same platform behavior as SynchronizedValue::TryToSynchronize(): where the lock supports timed locking (see SupportsTimedLock) it is passed straight to the underlying etcpal_*_timed_lock() call, so a negative value (ETCPAL_WAIT_FOREVER) blocks until the lock is acquired; elsewhere this always polls.

Parameters

timeout_ms

How long to wait for the lock, in milliseconds. Defaults to 0 (poll, return immediately).

Returns

Whether the lock was acquired.

Exceptions

std::runtime_error

if this handle already owns the lock or no longer references one.

---

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

• include/etcpal/cpp/synchronized_value.h