std::defer_...dopt_lock_t(3)

💖 NAME 💖

okay bestie, this is the std::defer_...dopt_lock_t(3) page from the C++ Standard Libary manual, and it's literally about std::defer_lock_t, std::try_to_lock_t, and std::adopt_lock_t — the original NAME line is std::defer_lock_t,std::try_to_lock_t,std::adopt_lock_t, and yes, all three are the main characters here 💅✨

✨ Synopsis ✨

Defined in header <mutex>

struct defer_lock_t { explicit defer_lock_t() = default; };

struct try_to_lock_t { explicit try_to_lock_t() = default; };  (since C++11)

struct adopt_lock_t { explicit adopt_lock_t() = default; };

std::defer_lock_t, std::try_to_lock_t, and std::adopt_lock_t are empty class tag types used to specify locking strategy for std::unique_lock and std::shared_lock. no cap, that's their whole job 🫶

Here's the type / effect(s) vibe check:

• defer_lock_t — do not acquire ownership of the mutex
• try_to_lock_t — try to acquire ownership of the mutex without blocking
• adopt_lock_t — assume the calling thread already has ownership of the mutex

🎀 Example 🎀

// Run this code — literally go run it, bestie 😭

        #include <iostream>
        #include <mutex>
        #include <thread>

        struct bank_account
        {
            explicit bank_account(int balance) : balance{balance} {}
            int balance;
            std::mutex m;
        };

        void transfer(bank_account& from, bank_account& to, int amount)
        {
            if (&from == &to) // avoid deadlock in case of self transfer
                return;

            // lock both mutexes without deadlock
            std::lock(from.m, to.m);
            // make sure both already-locked mutexes are unlocked at the end of
       scope
            std::lock_guard lock1{from.m, std::adopt_lock};
            std::lock_guard lock2{to.m, std::adopt_lock};

        // equivalent approach:
        //  std::unique_lock<std::mutex> lock1{from.m, std::defer_lock};
        //  std::unique_lock<std::mutex> lock2{to.m, std::defer_lock};
        //  std::lock(lock1, lock2);

            from.balance -= amount;
            to.balance += amount;
        }

        int main()
        {
            bank_account my_account{100};
            bank_account your_account{50};

            std::thread t1{transfer, std::ref(my_account),
       std::ref(your_account), 10};
            std::thread t2{transfer, std::ref(your_account),
       std::ref(my_account), 5};

            t1.join();
            t2.join();

            std::cout << "my_account.balance = " << my_account.balance << "\n"
                         "your_account.balance = " << your_account.balance <<
       '\n';
        }

Output:

        my_account.balance = 95
        your_account.balance = 55

🌸 Defect reports 🌸

The following behavior-changing defect reports were applied retroactively to previously published C++ standards. iykyk, retroactive lore ✨

• DR LWG 2510; applied to C++11; behavior as published: the default constructors were non-explicit, which could lead to ambiguity; correct behavior: made explicit.

🦋 See also 🦋

• defer_lock, try_to_lock, adopt_lock — tag constants used to specify locking strategy; (constant); (C++11) (C++11) (C++11)
• constructor — constructs a lock_guard, optionally locking the given mutex; public member function of std::lock_guard<Mutex>
• constructor — constructs a unique_lock, optionally locking (i.e., taking ownership of) the supplied mutex; public member function of std::unique_lock<Mutex>

okay that's the whole page 💖 source: http://cppreference.com; version/date: 2024.06.10; manual page: std::defer_...dopt_lock_t(3). byeee, go lock safely 🫶👑