rm_wlock.9freebsd

Langue: en

Version: 365169 (ubuntu - 25/10/10)

Section: 9 (Appels noyau Linux)


BSD mandoc

NAME

rmlock rm_init rm_init_flags rm_destroy rm_rlock rm_wlock rm_runlock rm_wunlock rm_wowned RM_SYSINIT - kernel reader/writer lock optimized for mostly read access patterns

SYNOPSIS

In sys/param.h In sys/lock.h In sys/rmlock.h Ft void Fn rm_init struct rmlock *rm const char *name Ft void Fn rm_init_flags struct rmlock *rm const char *name int opts Ft void Fn rm_destroy struct rmlock *rm Ft void Fn rm_rlock struct rmlock *rm struct rm_priotracker* tracker Ft void Fn rm_wlock struct rmlock *rm Ft void Fn rm_runlock struct rmlock *rm struct rm_priotracker* tracker Ft void Fn rm_wunlock struct rmlock *rm Ft int Fn rm_wowned struct rmlock *rm In sys/kernel.h Fn RM_SYSINIT name struct rmlock *rm const char *desc int opts

DESCRIPTION

Mostly reader locks allow shared access to protected data by multiple threads, or exclusive access by a single thread. The threads with shared access are known as readers since they only read the protected data. A thread with exclusive access is known as a writer since it can modify protected data.

Read mostly locks are designed to be efficient for locks almost exclusively used as reader locks and as such should be used for protecting data that rarely changes. Acquiring an exclusive lock after the lock had been locked for shared access is an expensive operation.

Although reader/writer locks look very similar to sx(9) locks, their usage pattern is different. Reader/writer locks can be treated as mutexes (see mutex(9)) with shared/exclusive semantics. Unlike sx(9), an can be locked while holding a non-spin mutex, and an cannot be held while sleeping. The locks have full priority propagation like mutexes. The rm_priotracker structure argument supplied in Fn rm_rlock and Fn rm_runlock is used to keep track of the read owner(s). Another important property is that shared holders of can recurse if the lock has been initialized with the LO_RECURSABLE option, however exclusive locks are not allowed to recurse.

Macros and Functions

Fn rm_init struct rmlock *rm const char *name
Initialize structure located at Fa rm as mostly reader lock, described by Fa name . The name description is used solely for debugging purposes. This function must be called before any other operations on the lock.
Fn rm_init_flags struct rmlock *rm const char *name int opts
Initialize the rm lock just like the Fn rm_init function, but specifying a set of optional flags to alter the behaviour of Fa rm , through the Fa opts argument. It contains one or more of the following flags:
RM_NOWITNESS
Instruct witness(4) to ignore this lock.
RM_RECURSE
Allow threads to recursively acquire exclusive locks for Fa rm .
Fn rm_rlock struct rmlock *rm struct rm_priotracker* tracker
Lock Fa rm as a reader. Using Fa tracker to track read owners of a lock for priority propagation. This data structure is only used internally by and must persist until Fn rm_runlock has been called. This data structure can be allocated on the stack since rmlocks cannot be held while sleeping. 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 LO_RECURSABLE option the Fn rm_rlock function can be called when the thread has already acquired reader access on Fa rm . This is called ``recursing on a lock''
Fn rm_wlock struct rmlock *rm
Lock Fa rm as a writer. If there are any shared owners of the lock, the current thread blocks. The Fn rm_wlock function cannot be called recursively.
Fn rm_runlock struct rmlock *rm struct rm_priotracker* tracker
This function releases a shared lock previously acquired by Fn rm_rlock . The Fa tracker argument must match the Fa tracker argument used for acquiring the shared lock
Fn rm_wunlock struct rmlock *rm
This function releases an exclusive lock previously acquired by Fn rm_wlock .
Fn rm_destroy struct rmlock *rm
This functions destroys a lock previously initialized with Fn rm_init . The Fa rm lock must be unlocked.
Fn rm_wowned struct rmlock *rm
This function returns a non-zero value if the current thread owns an exclusive lock on Fa rm .

SEE ALSO

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

HISTORY

These functions appeared in Fx 7.0 .

AUTHORS

An -nosplit The facility was written by An Stephan Uphoff . This manual page was written by An Gleb Smirnoff for rwlock and modified to reflect rmlock by An Stephan Uphoff .

BUGS

The implementation is currently not optimized for single processor systems.

The implementation uses a single per CPU list shared by all rmlocks in the system. If rmlocks become popular, hashing to multiple per CPU queues may be needed to speed up the writer lock process.

The can currently not be used as a lock argument for condition variable wait functions.