I would appreciate any donations. Wishlist or send e-mail type donations to maekawa AT daemon-systems.org.

Thank you.

RWLOCK(9)                  Kernel Developer's Manual                 RWLOCK(9)

     rw, rw_init, rw_destroy, rw_enter, rw_exit, rw_tryenter, rw_tryupgrade,
     rw_downgrade, rw_read_held, rw_write_held, rw_lock_held - reader / writer
     lock primitives

     #include <sys/rwlock.h>

     rw_init(krwlock_t *rw);

     rw_destroy(krwlock_t *rw);

     rw_enter(krwlock_t *rw, const krw_t op);

     rw_exit(krwlock_t *rw);

     rw_tryenter(krwlock_t *rw, const krw_t op);

     rw_tryupgrade(krwlock_t *rw);

     rw_downgrade(krwlock_t *rw);

     rw_read_held(krwlock_t *rw);

     rw_write_held(krwlock_t *rw);

     rw_lock_held(krwlock_t *rw);

     options DIAGNOSTIC
     options LOCKDEBUG

     Reader / writer locks (RW locks) are used in the kernel to synchronize
     access to an object among LWPs (lightweight processes) and soft interrupt

     In addition to the capabilities provided by mutexes, RW locks distinguish
     between read (shared) and write (exclusive) access.

     RW locks are in one of three distinct states at any given time:

     Unlocked      The lock is not held.

     Read locked   The lock holders intend to read the protected object.
                   Multiple callers may hold a RW lock with "read intent"

     Write locked  The lock holder intends to update the protected object.
                   Only one caller may hold a RW lock with "write intent".

     The krwlock_t type provides storage for the RW lock object.  This should
     be treated as an opaque object and not examined directly by consumers.

     Note that these interfaces must not be used from a hardware interrupt

     options DIAGNOSTIC

           Kernels compiled with the DIAGNOSTIC option perform basic sanity
           checks on RW lock operations.

     options LOCKDEBUG

           Kernels compiled with the LOCKDEBUG option perform potentially CPU
           intensive sanity checks on RW lock operations.


           Initialize a lock for use.  No other operations can be performed on
           the lock until it has been initialized.


           Release resources used by a lock.  The lock may not be used after
           it has been destroyed.

     rw_enter(rw, op)

           If RW_READER is specified as the argument to op, acquire a read
           lock.  If the lock is write held, the caller will block and not
           return until the hold is acquired.  Callers must not recursively
           acquire read locks.

           If RW_WRITER is specified, acquire a write lock.  If the lock is
           already held, the caller will block and not return until the hold
           is acquired.

           RW locks and other types of locks must always be acquired in a
           consistent order with respect to each other.  Otherwise, the
           potential for system deadlock exists.


           Release a lock.  The lock must have been previously acquired by the

     rw_tryenter(rw, op)

           Try to acquire a lock, but do not block if the lock is already
           held.  If the lock is acquired successfully, return non-zero.
           Otherwise, return zero.

           Valid arguments to op are RW_READER or RW_WRITER.


           Try to upgrade a lock from one read hold to a write hold.  If the
           lock is upgraded successfully, returns non-zero.  Otherwise,
           returns zero.


           Downgrade a lock from a write hold to a read hold.


           Return non-zero if write lock is held by current lwp.  Otherwise,
           return zero.

           Returns non-zero if read lock is held by any lwp.  Otherwise,
           return zero.


           Returns non-zero if either read or write lock is held by any lwp.
           Otherwise, return zero.

           Functions rw_write_held(), rw_read_held(), and rw_lock_held() must
           never be used to make locking decisions at run time: they are
           provided only for diagnostic purposes.  They are also not atomic,
           hence they should only be used to assert that lock is held.  The
           only exception is rw_write_held(), which can be also used safely to
           assert that write lock is NOT currently held by current lwp.

     RW locks are subject to high cache contention on multiprocessor systems,
     and scale poorly when the write:read ratio is not strongly in favour of
     readers.  Ideally, RW locks should only be used in settings when the
     following three conditions are met:

        The data object(s) protected by the RW lock are read much more
         frequently than written.

        The read-side hold time for the RW lock is long (in the order of
         thousands of processor clock cycles).

        Strong synchronization semantics are required: there is no scope for
         lockless, lazy or optimistic synchronization.

     Generally speaking, it is better to organise code paths and/or data flows
     such that fewer and weaker synchronization points are required to ensure
     correct operation.

     The core of the RW lock implementation is in sys/kern/kern_rwlock.c.

     The header file sys/sys/rwlock.h describes the public interface, and
     interfaces that machine-dependent code must provide to support RW locks.

     membar_ops(3), lockstat(8), condvar(9), mutex(9)

     Jim Mauro and Richard McDougall, Solaris Internals: Core Kernel
     Architecture, Prentice Hall, 2001, ISBN 0-13-022496-0.

     The RW lock primitives first appeared in NetBSD 5.0.

NetBSD 8.99.34                 December 10, 2018                NetBSD 8.99.34