Edit

Share via

<mutex>

  • Article

Include the standard header <mutex> to define the classes mutex, recursive_mutex, timed_mutex, and recursive_timed_mutex; the templates lock_guard and unique_lock; and supporting types and functions that define mutual-exclusion code regions.

Warning

Beginning in Visual Studio 2015, the C++ Standard Library synchronization types are based on Windows synchronization primitives and no longer use ConcRT (except when the target platform is Windows XP). The types defined in <mutex> should not be used with any ConcRT types or functions.

Requirements

Header: <mutex>

Namespace: std

Remarks

Note

In code that is compiled by using /clr, this header is blocked.

The classes mutex and recursive_mutex are mutex types. A mutex type has a default constructor and a destructor that doesn't throw exceptions. These objects have methods that provide mutual exclusion when multiple threads try to lock the same object. Specifically, a mutex type contains the methods lock, try_lock, and unlock:

  • The lock method blocks the calling thread until the thread obtains ownership of the mutex. Its return value is ignored.

  • The try_lock method tries to obtain ownership of the mutex without blocking. Its return type is convertible to bool and is true if the method obtains ownership, but is otherwise false.

  • The unlock method releases the ownership of the mutex from the calling thread.

You can use mutex types as type arguments to instantiate the templates lock_guard and unique_lock. You can use objects of these types as the Lock argument to the wait member functions in the template condition_variable_any.

A timed mutex type satisfies the requirements for a mutex type. In addition, it has the try_lock_for and try_lock_until methods that must be callable by using one argument and must return a type that is convertible to bool. A timed mutex type can define these functions by using additional arguments, provided that those additional arguments all have default values.

  • The try_lock_for method must be callable by using one argument, Rel_time, whose type is an instantiation of chrono::duration. The method tries to obtain ownership of the mutex, but returns within the time that is designated by Rel_time, regardless of success. The return value converts to true if the method obtains ownership; otherwise, the return value converts to false.

  • The try_lock_until method must be callable by using one argument, Abs_time, whose type is an instantiation of chrono::time_point. The method tries to obtain ownership of the mutex, but returns no later than the time that is designated by Abs_time, regardless of success. The return value converts to true if the method obtains ownership; otherwise, the return value converts to false.

A mutex type is also known as a lockable type. If it doesn't provide the member function try_lock, it's a basic lockable type. A timed mutex type is known as a timed lockable type. A timed lockable type blocks for a specified amount of time, or until a lock on the mutex is acquired.

Members

Classes

Name Description
lock_guard Class Represents a template that can be instantiated to create an object whose destructor unlocks a mutex.
mutex Class (C++ Standard Library) Represents a mutex type. Use objects of this type to enforce mutual exclusion within a program.
recursive_mutex Class Represents a mutex type. In contrast to the mutex class, the behavior of calling locking methods for objects that are already locked is well-defined.
recursive_timed_mutex Class Use objects of this type to enforce mutual exclusion that has time-limited blocking within a program. Unlike timed_mutex, the effect of calling locking methods for recursive_timed_mutex objects is well-defined.
scoped_lock Class
timed_mutex Class Use objects of this type to enforce mutual exclusion that has time-limited blocking within a program.
unique_lock Class Represents a template that can be instantiated to create objects that manage the locking and unlocking of a mutex.

Functions

Name Description
call_once Provides a mechanism for calling a specified callable object exactly once during execution.
lock Attempts to lock all arguments without deadlock.
swap Tries to exchange the internal states of two mutex objects, x and y.
try_lock Tries to lock the lockable object. Returns immediately.

Structs

Name Description
adopt_lock_t Structure Represents a type that is used to define an adopt_lock.
defer_lock_t Structure Represents a type that defines a defer_lock object that is used to select one of the overloaded constructors of unique_lock.
once_flag Structure Represents a struct that is used with the template function call_once to ensure that initialization code is called only once, even in the presence of multiple threads of execution.
try_to_lock_t Structure Represents a struct that defines a try_to_lock object and is used to select one of the overloaded constructors of unique_lock.

Variables

Name Description
adopt_lock Represents an object that can be passed to constructors for lock_guard and unique_lock to indicate that the mutex object that is also being passed to the constructor is locked.
defer_lock Represents an object that can be passed to the constructor for unique_lock, to indicate that the constructor shouldn't lock the mutex object that is also being passed to it.
try_to_lock Represents an object that can be passed to the constructor for unique_lock to indicate that the constructor should try to unlock the mutex object that is also being passed to it without blocking.

See also

Header Files Reference