Macros and Functions¶

rm_init(struct rmlock *rm, const char *name)

Initialize the read-mostly lock rm. The name description is used solely for debugging purposes. This function must be called before any other operations on the lock.

rm_init_flags(struct rmlock *rm, const char *name, int opts)

Similar to rm_init(), initialize the read-mostly lock rm with a set of optional flags. The opts arguments contains one or more of the following flags:

RM_NOWITNESS

Instruct witness(4) to ignore this lock.

RM_RECURSE

Allow threads to recursively acquire shared locks for rm.

RM_SLEEPABLE

Create a sleepable read-mostly lock.

RM_NEW

If the kernel has been compiled with option INVARIANTS, rm_init_flags() will assert that the rm has not been initialized multiple times without intervening calls to rm_destroy() unless this option is specified.

rm_rlock(struct rmlock *rm, struct rm_priotracker* tracker)

Lock rm as a reader using tracker to track read owners of a lock for priority propagation. This data structure is only used internally by rmlock and must persist until rm_runlock() has been called. This data structure can be allocated on the stack since readers cannot sleep. If any thread holds this lock exclusively, the current thread blocks, and its priority is propagated to the exclusive holder. If the lock was initialized with the RM_RECURSE option the rm_rlock() function can be called when the current thread has already acquired reader access on rm.

rm_try_rlock(struct rmlock *rm, struct rm_priotracker* tracker)

Try to lock rm as a reader. rm_try_rlock() will return 0 if the lock cannot be acquired immediately; otherwise, the lock will be acquired and a non-zero value will be returned. Note that rm_try_rlock() may fail even while the lock is not currently held by a writer. If the lock was initialized with the RM_RECURSE option, rm_try_rlock() will succeed if the current thread has already acquired reader access.

rm_wlock(struct rmlock *rm)

Lock rm as a writer. If there are any shared owners of the lock, the current thread blocks. The rm_wlock() function cannot be called recursively.

rm_runlock(struct rmlock *rm, struct rm_priotracker* tracker)

This function releases a shared lock previously acquired by rm_rlock(). The tracker argument must match the tracker argument used for acquiring the shared lock

rm_wunlock(struct rmlock *rm)

This function releases an exclusive lock previously acquired by rm_wlock().

rm_destroy(struct rmlock *rm)

This functions destroys a lock previously initialized with rm_init(). The rm lock must be unlocked.

rm_wowned(const struct rmlock *rm)

This function returns a non-zero value if the current thread owns an exclusive lock on rm.

rm_sleep(void *wchan, struct rmlock *rm, int priority, const char *wmesg, int timo)

This function atomically releases rm while waiting for an event. The rm lock must be exclusively locked. For more details on the parameters to this function, see sleep(9).

rm_assert(struct rmlock *rm, int what)

This function asserts that the rm lock is in the state specified by what. If the assertions are not true and the kernel is compiled with options INVARIANTS and options INVARIANT_SUPPORT, the kernel will panic. Currently the following base assertions are supported:

RA_LOCKED

Assert that current thread holds either a shared or exclusive lock of rm.

RA_RLOCKED

Assert that current thread holds a shared lock of rm.

RA_WLOCKED

Assert that current thread holds an exclusive lock of rm.

RA_UNLOCKED

Assert that current thread holds neither a shared nor exclusive lock of rm.

In addition, one of the following optional flags may be specified with RA_LOCKED, RA_RLOCKED, or RA_WLOCKED:

RA_RECURSED

Assert that the current thread holds a recursive lock of rm.

RA_NOTRECURSED

Assert that the current thread does not hold a recursive lock of rm.