1//! A synchronization primitive enforcing atomic access to a shared region of
 2//! code known as the "critical section".
 3//!
 4//! Equivalent to `std.Mutex` except it allows the same thread to obtain the
 5//! lock multiple times.
 6//!
 7//! A recursive mutex is an abstraction layer on top of a regular mutex;
 8//! therefore it is recommended to use instead `std.Mutex` unless there is a
 9//! specific reason a recursive mutex is warranted.
10
11const std = @import("../../std.zig");
12const Recursive = @This();
13const Mutex = std.Thread.Mutex;
14const assert = std.debug.assert;
15
16mutex: Mutex,
17thread_id: std.Thread.Id,
18lock_count: usize,
19
20pub const init: Recursive = .{
21    .mutex = .{},
22    .thread_id = invalid_thread_id,
23    .lock_count = 0,
24};
25
26/// Acquires the `Mutex` without blocking the caller's thread.
27///
28/// Returns `false` if the calling thread would have to block to acquire it.
29///
30/// Otherwise, returns `true` and the caller should `unlock()` the Mutex to release it.
31pub fn tryLock(r: *Recursive) bool {
32    const current_thread_id = std.Thread.getCurrentId();
33    if (@atomicLoad(std.Thread.Id, &r.thread_id, .unordered) != current_thread_id) {
34        if (!r.mutex.tryLock()) return false;
35        assert(r.lock_count == 0);
36        @atomicStore(std.Thread.Id, &r.thread_id, current_thread_id, .unordered);
37    }
38    r.lock_count += 1;
39    return true;
40}
41
42/// Acquires the `Mutex`, blocking the current thread while the mutex is
43/// already held by another thread.
44///
45/// The `Mutex` can be held multiple times by the same thread.
46///
47/// Once acquired, call `unlock` on the `Mutex` to release it, regardless
48/// of whether the lock was already held by the same thread.
49pub fn lock(r: *Recursive) void {
50    const current_thread_id = std.Thread.getCurrentId();
51    if (@atomicLoad(std.Thread.Id, &r.thread_id, .unordered) != current_thread_id) {
52        r.mutex.lock();
53        assert(r.lock_count == 0);
54        @atomicStore(std.Thread.Id, &r.thread_id, current_thread_id, .unordered);
55    }
56    r.lock_count += 1;
57}
58
59/// Releases the `Mutex` which was previously acquired with `lock` or `tryLock`.
60///
61/// It is undefined behavior to unlock from a different thread that it was
62/// locked from.
63pub fn unlock(r: *Recursive) void {
64    r.lock_count -= 1;
65    if (r.lock_count == 0) {
66        @atomicStore(std.Thread.Id, &r.thread_id, invalid_thread_id, .unordered);
67        r.mutex.unlock();
68    }
69}
70
71/// A value that does not alias any other thread id.
72const invalid_thread_id: std.Thread.Id = std.math.maxInt(std.Thread.Id);