std::shared...try_lock_for(3)

💅 std::shared_timed_mutex::try_lock_for — a C++ Standard Library moment

okok so bestie, welcome to the std::shared_timed_mutex::try_lock_for page from the C++ Standard Library manual — yes that's the whole vibe, she's a member function and she's iconic. Let me walk you through it 🫶

---

✨ NAME ✨

std::shared_timed_mutex::try_lock_for — literally the same thing twice because that's her name and she's not apologizing 💅

---

🦋 Synopsis 🦋

so here's the signature, copy it exactly bestie, (since C++14):

template< class Rep, class Period >
bool try_lock_for( const std::chrono::duration<Rep, Period>& timeout_duration );

What she does: tries to lock the mutex. She blocks until either the specified duration timeout_duration has elapsed (that's the timeout, babes) or the lock is acquired (meaning she owns the mutex) — whichever comes first 🏁

On successful lock acquisition she returns true, otherwise false. Simple as that, no cap.

If timeout_duration is less than or equal to timeout_duration.zero(), the function behaves like try_lock() 😌

⚠️ Heads up: this function may block for longer than timeout_duration due to scheduling or resource contention delays. Not her fault, it's the scheduler's.

The standard recommends that a std::steady_clock is used to measure the duration. If an implementation uses a std::system_clock instead, the wait time may also be sensitive to clock adjustments — the way that a clock adjustment can just ruin your whole day 😭

As with try_lock(), this function is allowed to fail spuriously and return false even if the mutex was not locked by any other thread at some point during timeout_duration. Rude? kinda. Allowed? yes 💀

A prior unlock() operation on the same mutex synchronizes-with (as defined in std::memory_order) this operation if it returns true. memory ordering slay ✨

🚨 If try_lock_for is called by a thread that already owns the mutex in any mode (shared or exclusive), the behavior is undefined. Don't do it. Periodt.

---

🎀 Parameters 🎀

• timeout_duration — minimum duration to block for

---

👑 Return value 👑

true if the lock was acquired successfully, otherwise false. That's it, that's the whole personality 🍓

---

🌈 Exceptions 🌈

Any exception thrown by timeout_duration — but bestie, durations provided by the standard library never throw, so lowkey you're fine 🧚

---

💖 Example 💖

go ahead and run this code, it's giving main character energy:

#include <chrono>
#include <iostream>
#include <mutex>
#include <sstream>
#include <thread>
#include <vector>

using namespace std::chrono_literals;

std::mutex cout_mutex; // control access to std::cout
std::timed_mutex mutex;

void job(int id)
{
    std::ostringstream stream;

    for (int i = 0; i < 3; ++i)
    {
        if (mutex.try_lock_for(100ms))
        {
            stream << "success ";
            std::this_thread::sleep_for(100ms);
            mutex.unlock();
        }
        else
            stream << "failed ";

        std::this_thread::sleep_for(100ms);
    }

    std::lock_guard<std::mutex> lock{cout_mutex};
    std::cout << '[' << id << "] " << stream.str() << '\n';
}

int main()
{
    std::vector<std::thread> threads;
    for (int i{0}; i < 4; ++i)
        threads.emplace_back(job, i);

    for (auto& th : threads)
        th.join();
}

🌸 Possible output 🌸

(emphasis on possible, she's chaotic like that 🙈)

[0] failed failed failed
[3] failed failed success
[2] failed success failed
[1] success failed success

---

⭐ See also ⭐

• lock — locks the mutex, blocks if the mutex is not available (public member function)
• try_lock — tries to lock the mutex, returns if the mutex is not available (public member function)
• try_lock_until — tries to lock the mutex, returns if the mutex has been unavailable until specified time point has been reached (public member function)
• unlock — unlocks the mutex (public member function)

---

and that's the page bestie!! 🎀 this came to you straight from http://cppreference.com, dated 2024.06.10 — so if you're reading this on some other date, hi from the past, ily, go lock a mutex responsibly 🦋💜🔥