std::shared...:shared_lock(3)

💖 NAME 💖

std::shared_lock::shared_lock - std::shared_lock::shared_lock

okay so this is the std::shared...:shared_lock(3) page from the C++ Standard Libary manual — yes, that spelling is literally in the header and we are not fixing it, it’s part of the lore. We’re talking about the constructor for std::shared_lock, and bestie, we’re gonna build locks. 🎀

🦋 Synopsis 🦋

Here’s the whole overload lineup, copied exactly so nobody gets lost:

          shared_lock() noexcept;
       (1) (since C++14)
          shared_lock( shared_lock&& other ) noexcept;
       (2) (since C++14)
          explicit shared_lock( mutex_type& m );
       (3) (since C++14)
          shared_lock( mutex_type& m, std::defer_lock_t t ) noexcept;
       (4) (since C++14)
          shared_lock( mutex_type& m, std::try_to_lock_t t );
       (5) (since C++14)
          shared_lock( mutex_type& m, std::adopt_lock_t t );
       (6) (since C++14)
          template< class Rep, class Period >

          shared_lock( mutex_type& m,
       (7) (since C++14)

                       const std::chrono::duration<Rep,Period>&
          timeout_duration );
          template< class Clock, class Duration >

          shared_lock( mutex_type& m,
       (8) (since C++14)

                       const std::chrono::time_point<Clock,Duration>&
          timeout_time );

Constructs a shared_lock, optionally locking the supplied mutex. That’s the whole vibe. 💅

1. (1) — Constructs a shared_lock with no associated mutex.
2. (2) — Move constructor. Initializes the shared_lock with the contents of other. Leaves other with no associated mutex.

Overloads (3)–(8) construct a shared_lock with m as the associated mutex. Additionally:

3. (3) — Locks the associated mutex in shared mode by calling m.lock_shared().
4. (4) — Does not lock the associated mutex.
5. (5) — Tries to lock the associated mutex in shared mode without blocking by calling m.try_lock_shared().
6. (6) — Assumes the calling thread already holds a shared lock (i.e., a lock acquired by lock_shared, try_lock_shared, try_lock_shared_for, or try_lock_shared_until) on m. The behavior is undefined if not so.
7. (7) — Tries to lock the associated mutex in shared mode by calling m.try_lock_shared_for(timeout_duration), which blocks until specified timeout_duration has elapsed or the lock is acquired, whichever comes first. May block for longer than timeout_duration. The behavior is undefined if Mutex does not meet the SharedTimedLockable requirements.
8. (8) — Tries to lock the associated mutex in shared mode by calling m.try_lock_shared_until(timeout_time), which blocks until specified timeout_time has been reached or the lock is acquired, whichever comes first. May block for longer than until timeout_time has been reached. The behavior is undefined if Mutex does not meet the SharedTimedLockable requirements.

🚨 bestie, please clock the undefined behavior: overload (6) is UB if the thread isn’t already holding that shared lock, and (7)/8) are UB if Mutex doesn’t meet the SharedTimedLockable requirements. That is not a cute surprise. That is undefined behavior. 😭

🍓 Parameters 🍓

• other — another shared_lock to initialize the state with.
• m — mutex to associate with the lock and optionally acquire ownership of.
• t — tag parameter used to select constructors with different locking strategies.
• timeout_duration — maximum duration to block for.
• timeout_time — maximum time point to block until.

🌈 Example 🌈

Run this code, bestie:

// Run this code

#include <chrono>
#include <iostream>
#include <shared_mutex>
#include <syncstream>
#include <thread>

std::shared_timed_mutex m;
int i = 10;

void read_shared_var(int id)
{
     // both the threads get access to the integer i
     std::shared_lock<std::shared_timed_mutex> slk(m);
     const int ii = i; // reads global i

     std::osyncstream(std::cout) << '#' << id << " read i as " << ii << "...\n";
     std::this_thread::sleep_for(std::chrono::milliseconds(10));
     std::osyncstream(std::cout) << '#' << id << " woke up..." << std::endl;
}

int main()
{
     std::thread r1{read_shared_var, 1};
     std::thread r2{read_shared_var, 2};

     r1.join();
     r2.join();
}

💀 Possible output 💀

#2 read i as 10...
#1 read i as 10...
#2 woke up...
#1 woke up...

source/version: http://cppreference.com · date: 2024.06.10 · page: std::shared...:shared_lock(3) — byeee, go lock something shared, bestie 💖✨🫶