# std::shared_mutex::lock_shared

> C++ Atlas: `cppatlas.com/w/cpp/thread/shared_mutex/lock_shared` | Source: https://en.cppreference.com/w/cpp/thread/shared_mutex/lock_shared | Domain: Concurrency support | Standards: C++17

Acquires shared ownership of the mutex. If another thread is holding the mutex in exclusive ownership, a call to lock_shared will block execution until shared ownership can be acquired.

## Official Specification Summary (cppreference)

```cpp
void lock_shared(); // (since C++17)
```

Acquires shared ownership of the mutex. If another thread is holding the mutex in exclusive ownership, a call to `lock_shared` will block execution until shared ownership can be acquired.

If `lock_shared` is called by a thread that already owns the `mutex` in any mode (exclusive or shared), the behavior is undefined.

If more than the implementation-defined maximum number of shared owners already locked the mutex in shared mode, `lock_shared` blocks execution until the number of shared owners is reduced. The maximum number of owners is guaranteed to be at least 10000.

A prior `unlock()` operation on the same mutex *synchronizes-with* (as defined in `std::memory_order`) this operation.

### Parameters

(none)

### Return value

(none)

### Exceptions

Throws `std::system_error` when errors occur, including errors from the underlying operating system that would prevent `lock` from meeting its specifications. The mutex is not locked in the case of any exception being thrown.

### Notes

`lock_shared()` is usually not called directly: `std::shared_lock` is used to manage shared locking.

### Example

```cpp
#include <chrono>
#include <iostream>
#include <mutex>
#include <shared_mutex>
#include <syncstream>
#include <thread>
#include <vector>

std::mutex stream_mutx;
void print(auto v)
{
    std::unique_lock<std::mutex> lock(stream_mutx);
    std::cout << std::this_thread::get_id() << " saw: ";
    for (auto e : v)
        std::cout << e << ' ';
    std::cout << '\n';
}

int main()
{
    using namespace std::chrono_literals;
    constexpr int N_READERS = 5;
    constexpr int LAST = -999;

    std::shared_mutex smtx;
    int product = 0;

    auto writer = [&smtx, &product](int start, int end)
    {
        for (int i = start; i < end; ++i)
        {
            auto data = i;
            {
                std::unique_lock<std::shared_mutex> lock(smtx);
                product = data;
            }
            std::this_thread::sleep_for(3ms);
        }

        smtx.lock(); // lock manually
        product = LAST;
        smtx.unlock();
    };

    auto reader = [&smtx, &product]()
    {
        int data = 0;
        std::vector<int> seen;
        do
        {
            {
                smtx.lock_shared(); // better to use: std::shared_lock lock(smtx);
                data = product;
                smtx.unlock_shared();
            }

            seen.push_back(data);
            std::this_thread::sleep_for(2ms);
        }
        while (data != LAST);

        print(seen);
    };

    std::vector<std::thread> threads;
    threads.emplace_back(writer, 1, 13);
    threads.emplace_back(writer, 42, 52);

    for (int i = 0; i < N_READERS; ++i)
        threads.emplace_back(reader);

    for (auto&& t : threads)
        t.join();
}
```

Possible output:

```text
127755840 saw: 43 3 3 4 46 5 6 7 7 8 9 51 10 11 11 12 -999
144541248 saw: 2 44 3 4 46 5 6 7 7 8 9 51 10 11 11 12 -999
110970432 saw: 42 2 3 45 4 5 47 6 7 8 8 9 10 11 11 12 -999
119363136 saw: 42 2 3 4 46 5 6 7 7 8 9 9 10 11 11 12 12 -999
136148544 saw: 2 44 3 4 46 5 6 48 7 8 9 51 10 11 11 12 12 -999
```

### See also

- [`lock`](https://en.cppreference.com/w/cpp/thread/shared_mutex/lock): locks the mutex, blocks if the mutex is not available (public member function)
- [`try_lock_shared`](https://en.cppreference.com/w/cpp/thread/shared_mutex/try_lock_shared): tries to lock the mutex for shared ownership, returns if the mutex is not available (public member function)
- [`unlock_shared`](https://en.cppreference.com/w/cpp/thread/shared_mutex/unlock_shared): unlocks the mutex (shared ownership) (public member function)

---
Attribution: content from https://en.cppreference.com/w/cpp/thread/shared_mutex/lock_shared (cppreference.com), licensed under CC-BY-SA 3.0 and GFDL. Modified: converted to markdown, study notes added. Offline snapshot of 9 February 2025.