RWLOCK(9)

✨ RWLOCK — the kernel reader/writer lock, bestie edition ✨

okay so picture this: you're in the kernel, multiple threads wanna touch the same data, and you need ✨rules✨. That's rwlock, from the Kernel Developer's Manual (section 9). Sit down, grab a 🍓, let's get into it.

---

🌸 NAME 🌸

rwlock, rw_init, rw_init_flags, rw_destroy, rw_rlock, rw_wlock, rw_runlock, rw_wunlock, rw_unlock, rw_try_rlock, rw_try_upgrade, rw_try_wlock, rw_downgrade, rw_sleep, rw_initialized, rw_wowned, rw_assert, RW_SYSINIT, RW_SYSINIT_FLAGS — it's giving kernel reader/writer lock 💅

---

🌈 SYNOPSIS 🌈

#include <sys/param.h>
#include <sys/lock.h>
#include <sys/rwlock.h>

void
rw_init(struct rwlock *rw, const char *name);

void
rw_init_flags(struct rwlock *rw, const char *name, int opts);

void
rw_destroy(struct rwlock *rw);

void
rw_rlock(struct rwlock *rw);

void
rw_wlock(struct rwlock *rw);

int
rw_try_rlock(struct rwlock *rw);

int
rw_try_wlock(struct rwlock *rw);

void
rw_runlock(struct rwlock *rw);

void
rw_wunlock(struct rwlock *rw);

void
rw_unlock(struct rwlock *rw);

int
rw_try_upgrade(struct rwlock *rw);

void
rw_downgrade(struct rwlock *rw);

int
rw_sleep(void *chan, struct rwlock *rw, int priority, const char *wmesg,
    int timo);

int
rw_initialized(const struct rwlock *rw);

int
rw_wowned(const struct rwlock *rw);

options INVARIANTS
options INVARIANT_SUPPORT

void
rw_assert(const struct rwlock *rw, int what);

#include <sys/kernel.h>

RW_SYSINIT(name, struct rwlock *rw, const char *desc);

RW_SYSINIT_FLAGS(name, struct rwlock *rw, const char *desc, int flags);

---

💖 DESCRIPTION 💖

So reader/writer locks let multiple threads share access to protected data, OR let one single thread have it all to themselves. Exclusive. Main character energy 👑.

The threads with shared access are called readers, because all they do is read the protected data. No touching, just looking 👀. A thread with exclusive access is called a writer, because it's the one who actually gets to modify the protected data.

ngl, reader/writer locks look super similar to sx(9) locks, but the usage pattern is a whole different vibe. Reader/writer locks can be treated like mutexes (see mutex(9)) with shared/exclusive semantics. But unlike sx(9):

• an rwlock can be locked while holding a non-spin mutex
• an rwlock cannot be held while sleeping 😴

Also, rwlock locks have priority propagation like mutexes do, but priority can only be propagated to writers. Why? Because readers are anonymous — no names, no identity, we can't propagate to them fr fr. Another important property: readers can always recurse, and exclusive locks can be made recursive selectively. Periodt.

🎀 Macros and Functions 🎀

• rw_init(struct rwlock *rw, const char *name) — Initialize the structure hanging out at rw as a reader/writer lock, described by name. That description is solely for debugging purposes, bestie, don't read into it. You must call this before doing literally anything else to the lock.
• rw_init_flags(struct rwlock *rw, const char *name, int opts) — Initialize the rw lock exactly like rw_init() does, but you get to pass a set of optional flags through opts to alter how rw behaves. It contains one or more of these flags:
  • RW_DUPOK — Witness should not log messages about duplicate locks being acquired.
  • RW_NOPROFILE — Do not profile this lock.
  • RW_NOWITNESS — Instruct witness(4) to ignore this lock. 🙈
  • RW_QUIET — Do not log any operations for this lock via ktr(4).
  • RW_RECURSE — Allow threads to recursively acquire exclusive locks for rw.
  • RW_NEW — If the kernel has been compiled with option INVARIANTS, rw_init_flags() will assert that the rw has not been initialized multiple times without intervening calls to rw_destroy() — unless this option is specified.
• rw_rlock(struct rwlock *rw) — Lock rw as a reader. If any thread holds this lock exclusively, your current thread blocks, and its priority gets propagated to the exclusive holder. And here's the cute part: rw_rlock() can be called when the thread has already acquired reader access on rw. That's called "recursing on a lock" 💫.
• rw_wlock(struct rwlock *rw) — Lock rw as a writer. If there are any shared owners of the lock, the current thread blocks. rw_wlock() can only be called recursively if rw was initialized with the RW_RECURSE option enabled. No sneaky recursion otherwise 🚫.
• rw_try_rlock(struct rwlock *rw) — Try to lock rw as a reader. Returns true if it worked, otherwise 0 comes back. No blocking, just vibes.
• rw_try_wlock(struct rwlock *rw) — Try to lock rw as a writer. Returns true if it worked, otherwise 0 comes back.
• rw_runlock(struct rwlock *rw) — Releases a shared lock previously acquired by rw_rlock().
• rw_wunlock(struct rwlock *rw) — Releases an exclusive lock previously acquired by rw_wlock().
• rw_unlock(struct rwlock *rw) — Releases a shared lock previously acquired by rw_rlock() OR an exclusive lock previously acquired by rw_wlock(). It's flexible like that 💅.
• rw_try_upgrade(struct rwlock *rw) — Attempt to upgrade a single shared lock to an exclusive lock. The current thread must hold a shared lock of rw. This only succeeds if the current thread holds the only shared lock on rw, and it only holds a single shared lock. If it works, rw_try_upgrade() returns a non-zero value and the current thread now holds an exclusive lock 🎉. If it fails, rw_try_upgrade() returns zero and the current thread still holds a shared lock. Whomp whomp.
• rw_downgrade(struct rwlock *rw) — Convert an exclusive lock into a single shared lock. The current thread must hold an exclusive lock of rw.
• rw_sleep(void *chan, struct rwlock *rw, int priority, const char *wmesg, int timo) — Atomically release rw while waiting for an event. For all the deets on the parameters here, go read sleep(9).
• rw_initialized(const struct rwlock *rw) — Returns non-zero if rw has been initialized, and zero otherwise. A little vibe check ✅.
• rw_destroy(struct rwlock *rw) — Destroys a lock previously initialized with rw_init(). The rw lock must be unlocked. Do not skip this, I'm serious 😭.
• rw_wowned(const struct rwlock *rw) — Returns a non-zero value if the current thread owns an exclusive lock on rw.
• rw_assert(const struct rwlock *rw, int what) — Lets assertions specified in what be made about rw. If the assertions aren't true AND the kernel was compiled with options INVARIANTS and options INVARIANT_SUPPORT, the kernel will panic 💀. Currently these base assertions are supported:
  • RA_LOCKED — Assert that current thread holds either a shared or exclusive lock of rw.
  • RA_RLOCKED — Assert that current thread holds a shared lock of rw.
  • RA_WLOCKED — Assert that current thread holds an exclusive lock of rw.
  • RA_UNLOCKED — Assert that current thread holds neither a shared nor exclusive lock of rw.

In addition, one of these optional flags may be specified alongside RA_LOCKED, RA_RLOCKED, or RA_WLOCKED:

• RA_RECURSED — Assert that the current thread holds a recursive lock of rw.
• RA_NOTRECURSED — Assert that the current thread does not hold a recursive lock of rw.

---

🦋 SEE ALSO 🦋

locking(9), mutex(9), panic(9), sema(9), sx(9)

---

⭐ HISTORY ⭐

These functions appeared in FreeBSD 7.0. Vintage ✨.

---

👑 AUTHORS 👑

The rwlock facility was written by John Baldwin. This manual page was written by Gleb Smirnoff. Absolute legends, both of them 🫶.

---

💀 BUGS 💀

• A kernel without WITNESS cannot assert whether the current thread does or does not hold a read lock. RA_LOCKED and RA_RLOCKED can only assert that any thread holds a read lock. They cannot ensure that the current thread holds a read lock. Further, RA_UNLOCKED can only assert that the current thread does not hold a write lock. So like... it's giving approximate, not exact, iykyk 😭.
• "Reader/writer" is a bit of an awkward name, lowkey. An rwlock can also be called a "Robert Watson" lock if desired. No cap, that's in the manual 🌈.

---

Debian build, dated November 11, 2017, RWLOCK(9) — that's the whole page bestie, go lock something (responsibly) 💖