Reader-writer lock

[matthew-mcallister]

Pull Request check-list

Please make sure to review and check all of these items:

• Do tests and lints pass with this change?
• Do the CI tests pass with this change (enable it first in your forked repo and wait for the github action build to finish)?
• Is the new or changed code fully tested?
• Is a documentation update included (if this change modifies existing APIs, or introduces new ones)?
• Is there an example added to the examples folder (if applicable)?

NOTE: these things are not required to open a PR and can be done
afterwards / while the PR is open.

Description of change

This implements the reader-write lock requested in #2372. It is a pretty sizeable standalone feature that may take a while to review.

The interface and implementation I think are explained decently well in docstrings and comments. Briefly: the lock state is stored in three keys:

1. <prefix>:write: Standard mutex lease
2. <prefix>:write_semaphore: Semaphore that tracks waiting writers, implemented as an ordered set.
3. <prefix>:read: Semaphore that tracks readers.

I tried to keep the interface (and implementation) similar to the existing Lock class while taking inspiration from the Rust and C++ standard libraries for the new bits. I got rid of thread-local state since each read/write guard now generates its own token.

Other than supporting multiple readers, the only really "new" feature is the max_writers parameter, which can be used to cap the number of waiting writers. Typically I expect most users would only choose 0/None (unlimited) or 1 (guarantee single writer).

Benchmark

I included a benchmark that simulates a group of workers sharing the lock for reading and writing. Perhaps it doesn't measure numbers that are super meaningful to optimize, but it shows that the lock demonstrates the expected behavior, and you can run parameter sweeps to see how it handles different levels of contention.

I added dev dependencies on pandas (for printing stats) and matplotlib (for reproducing graphs). matplotlib is not needed to run the benchmark, only to visualize the time series output after a run.

Sample run output

duration = 5, seed = 0, num_workers = 2, wr_ratio = 0.01, io_duration = 0.025, max_writers = 0
iops: 79.60
                       min    mean     p95     max
read_acquire_time   0.09ms  0.53ms  0.20ms 76.15ms
read_release_time   0.07ms  0.11ms  0.15ms  0.24ms
write_acquire_time 25.46ms 33.87ms 48.12ms 50.63ms
write_release_time  0.14ms  0.15ms  0.16ms  0.16ms
                      success  timeout  aborted
read_acquire_status       395        0        0
write_acquire_status        3        0        0


duration = 5, seed = 0, num_workers = 2, wr_ratio = 0.01, io_duration = 0.025, max_writers = 1
iops: 74.00
                       min    mean     p95     max
read_acquire_time   0.09ms  0.62ms  0.19ms 75.74ms
read_release_time   0.07ms  0.10ms  0.13ms  0.30ms
write_acquire_time 25.35ms 25.38ms 25.40ms 25.41ms
write_release_time  0.10ms  0.11ms  0.13ms  0.13ms
                      success  timeout  aborted
read_acquire_status       367        0        0
write_acquire_status        3        0        0


duration = 5, seed = 0, num_workers = 2, wr_ratio = 0.1, io_duration = 0.025, max_writers = 0
iops: 59.60
                      min    mean     p95      max
read_acquire_time  0.10ms  5.82ms 50.63ms 151.60ms
read_release_time  0.07ms  0.11ms  0.14ms   0.19ms
write_acquire_time 0.15ms 27.89ms 50.73ms  50.84ms
write_release_time 0.11ms  0.15ms  0.18ms   0.20ms
                      success  timeout  aborted
read_acquire_status       267        0        0
write_acquire_status       31        0        0


duration = 5, seed = 0, num_workers = 2, wr_ratio = 0.1, io_duration = 0.025, max_writers = 1
iops: 58.80
                      min    mean     p95      max
read_acquire_time  0.09ms  5.52ms 50.63ms 126.46ms
read_release_time  0.07ms  0.11ms  0.14ms   0.22ms
write_acquire_time 0.13ms 27.85ms 63.30ms  75.91ms
write_release_time 0.08ms  0.13ms  0.19ms   0.34ms
                      success  timeout  aborted
read_acquire_status       263        0        0
write_acquire_status       31        0        0


duration = 5, seed = 0, num_workers = 4, wr_ratio = 0.01, io_duration = 0.025, max_writers = 0
iops: 137.40
                       min    mean      p95      max
read_acquire_time   0.09ms  2.49ms   0.26ms 151.62ms
read_release_time   0.07ms  0.11ms   0.15ms   0.27ms
write_acquire_time 25.41ms 60.28ms 108.79ms 126.30ms
write_release_time  0.13ms  0.15ms   0.17ms   0.17ms
                      success  timeout  aborted
read_acquire_status       679        0        0
write_acquire_status        8        0        0


duration = 5, seed = 0, num_workers = 4, wr_ratio = 0.01, io_duration = 0.025, max_writers = 1
iops: 148.60
                       min    mean     p95     max
read_acquire_time   0.09ms  1.58ms  0.23ms 75.89ms
read_release_time   0.06ms  0.11ms  0.14ms  0.30ms
write_acquire_time 25.32ms 38.05ms 50.77ms 50.78ms
write_release_time  0.09ms  0.12ms  0.13ms  0.13ms
                      success  timeout  aborted
read_acquire_status       737        0        0
write_acquire_status        6        0        0


duration = 5, seed = 0, num_workers = 4, wr_ratio = 0.1, io_duration = 0.025, max_writers = 0
iops: 73.20
                      min    mean      p95      max
read_acquire_time  0.09ms 23.85ms 101.31ms 278.17ms
read_release_time  0.07ms  0.11ms   0.15ms   0.28ms
write_acquire_time 0.14ms 50.70ms 101.35ms 152.18ms
write_release_time 0.09ms  0.14ms   0.19ms   0.20ms
                      success  timeout  aborted
read_acquire_status       323        0        0
write_acquire_status       43        0        0


duration = 5, seed = 0, num_workers = 4, wr_ratio = 0.1, io_duration = 0.025, max_writers = 1
iops: 86.40
                      min    mean      p95      max
read_acquire_time  0.09ms 18.82ms 126.28ms 202.43ms
read_release_time  0.07ms  0.12ms   0.15ms   0.28ms
write_acquire_time 0.12ms 41.44ms 126.43ms 126.59ms
write_release_time 0.09ms  0.14ms   0.19ms   0.20ms
                      success  timeout  aborted
read_acquire_status       391        0        0
write_acquire_status       41        0        9


duration = 5, seed = 0, num_workers = 8, wr_ratio = 0.01, io_duration = 0.025, max_writers = 0
iops: 229.60
                       min    mean      p95      max
read_acquire_time   0.09ms  7.51ms  50.78ms 176.95ms
read_release_time   0.06ms  0.12ms   0.18ms   0.49ms
write_acquire_time 25.45ms 85.16ms 126.53ms 126.55ms
write_release_time  0.11ms  0.16ms   0.20ms   0.21ms
                      success  timeout  aborted
read_acquire_status      1137        0        0
write_acquire_status       11        0        0


duration = 5, seed = 0, num_workers = 8, wr_ratio = 0.01, io_duration = 0.025, max_writers = 1
iops: 263.20
                       min    mean      p95      max
read_acquire_time   0.09ms  4.76ms  50.56ms 151.84ms
read_release_time   0.07ms  0.11ms   0.17ms   0.50ms
write_acquire_time 50.53ms 71.33ms 113.95ms 126.63ms
write_release_time  0.10ms  0.13ms   0.16ms   0.16ms
                      success  timeout  aborted
read_acquire_status      1305        0        0
write_acquire_status       11        0        1


duration = 5, seed = 0, num_workers = 8, wr_ratio = 0.1, io_duration = 0.025, max_writers = 0
iops: 107.40
                      min    mean      p95      max
read_acquire_time  0.10ms 45.93ms 201.72ms 302.87ms
read_release_time  0.07ms  0.12ms   0.16ms   0.32ms
write_acquire_time 0.12ms 64.21ms 151.78ms 227.21ms
write_release_time 0.09ms  0.14ms   0.18ms   0.21ms
                      success  timeout  aborted
read_acquire_status       479        0        0
write_acquire_status       58        0        0


duration = 5, seed = 0, num_workers = 8, wr_ratio = 0.1, io_duration = 0.025, max_writers = 1
iops: 112.00
                      min    mean      p95      max
read_acquire_time  0.10ms 44.48ms 176.69ms 303.13ms
read_release_time  0.07ms  0.12ms   0.16ms   0.48ms
write_acquire_time 0.14ms 59.12ms 125.25ms 126.61ms
write_release_time 0.10ms  0.15ms   0.18ms   0.23ms
                      success  timeout  aborted
read_acquire_status       518        0        0
write_acquire_status       42        0       14

[jit-ci]

Hi, I’m Jit, a friendly security platform designed to help developers build secure applications from day zero with an MVS (Minimal viable security) mindset.

In case there are security findings, they will be communicated to you as a comment inside the PR.

Hope you’ll enjoy using Jit.

Questions? Comments? Want to learn more? Get in touch with us.

[petyaslavova]

Hi @matthew-mcallister thank you for your contribution! We will review your change soon.