unique_lock Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

Represents a template that can be instantiated to create objects that manage the locking and unlocking of a mutex.

template <class Mutex>
class unique_lock;

The template argument Mutex must name a mutex type.

Internally, a unique_lock stores a pointer to an associated mutex object and a bool that indicates whether the current thread owns the mutex.

Public Typedefs

NameDescription
unique_lock::mutex_typeSynonym for the template argument Mutex.

Public Constructors

NameDescription
unique_lock::unique_lock ConstructorConstructs a unique_lock object.
unique_lock::~unique_lock DestructorReleases any resources that are associated with the unique_lock object.

Public Methods

NameDescription
unique_lock::lock MethodBlocks the calling thread until the thread obtains ownership of the associated mutex.
unique_lock::mutex MethodRetrieves the stored pointer to the associated mutex.
unique_lock::owns_lock MethodSpecifies whether the calling thread owns the associated mutex.
unique_lock::release MethodDisassociates the unique_lock object from the associated mutex object.
unique_lock::swap MethodSwaps the associated mutex and ownership status with that of a specified object.
unique_lock::try_lock MethodAttempts to obtain ownership of the associated mutex without blocking.
unique_lock::try_lock_for MethodAttempts to obtain ownership of the associated mutex without blocking.
unique_lock::try_lock_until MethodAttempts to obtain ownership of the associated mutex without blocking.
unique_lock::unlock MethodReleases ownership of the associated mutex.

Public Operators

NameDescription
unique_lock::operator boolSpecifies whether the calling thread has ownership of the associated mutex.
unique_lock::operator=Copies the stored mutex pointer and associated ownership status from a specified object.

unique_lock

Header: mutex

Namespace: std

Blocks the calling thread until the thread obtains ownership of the associated mutex.

void lock();

Remarks

If the stored mutex pointer is null, this method throws a system_error that has an error code of operation_not_permitted.

If the calling thread already owns the associated mutex, this method throws a system_error that has an error code of resource_deadlock_would_occur.

Otherwise, this method calls lock on the associated mutex and sets the internal thread ownership flag to true.

Retrieves the stored pointer to the associated mutex.

mutex_type *mutex() const noexcept;

Specifies whether the calling thread has ownership of the associated mutex.

explicit operator bool() noexcept

Return Value

true if the thread owns the mutex; otherwise false.

Copies the stored mutex pointer and associated ownership status from a specified object.

unique_lock& operator=(unique_lock&& Other) noexcept;

Parameters

Other
A unique_lock object.

Return Value

*this

Remarks

If the calling thread owns the previously associated mutex, before this method calls unlock on the mutex, it assigns the new values.

After the copy, this method sets Other to a default-constructed state.

Specifies whether the calling thread owns the associated mutex.

bool owns_lock() const noexcept;

Return Value

true if the thread owns the mutex; otherwise, false.

Disassociates the unique_lock object from the associated mutex object.

mutex_type *release() noexcept;

Return Value

The previous value of the stored mutex pointer.

Remarks

This method sets the value of the stored mutex pointer to 0 and sets the internal mutex ownership flag to false.

Swaps the associated mutex and ownership status with that of a specified object.

void swap(unique_lock& Other) noexcept;

Parameters

Other
A unique_lock object.

Attempts to obtain ownership of the associated mutex without blocking.

bool try_lock() noexcept;

Return Value

true if the method successfully obtains ownership of the mutex; otherwise, false.

Remarks

If the stored mutex pointer is null, the method throws a system_error that has an error code of operation_not_permitted.

If the calling thread already owns the mutex, the method throws a system_error that has an error code of resource_deadlock_would_occur.

Attempts to obtain ownership of the associated mutex without blocking.

template <class Rep, class Period>
bool try_lock_for(
    const chrono::duration<Rep, Period>& Rel_time);

Parameters

Rel_time
A chrono::duration object that specifies the maximum amount of time that the method attempts to obtain ownership of the mutex.

Return Value

true if the method successfully obtains ownership of the mutex; otherwise, false.

Remarks

If the stored mutex pointer is null, the method throws a system_error that has an error code of operation_not_permitted.

If the calling thread already owns the mutex, the method throws a system_error that has an error code of resource_deadlock_would_occur.

Attempts to obtain ownership of the associated mutex without blocking.

template <class Clock, class Duration>
bool try_lock_until(const chrono::time_point<Clock, Duration>& Abs_time);

bool try_lock_until(const xtime* Abs_time);

Parameters

Abs_time
A point in time that specifies the threshold after which the method no longer attempts to obtain ownership of the mutex.

Return Value

true if the method successfully obtains ownership of the mutex; otherwise, false.

Remarks

If the stored mutex pointer is null, the method throws a system_error that has an error code of operation_not_permitted.

If the calling thread already owns the mutex, the method throws a system_error that has an error code of resource_deadlock_would_occur.

Constructs a unique_lock object.

unique_lock() noexcept;
unique_lock(unique_lock&& Other) noexcept;
explicit unique_lock(mutex_type& Mtx);

unique_lock(mutex_type& Mtx, adopt_lock_t Adopt);

unique_lock(mutex_type& Mtx, defer_lock_t Defer) noexcept;
unique_lock(mutex_type& Mtx, try_to_lock_t Try);

template <class Rep, class Period>
unique_lock(mutex_type& Mtx,
    const chrono::duration<Rep, Period>  
Rel_time);

template <class Clock, class Duration>
unique_lock(mutex_type& Mtx,
    const chrono::time_point<Clock, Duration>  
Abs_time);

unique_lock(mutex_type& Mtx,
    const xtime* Abs_time) noexcept;

Parameters

Mtx
A mutex type object.

Rel_time
A chrono::duration object that specifies the maximum amount of time that the method attempts to obtain ownership of the mutex.

Abs_time
A point in time that specifies the threshold after which the method no longer attempts to obtain ownership of the mutex.

Other
A unique_lock object.

Remarks

The first constructor constructs an object that has an associated mutex pointer value of 0.

The second constructor moves the associated mutex status from Other. After the move, Other is no longer associated with a mutex.

The remaining constructors store & Mtx as the stored mutex pointer. Ownership of the mutex is determined by the second argument, if it exists.

No argumentOwnership is obtained by calling the lock method on the associated mutex object.
AdoptOwnership is assumed. Mtx must be locked when the constructor is called.
DeferThe calling thread is assumed not to own the mutex object. Mtx must not be locked when the constructor is called.
TryOwnership is determined by calling try_lock on the associated mutex object. The constructor throws nothing.
Rel_timeOwnership is determined by calling try_lock_for(Rel_time).
Abs_timeOwnership is determined by calling try_lock_until(Abs_time).

Releases any resources that are associated with the unique_lock object.

~unique_lock() noexcept;

Remarks

If the calling thread owns the associated mutex, the destructor releases ownership by calling unlock on the mutex object.

Releases ownership of the associated mutex.

void unlock();

Remarks

If the calling thread doesn't own the associated mutex, this method throws a system_error that has an error code of operation_not_permitted.

Otherwise, this method calls unlock on the associated mutex and sets the internal thread ownership flag to false.

Header Files Reference
<mutex>

Show: