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

Latest revision as of 07:00, 6 July 2023

Defined in header `<mutex>`
template< class Mutex > class lock_guard;		(since C++11)

The class lock_guard is a mutex wrapper that provides a convenient RAII-style mechanism for owning a mutex for the duration of a scoped block.

When a lock_guard object is created, it attempts to take ownership of the mutex it is given. When control leaves the scope in which the lock_guard object was created, the lock_guard is destructed and the mutex is released.

The lock_guard class is non-copyable.

A common beginner error is to "forget" to give a lock_guard variable a name, e.g. std::lock_guard(mtx); (which default constructs a lock_guard variable named mtx) or std::lock_guard{mtx}; (which constructs a prvalue object that is immediately destroyed), thereby not actually constructing a lock that holds a mutex for the rest of the scope.

std::scoped_lock offers an alternative for lock_guard that provides the ability to lock multiple mutexes using a deadlock avoidance algorithm.

(since C++17)

[edit] Example

Demonstrates safe and unsafe increments of a volatile variable by two threads.

Run this code

#include <iostream>
#include <mutex>
#include <string_view>
#include <syncstream>
#include <thread>
 
volatile int g_i = 0;
std::mutex g_i_mutex;  // protects g_i
 
void safe_increment(int iterations)
{
    const std::lock_guard<std::mutex> lock(g_i_mutex);
    while (iterations-- > 0)
        g_i = g_i + 1;
    std::cout << "thread #" << std::this_thread::get_id() << ", g_i: " << g_i << '\n';
 
    // g_i_mutex is automatically released when lock goes out of scope
}
 
void unsafe_increment(int iterations)
{
    while (iterations-- > 0)
        g_i = g_i + 1;
    std::osyncstream(std::cout) << "thread #" << std::this_thread::get_id()
                                << ", g_i: " << g_i << '\n';
}
 
int main()
{
    auto test = [](std::string_view fun_name, auto fun)
    {
        g_i = 0;
        std::cout << fun_name << ":\nbefore, g_i: " << g_i << '\n';
        {
            std::jthread t1(fun, 1'000'000);
            std::jthread t2(fun, 1'000'000);
        }
        std::cout << "after, g_i: " << g_i << "\n\n";
    };
    test("safe_increment", safe_increment);
    test("unsafe_increment", unsafe_increment);
}

Possible output:

safe_increment:
before, g_i: 0
thread #140121493231360, g_i: 1000000
thread #140121484838656, g_i: 2000000
after, g_i: 2000000
 
unsafe_increment:
before, g_i: 0
thread #140121484838656, g_i: 1028945
thread #140121493231360, g_i: 1034337
after, g_i: 1034337

[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 `lock_guard<Mutex>` was provided	removed

[edit] See also

unique_lock (C++11)	implements movable mutex ownership wrapper (class template) [edit]
scoped_lock (C++17)	deadlock-avoiding RAII wrapper for multiple mutexes (class template) [edit]

@@ Line 1: / Line 1: @@
 {{cpp/title|lock_guard}}
-{{cpp/thread/lock_guard/sidebar}}
+{{cpp/thread/lock_guard/navbar}}
-{{ddcl | header=mutex | notes={{mark since c++11}} | 1=
+{{ddcl|header=mutex|since=c++11|1=
 template< class Mutex >
 class lock_guard;
 }}
-The class {{c|lock_guard}} implements a strictly scope-based mutex ownership wrapper. The class is non-copyable.
+The class {{tt|lock_guard}} is a mutex wrapper that provides a convenient [[cpp/language/raii|RAII-style]] mechanism for owning a mutex for the duration of a scoped block.
-The supplied Mutex type shall implement the Lockable concept.
-{{todo}}
+When a {{tt|lock_guard}} object is created, it attempts to take ownership of the mutex it is given. When control leaves the scope in which the {{tt|lock_guard}} object was created, the {{tt|lock_guard}} is destructed and the mutex is released.
+The {{tt|lock_guard}} class is non-copyable.
+===Template parameters===
+{{par begin}}
+{{par|Mutex|the type of the mutex to lock. The type must meet the {{named req|BasicLockable}} requirements}}
+{{par end}}
 ===Member types===
-{{tdcl list begin}}
+{{dsc begin}}
-{{tdcl list hitem | Member type | Definition}}
+{{dsc hitem|Member type|Definition}}
-{{tdcl list item | {{tt|mutex_type}} | Mutex}}
+{{dsc|{{tt|mutex_type}}|Mutex}}
-{{tdcl list end}}
+{{dsc end}}
 ===Member functions===
-{{dcl list begin}}
+{{dsc begin}}
-{{dcl list template | cpp/thread/lock_guard/dcl list constructor | Locks the supplied mutex}}
+{{dsc inc|cpp/thread/lock_guard/dsc constructor}}
-{{dcl list template | cpp/thread/lock_guard/dcl list destructor | Unlocks the supplied mutex}}
+{{dsc inc|cpp/thread/lock_guard/dsc destructor}}
-{{tdcl list end}}
+{{dsc inc|cpp/thread/lock_guard/dsc operator{{=}}}}
+{{dsc end}}
+===Notes===
+A common beginner error is to "forget" to give a {{tt|lock_guard}} variable a name, e.g. {{c|std::lock_guard(mtx);}} (which default constructs a {{tt|lock_guard}} variable named {{tt|mtx}}) or {{c|std::lock_guard{mtx};}} (which constructs a prvalue object that is immediately destroyed), thereby not actually constructing a lock that holds a mutex for the rest of the scope.
+{{rrev|since=c++17|
+{{ltt|cpp/thread/scoped_lock|std::scoped_lock}} offers an alternative for {{tt|lock_guard}} that provides the ability to lock multiple mutexes using a deadlock avoidance algorithm.
+}}
 ===Example===
-{{example|
+{{example
- | code=std::mutex m;
+|Demonstrates safe and unsafe increments of a volatile variable by two threads.
+|code=
+#include <iostream>
+#include <mutex>
+#include <string_view>
+#include <syncstream>
+#include <thread>
-void do_something()
+volatile int g_i = 0;
+std::mutex g_i_mutex;  // protects g_i
+void safe_increment(int iterations)
 {
-     std::lock_guard<std::mutex> lock(m);
+     const std::lock_guard<std::mutex> lock(g_i_mutex);
-     // the remaining function is thread-safe now
+    while (iterations-- > 0)
+        g_i = g_i + 1;
+    std::cout << "thread #" << std::this_thread::get_id() << ", g_i: " << g_i << '\n';
+     // g_i_mutex is automatically released when lock goes out of scope
 }
- | output=
+void unsafe_increment(int iterations)
+{
+    while (iterations-- > 0)
+        g_i = g_i + 1;
+    std::osyncstream(std::cout) << "thread #" << std::this_thread::get_id()
+                                << ", g_i: " << g_i << '\n';
+}
+int main()
+{
+    auto test = [](std::string_view fun_name, auto fun)
+    {
+        g_i = 0;
+        std::cout << fun_name << ":\nbefore, g_i: " << g_i << '\n';
+        {
+            std::jthread t1(fun, 1'000'000);
+            std::jthread t2(fun, 1'000'000);
+        }
+        std::cout << "after, g_i: " << g_i << "\n\n";
+    };
+    test("safe_increment", safe_increment);
+    test("unsafe_increment", unsafe_increment);
+}
+|p=true
+|output=
+safe_increment:
+before, g_i: 0
+thread #140121493231360, g_i: 1000000
+thread #140121484838656, g_i: 2000000
+after, g_i: 2000000
+unsafe_increment:
+before, g_i: 0
+thread #140121484838656, g_i: 1028945
+thread #140121493231360, g_i: 1034337
+after, g_i: 1034337
 }}
+===Defect reports===
+{{dr list begin}}
+{{dr list item|wg=lwg|dr=2981|std=C++17|before=redundant deduction guide from {{tt|lock_guard<Mutex>}} was provided|after=removed}}
+{{dr list end}}
+===See also===
+{{dsc begin}}
+{{dsc inc|cpp/thread/dsc unique_lock}}
+{{dsc inc|cpp/thread/dsc scoped_lock}}
+{{dsc end}}
+{{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

Member type	Definition
`mutex_type`	Mutex

(constructor)	constructs a `lock_guard`, optionally locking the given mutex (public member function) [edit]
(destructor)	destructs the `lock_guard` object, unlocks the underlying mutex (public member function) [edit]
operator= [deleted]	not copy-assignable (public member function) [edit]

cppreference.com

Namespaces

Variants

Views

Actions

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

Latest revision as of 07:00, 6 July 2023

Contents

[edit] Template parameters

[edit] Member types

[edit] Member functions

[edit] Notes

[edit] Example

[edit] Defect reports

[edit] See also

Navigation

Toolbox