boost::fairness::shared_lock< Lockable > Class Template Reference

The class shared_lock is a general-purpose shared mutex ownership wrapper allowing deferred locking, timed locking and transfer of lock ownership. Locking a shared_lock locks the associated shared mutex in shared mode (to lock it in exclusive mode, std::unique_lock can be used).
The shared_lock class is movable, but not copyable – it meets the requirements of MoveConstructible and MoveAssignable but not of CopyConstructible or CopyAssignable.
shared_lock meets the Lockable requirements. If Lockable meets the SharedTimedLockable requirements, shared_lock also meets TimedLockable requirements.
In order to wait in a shared mutex in shared ownership mode, std::condition_variable_any can be used (std::condition_variable requires std::unique_lock and so can only wait in unique ownership mode). More...

#include <shared_lock.hpp>

Public Member Functions
void	lock (Priority_t const p=BOOST_FAIRNESS_MINIMUM_PRIORITY)
	Locks the associated mutex in shared mode. Effectively calls mutex()->lock_shared().
Priority_t	lock_priority () const noexcept
	Checks the current priority of *this. #TODO.
Lockable *	mutex () const noexcept
	Returns a pointer to the associated mutex, or a null pointer if there is no associated mutex.
	operator bool () const noexcept
	Checks whether *this owns a locked mutex or not. Effectively calls owns_lock().
bool	owns_lock () const noexcept
	Checks whether *this owns a locked mutex or not.
Lockable *	release () noexcept
	Breaks the association of the associated mutex, if any, and *this. No locks are unlocked. If the *this held ownership of the associated mutex prior to the call, the caller is now responsible to unlock the mutex.
void	swap (shared_lock &other) noexcept
	Exchanges the internal states of the lock objects.
bool	try_lock (Priority_t const p=BOOST_FAIRNESS_MINIMUM_PRIORITY)
	Tries to lock the associated mutex in shared mode without blocking. Effectively calls mutex()->try_lock_shared(). std::system_error is thrown if there is no associated mutex or if the mutex is already locked.
template<typename Rep , typename Period >
bool	try_lock_for (const std::chrono::duration< Rep, Period > &rtime, Priority_t const p=BOOST_FAIRNESS_MINIMUM_PRIORITY)
	Tries to lock the associated mutex in shared mode. Blocks until specified rtime has elapsed or the lock is acquired, whichever comes first. On successful lock acquisition returns true, otherwise returns false. Effectively calls mutex()->try_lock_shared_for(rtime). This function may block for longer than rtime due to scheduling or resource contention delays. The standard recommends that a steady clock is used to measure the duration. If an implementation uses a system clock instead, the wait time may also be sensitive to clock adjustments. std::system_error is thrown if there is no associated mutex or if the mutex is already locked. The behavior is undefined if Lockable does not meet the SharedTimedLockable requirements.
template<typename Clock , typename Duration >
bool	try_lock_until (const std::chrono::time_point< Clock, Duration > &atime, Priority_t const p=BOOST_FAIRNESS_MINIMUM_PRIORITY)
	Tries to lock the associated mutex in shared mode. Blocks until specified atime has been reached or the lock is acquired, whichever comes first. On successful lock acquisition returns true, otherwise returns false. May block for longer than until atime has been reached. Effectively calls mutex()->try_lock_shared_until(timeout_time). std::system_error is thrown if there is no associated mutex or if the mutex is already locked. Clock must meet the Clock requirements. The behavior is undefined if Mutex does not meet the SharedTimedLockable requirements. The program is ill-formed if std::chrono::is_clock_v<Clock> is false.
void	unlock ()
	Unlocks the associated mutex from shared mode. Effectively calls mutex()->unlock_shared(). std::system_error is thrown if there is no associated mutex or if the mutex is not locked.

Detailed Description

template<typename Lockable>
class boost::fairness::shared_lock< Lockable >

The class shared_lock is a general-purpose shared mutex ownership wrapper allowing deferred locking, timed locking and transfer of lock ownership. Locking a shared_lock locks the associated shared mutex in shared mode (to lock it in exclusive mode, std::unique_lock can be used).
The shared_lock class is movable, but not copyable – it meets the requirements of MoveConstructible and MoveAssignable but not of CopyConstructible or CopyAssignable.
shared_lock meets the Lockable requirements. If Lockable meets the SharedTimedLockable requirements, shared_lock also meets TimedLockable requirements.
In order to wait in a shared mutex in shared ownership mode, std::condition_variable_any can be used (std::condition_variable requires std::unique_lock and so can only wait in unique ownership mode).

Template Parameters

Lockable

: the type of the shared mutex to lock. The type must meet the SharedLockable requirements.

Member Function Documentation

lock()

template<typename Lockable >

void boost::fairness::shared_lock< Lockable >::lock ( Priority_t const  p = BOOST_FAIRNESS_MINIMUM_PRIORITY )

inline

Locks the associated mutex in shared mode. Effectively calls mutex()->lock_shared().

Parameters

p	: the priority of the mutex.

Returns

none.

Exceptions

• Any exceptions thrown by mutex()->lock_shared();
• If there is no associated mutex, std::system_error with an error code of std::errc::operation_not_permitted;
• If the associated mutex is already locked by this shared_lock (that is, owns_lock() returns true), std::system_error with an error code of std::errc::resource_deadlock_would_occur.

lock_priority()

template<typename Lockable >

Priority_t boost::fairness::shared_lock< Lockable >::lock_priority ( ) const

inlinenoexcept

Checks the current priority of *this. #TODO.

Returns

Priority_t : the current priority.

mutex()

template<typename Lockable >

Lockable * boost::fairness::shared_lock< Lockable >::mutex ( ) const

inlinenoexcept

Returns a pointer to the associated mutex, or a null pointer if there is no associated mutex.

Returns

Lockable* : Pointer to the associated mutex or a null pointer if there is no associated mutex.

operator bool()

template<typename Lockable >

boost::fairness::shared_lock< Lockable >::operator bool ( ) const

inlineexplicitnoexcept

Checks whether *this owns a locked mutex or not. Effectively calls owns_lock().

Returns

true if *this has an associated mutex and has acquired shared ownership of it.

false otherwise.

owns_lock()

template<typename Lockable >

bool boost::fairness::shared_lock< Lockable >::owns_lock ( ) const

inlinenoexcept

Checks whether *this owns a locked mutex or not.

Returns

true if *this has an associated mutex and has acquired shared ownership of it.

false otherwise.

release()

template<typename Lockable >

Lockable * boost::fairness::shared_lock< Lockable >::release ( )

inlinenoexcept

Breaks the association of the associated mutex, if any, and *this.
No locks are unlocked. If the *this held ownership of the associated mutex prior to the call, the caller is now responsible to unlock the mutex.

Returns

Lockable* : Pointer to the associated mutex or a null pointer if there was no associated mutex.

swap()

template<typename Lockable >

void boost::fairness::shared_lock< Lockable >::swap ( shared_lock< Lockable > &  other )

inlinenoexcept

Exchanges the internal states of the lock objects.

Parameters

other

: the lock to swap the state with.

try_lock()

template<typename Lockable >

bool boost::fairness::shared_lock< Lockable >::try_lock ( Priority_t const  p = BOOST_FAIRNESS_MINIMUM_PRIORITY )

inline

Tries to lock the associated mutex in shared mode without blocking. Effectively calls mutex()->try_lock_shared().
std::system_error is thrown if there is no associated mutex or if the mutex is already locked.

Parameters

p	: the current priority.

Returns

true if the ownership of the mutex has been acquired successfully.

false otherwise.

try_lock_for()

template<typename Lockable >

template<typename Rep , typename Period >

bool boost::fairness::shared_lock< Lockable >::try_lock_for ( const std::chrono::duration< Rep, Period > &  rtime, Priority_t const  p = BOOST_FAIRNESS_MINIMUM_PRIORITY  )

inline

Tries to lock the associated mutex in shared mode. Blocks until specified rtime has elapsed or the lock is acquired, whichever comes first. On successful lock acquisition returns true, otherwise returns false. Effectively calls mutex()->try_lock_shared_for(rtime).
This function may block for longer than rtime due to scheduling or resource contention delays.
The standard recommends that a steady clock is used to measure the duration. If an implementation uses a system clock instead, the wait time may also be sensitive to clock adjustments.
std::system_error is thrown if there is no associated mutex or if the mutex is already locked.
The behavior is undefined if Lockable does not meet the SharedTimedLockable requirements.

Template Parameters

Rep	TODO
Period	TODO

Parameters

rtime	: maximum duration to block for.
p

Returns

true : if the ownership of the mutex has been acquired successfully.

false : otherwise.

Exceptions

• Any exceptions thrown by mutex()->try_lock_shared_for(timeout_duration).
• If there is no associated mutex, std::system_error with an error code of std::errc::operation_not_permitted;
• If the mutex is already locked, std::system_error with an error code of std::errc::resource_deadlock_would_occur.

try_lock_until()

template<typename Lockable >

template<typename Clock , typename Duration >

bool boost::fairness::shared_lock< Lockable >::try_lock_until ( const std::chrono::time_point< Clock, Duration > &  atime, Priority_t const  p = BOOST_FAIRNESS_MINIMUM_PRIORITY  )

inline

Tries to lock the associated mutex in shared mode. Blocks until specified atime has been reached or the lock is acquired, whichever comes first. On successful lock acquisition returns true, otherwise returns false. May block for longer than until atime has been reached.
Effectively calls mutex()->try_lock_shared_until(timeout_time).
std::system_error is thrown if there is no associated mutex or if the mutex is already locked.
Clock must meet the Clock requirements. The behavior is undefined if Mutex does not meet the SharedTimedLockable requirements. The program is ill-formed if std::chrono::is_clock_v<Clock> is false.

Template Parameters

Clock	TODO
Duration	TODO

Parameters

atime	: maximum time point to block until.
p	: the current priority.

Returns

true : if the ownership of the mutex has been acquired successfully.

false : otherwise.

Exceptions

• Any exceptions thrown by mutex()->try_lock_shared_until(atime);
• If there is no associated mutex, std::system_error with an error code of std::errc::operation_not_permitted;
• If the mutex is already locked, std::system_error with an error code of std::errc::resource_deadlock_would_occur.

unlock()

template<typename Lockable >

void boost::fairness::shared_lock< Lockable >::unlock ( )

inline

Unlocks the associated mutex from shared mode. Effectively calls mutex()->unlock_shared().
std::system_error is thrown if there is no associated mutex or if the mutex is not locked.

Parameters

none.

Returns

none.

Exceptions

• Any exceptions thrown by mutex()->unlock_shared();
• If there is no associated mutex, std::system_error with an error code of std::errc::operation_not_permitted.

---

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

• include/boost/fairness/shared_lock.hpp