102 lines · plain
1.. title:: clang-tidy - modernize-use-scoped-lock2 3modernize-use-scoped-lock4=========================5 6Finds uses of ``std::lock_guard`` and suggests replacing them with C++17's7alternative ``std::scoped_lock``.8 9Fix-its are provided for single declarations of ``std::lock_guard`` and warning10is emitted for multiple declarations of ``std::lock_guard`` that can be11replaced with a single declaration of ``std::scoped_lock``.12 13Examples14--------15 16Single ``std::lock_guard`` declaration:17 18.. code-block:: c++19 20 std::mutex M;21 std::lock_guard<std::mutex> L(M);22 23 24Transforms to:25 26.. code-block:: c++27 28 std::mutex M;29 std::scoped_lock L(M);30 31Single ``std::lock_guard`` declaration with ``std::adopt_lock``:32 33.. code-block:: c++34 35 std::mutex M;36 std::lock(M);37 std::lock_guard<std::mutex> L(M, std::adopt_lock);38 39 40Transforms to:41 42.. code-block:: c++43 44 std::mutex M;45 std::lock(M);46 std::scoped_lock L(std::adopt_lock, M);47 48Multiple ``std::lock_guard`` declarations only emit warnings:49 50.. code-block:: c++51 52 std::mutex M1, M2;53 std::lock(M1, M2);54 std::lock_guard Lock1(M1, std::adopt_lock); // warning: use single 'std::scoped_lock' instead of multiple 'std::lock_guard'55 std::lock_guard Lock2(M2, std::adopt_lock); // note: additional 'std::lock_guard' declared here56 57 58Limitations59-----------60 61The check will not emit warnings if ``std::lock_guard`` is used implicitly via62``template`` parameter:63 64.. code-block:: c++65 66 template <template <typename> typename Lock>67 void TemplatedLock() {68 std::mutex M;69 Lock<std::mutex> L(M); // no warning70 }71 72 void instantiate() {73 TemplatedLock<std::lock_guard>();74 }75 76 77Options78-------79 80.. option:: WarnOnSingleLocks81 82 When `true`, the check will warn on single ``std::lock_guard`` declarations.83 Set this option to `false` if you want to get warnings only on multiple84 ``std::lock_guard`` declarations that can be replaced with a single85 ``std::scoped_lock``. Default is `true`.86 87.. option:: WarnOnUsingAndTypedef88 89 When `true`, the check will emit warnings if ``std::lock_guard`` is used90 in ``using`` or ``typedef`` context. Default is `true`.91 92 .. code-block:: c++93 94 template <typename T>95 using Lock = std::lock_guard<T>; // warning: use 'std::scoped_lock' instead of 'std::lock_guard'96 97 using LockMutex = std::lock_guard<std::mutex>; // warning: use 'std::scoped_lock' instead of 'std::lock_guard'98 99 typedef std::lock_guard<std::mutex> LockDef; // warning: use 'std::scoped_lock' instead of 'std::lock_guard'100 101 using std::lock_guard; // warning: use 'std::scoped_lock' instead of 'std::lock_guard'102