Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/thread/unique lock"

From cppreference.com
< cpp‎ | thread
(→‎Member functions: namespaces)
(c -> tt.)
 
(45 intermediate revisions by 15 users not shown)
Line 1: Line 1:
 
{{cpp/title|unique_lock}}
 
{{cpp/title|unique_lock}}
−
{{cpp/thread/unique_lock/sidebar}}
+
{{cpp/thread/unique_lock/navbar}}
−
{{ddcl | header=mutex | notes={{mark c++11 feature}} | 1=
+
{{ddcl|header=mutex|since=c++11|1=
−
template<typename Mutex>
+
template< class Mutex >
 
class unique_lock;
 
class unique_lock;
 
}}
 
}}
  
−
The class {{cpp|unique_lock}} implements general-purpose mutex ownership wrapper allowing deferred locking, timed locking, recursive locking, transfer of lock ownership, and use with condition variables. The class is non-copyable but movable.
+
The class {{tt|unique_lock}} is a general-purpose mutex ownership wrapper allowing deferred locking, time-constrained attempts at locking, recursive locking, transfer of lock ownership, and use with condition variables.  
  
−
===Member types===
+
The class {{tt|unique_lock}} is movable, but not copyable -- it meets the requirements of {{named req|MoveConstructible}} and {{named req|MoveAssignable}} but not of {{named req|CopyConstructible}} or {{named req|CopyAssignable}}.
−
{{tdcl list begin}}
+
 
−
{{tdcl list hitem | Member type | Definition}}
+
The class {{tt|unique_lock}} meets the {{named req|BasicLockable}} requirements. If {{tt|Mutex}} meets the {{named req|Lockable}} requirements, {{tt|unique_lock}} also meets the {{named req|Lockable}} requirements (ex.: can be used in {{lc|std::lock}}); if {{tt|Mutex}} meets the {{named req|TimedLockable}} requirements, {{tt|unique_lock}} also meets the {{named req|TimedLockable}} requirements.
−
{{tdcl list item | {{tt|mutex_type}} | Mutex}}
+
 
−
{{tdcl list end}}
+
===Template parameters===
 +
{{par begin}}
 +
{{par|Mutex|the type of the mutex to lock. The type must meet the {{named req|BasicLockable}} requirements}}
 +
{{par end}}
 +
 
 +
===Nested types===
 +
{{dsc begin}}
 +
{{dsc hitem|Type|Definition}}
 +
{{dsc|{{tt|mutex_type}}|{{tt|Mutex}}}}
 +
{{dsc end}}
  
 
===Member functions===
 
===Member functions===
−
{{dcl list begin}}
+
{{dsc begin}}
−
{{dcl list mem ctor | cpp/thread/unique_lock/unique_lock | Constructs a unique_lock, optionally locking the supplied mutex }}
+
{{dsc inc|cpp/thread/unique_lock/dsc constructor}}
−
{{dcl list mem dtor | cpp/thread/unique_lock/~unique_lock | Unlocks the supplied mutex, if owned}}
+
{{dsc inc|cpp/thread/unique_lock/dsc destructor}}
−
{{dcl list mem fun | cpp/thread/unique_lock/operator{{=}} | Unlocks the mutex, if owned, and acquires ownership of another }}
+
{{dsc inc|cpp/thread/unique_lock/dsc operator{{=}}}}
−
{{dcl list mem fun | cpp/thread/unique_lock/lock | Locks the supplied mutex}}
+
−
{{dcl list mem fun | cpp/thread/unique_lock/try_lock | Attempts to lock the supplied mutex}}
+
−
{{dcl list mem fun | cpp/thread/unique_lock/try_lock_for | Attempts to lock the supplied TimedLockable mutex for specified {{cpp|std::chrono::duration}}}}
+
−
{{dcl list mem fun | cpp/thread/unique_lock/try_lock_until | Attempts to lock the supplied TimedLockable mutex until specified {{cpp|std::chrono::time_point}}}}
+
−
{{dcl list mem fun | cpp/thread/unique_lock/unlock | Unlocks the supplied mutex }}
+
−
{{dcl list mem fun | cpp/thread/unique_lock/swap | Swaps state with another {{cpp|std::unique_lock}}}}
+
−
{{dcl list mem fun | cpp/thread/unique_lock/mutex | Returns a pointer to the supplied mutex}}
+
−
{{dcl list mem fun | cpp/thread/unique_lock/release | Unlocks the mutex and returns a pointer to the mutex object}}
+
−
{{dcl list mem fun | cpp/thread/unique_lock/owns_lock | Tests if this unique_lock owns its mutex }}
+
−
{{dcl list mem fun | cpp/thread/unique_lock/operator bool() | Tests if this unique_lock owns its mutex}}
+
−
{{dcl list end}}
+
  
−
===Helper classes===
+
{{dsc h2|Locking}}
−
{{dcl list begin}}
+
{{dsc inc|cpp/thread/unique_lock/dsc lock}}
−
{{dcl list class | cpp/thread/unique_lock/defer_lock_t | tag type used to disambiguate unique_lock constructors}}
+
{{dsc inc|cpp/thread/unique_lock/dsc try_lock}}
−
{{dcl list class | cpp/thread/unique_lock/try_to_lock_t | tag type used to disambiguate unique_lock constructors}}
+
{{dsc inc|cpp/thread/unique_lock/dsc try_lock_for}}
−
{{dcl list class | cpp/thread/unique_lock/adopt_lock_t | tag type used to disambiguate unique_lock constructors}}
+
{{dsc inc|cpp/thread/unique_lock/dsc try_lock_until}}
−
{{dcl list end}}
+
{{dsc inc|cpp/thread/unique_lock/dsc unlock}}
  
−
===Non-member constants===
+
{{dsc h2|Modifiers}}
−
{{dcl list begin}}
+
{{dsc inc|cpp/thread/unique_lock/dsc swap}}
−
{{dcl list const | cpp/thread/unique_lock/defer_lock | tag constant used to disambiguate unique_lock constructors}}
+
{{dsc inc|cpp/thread/unique_lock/dsc release}}
−
{{dcl list const | cpp/thread/unique_lock/try_to_lock | tag constant used to disambiguate unique_lock constructors}}
+
 
−
{{dcl list const | cpp/thread/unique_lock/adopt_lock | tag constant used to disambiguate unique_lock constructors}}
+
{{dsc h2|Observers}}
−
{{dcl list end}}
+
{{dsc inc|cpp/thread/unique_lock/dsc mutex}}
 +
{{dsc inc|cpp/thread/unique_lock/dsc owns_lock}}
 +
{{dsc inc|cpp/thread/unique_lock/dsc operator bool}}
 +
{{dsc end}}
  
 
===Non-member functions===
 
===Non-member functions===
−
{{dcl list begin}}
+
{{dsc begin}}
−
{{dcl list tfun | cpp/thread/unique_lock/swap2 | title=std::swap{{dcl small|(std::unique_lock)}} | Specialization of std::swap for unique_locks}}
+
{{dsc inc|cpp/thread/unique_lock/dsc swap2}}
−
{{dcl list end}}
+
{{dsc end}}
  
 
===Example===
 
===Example===
−
{{example cpp
+
{{example
−
|
+
|code=
−
| code=
+
#include <iostream>
−
| output=
+
#include <mutex>
 +
#include <thread>
 +
 
 +
struct Box
 +
{
 +
    explicit Box(int num) : num_things{num} {}
 +
   
 +
    int num_things;
 +
    std::mutex m;
 +
};
 +
 
 +
void transfer(Box& from, Box& to, int num)
 +
{
 +
    // don't actually take the locks yet
 +
    std::unique_lock lock1{from.m, std::defer_lock};
 +
    std::unique_lock lock2{to.m, std::defer_lock};
 +
   
 +
    // lock both unique_locks without deadlock
 +
    std::lock(lock1, lock2);
 +
   
 +
    from.num_things -= num;
 +
    to.num_things += num;
 +
   
 +
    // “from.m” and “to.m” mutexes unlocked in unique_lock dtors
 +
}
 +
 
 +
int main()
 +
{
 +
    Box acc1{100};
 +
    Box acc2{50};
 +
   
 +
    std::thread t1{transfer, std::ref(acc1), std::ref(acc2), 10};
 +
    std::thread t2{transfer, std::ref(acc2), std::ref(acc1), 5};
 +
   
 +
    t1.join();
 +
    t2.join();
 +
   
 +
    std::cout << "acc1: " << acc1.num_things << "\n"
 +
                "acc2: " << acc2.num_things << '\n';
 +
}
 +
|output=
 +
acc1: 95
 +
acc2: 55
 
}}
 
}}
 +
 +
===Defect reports===
 +
{{dr list begin}}
 +
{{dr list item|wg=lwg|dr=2981|std=C++17|before=redundant deduction guide from {{tt|unique_lock<Mutex>}} was provided|after=removed}}
 +
{{dr list end}}
 +
 +
===See also===
 +
{{dsc begin}}
 +
{{dsc inc|cpp/thread/dsc lock}}
 +
{{dsc inc|cpp/thread/dsc lock_guard}}
 +
{{dsc inc|cpp/thread/dsc scoped_lock}}
 +
{{dsc inc|cpp/thread/dsc mutex}}
 +
{{dsc end}}
 +
 +
{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Latest revision as of 23:31, 27 February 2024

 
C++
 
Concurrency support library
Threads
(C++11)
(C++20)
(C++17)(C++17)
this_thread namespace
(C++11)
(C++11)
(C++11)
(C++11)
Cooperative cancellation
Mutual exclusion
(C++11)
(C++11)
(C++17)
Generic lock management
(C++11)
(C++11)
(C++17)
unique_lock
(C++11)
(C++14)
(C++11)
(C++11)
(C++11)
(C++11)(C++11)(C++11)(C++11)(C++11)(C++11)
Condition variables
(C++11)
(C++11)
(C++11)
(C++11)
Semaphores
(C++20)(C++20)
Latches and Barriers
(C++20)
(C++20)
Futures
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
(C++11)
Safe Reclamation
(C++26)
(C++26)
(C++26)
Hazard Pointers
(C++26)
(C++26)
(C++26)
Atomic types
(C++11)
(C++20)
(C++11)
Initialization of atomic types
(C++11)(deprecated in C++20)
(C++11)(deprecated in C++20)
(C++11)
Memory ordering
(C++11)
(C++11)
(C++11)
(C++11)
Free functions for atomic operations
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)
(C++26)(C++26)
(C++26)(C++26)
(C++11)
(C++20)(C++20)
(C++20)
(C++20)
Free functions for atomic flags
(C++11)(C++11)
(C++11)(C++11)
(C++20)(C++20)
(C++20)(C++20)
(C++20)
(C++20)
 
std::unique_lock
 
Defined in header <mutex>
template< class Mutex >
class unique_lock;
 (since C++11)

The class unique_lock is a general-purpose mutex ownership wrapper allowing deferred locking, time-constrained attempts at locking, recursive locking, transfer of lock ownership, and use with condition variables.

The class unique_lock is movable, but not copyable -- it meets the requirements of MoveConstructible and MoveAssignable but not of CopyConstructible or CopyAssignable.

The class unique_lock meets the BasicLockable requirements. If Mutex meets the Lockable requirements, unique_lock also meets the Lockable requirements (ex.: can be used in std::lock); if Mutex meets the TimedLockable requirements, unique_lock also meets the TimedLockable requirements.

Contents

[edit] Template parameters

Mutex - the type of the mutex to lock. The type must meet the BasicLockable requirements

[edit] Nested types

Type Definition
mutex_type Mutex

[edit] Member functions

 constructs a unique_lock, optionally locking (i.e., taking ownership of) the supplied mutex
(public member function) [edit]
unlocks (i.e., releases ownership of) the associated mutex, if owned
(public member function) [edit]
unlocks (i.e., releases ownership of) the mutex, if owned, and acquires ownership of another
(public member function) [edit]
Locking
locks (i.e., takes ownership of) the associated mutex
(public member function) [edit]
tries to lock (i.e., takes ownership of) the associated mutex without blocking
(public member function) [edit]
attempts to lock (i.e., takes ownership of) the associated TimedLockable mutex, returns if the mutex has been unavailable for the specified time duration
(public member function) [edit]
tries to lock (i.e., takes ownership of) the associated TimedLockable mutex, returns if the mutex has been unavailable until specified time point has been reached
(public member function) [edit]
unlocks (i.e., releases ownership of) the associated mutex
(public member function) [edit]
Modifiers
swaps state with another std::unique_lock
(public member function) [edit]
disassociates the associated mutex without unlocking (i.e., releasing ownership of) it
(public member function) [edit]
Observers
returns a pointer to the associated mutex
(public member function) [edit]
tests whether the lock owns (i.e., has locked) its associated mutex
(public member function) [edit]
tests whether the lock owns (i.e., has locked) its associated mutex
(public member function) [edit]

[edit] Non-member functions

(C++11)
 specializes the std::swap algorithm
(function template) [edit]

[edit] Example

Run this code
#include <iostream>
#include <mutex>
#include <thread>
 
struct Box
{
    explicit Box(int num) : num_things{num} {}
 
    int num_things;
    std::mutex m;
};
 
void transfer(Box& from, Box& to, int num)
{
    // don't actually take the locks yet
    std::unique_lock lock1{from.m, std::defer_lock};
    std::unique_lock lock2{to.m, std::defer_lock};
 
    // lock both unique_locks without deadlock
    std::lock(lock1, lock2);
 
    from.num_things -= num;
    to.num_things += num;
 
    // “from.m” and “to.m” mutexes unlocked in unique_lock dtors
}
 
int main()
{
    Box acc1{100};
    Box acc2{50};
 
    std::thread t1{transfer, std::ref(acc1), std::ref(acc2), 10};
    std::thread t2{transfer, std::ref(acc2), std::ref(acc1), 5};
 
    t1.join();
    t2.join();
 
    std::cout << "acc1: " << acc1.num_things << "\n"
                 "acc2: " << acc2.num_things << '\n';
}

Output: 

acc1: 95
acc2: 55

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR Applied to Behavior as published Correct behavior
LWG 2981 C++17 redundant deduction guide from unique_lock<Mutex> was provided removed

[edit] See also

(C++11)
 locks specified mutexes, blocks if any are unavailable
(function template) [edit]
(C++11)
 implements a strictly scope-based mutex ownership wrapper
(class template) [edit]
(C++17)
 deadlock-avoiding RAII wrapper for multiple mutexes
(class template) [edit]
(C++11)
 provides basic mutual exclusion facility
(class) [edit]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/thread/unique_lock&oldid=169985"