| 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 —
#include <sys/rwlock.h>
void
  
  rw_init(krwlock_t
    *rw);
void
  
  rw_destroy(krwlock_t
    *rw);
void
  
  rw_enter(krwlock_t
    *rw, const krw_t
    op);
void
  
  rw_exit(krwlock_t
    *rw);
int
  
  rw_tryenter(krwlock_t
    *rw, const krw_t
    op);
int
  
  rw_tryupgrade(krwlock_t
    *rw);
void
  
  rw_downgrade(krwlock_t
    *rw);
int
  
  rw_read_held(krwlock_t
    *rw);
int
  
  rw_write_held(krwlock_t
    *rw);
int
  
  rw_lock_held(krwlock_t
    *rw);
  
  options DIAGNOSTIC
  
  options LOCKDEBUG
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:
UnlockedRead
    lockedWrite
    lockedThe 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 handler.
options DIAGNOSTICKernels compiled with the DIAGNOSTIC
        option perform basic sanity checks on RW lock operations.
options LOCKDEBUGKernels compiled with the LOCKDEBUG
        option perform potentially CPU intensive sanity checks on RW lock
        operations.
rw_init(rw)Initialize a lock for use. No other operations can be performed on the lock until it has been initialized.
rw_destroy(rw)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.
rw_exit(rw)Release a lock. The lock must have been previously acquired by the caller.
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.
rw_tryupgrade(rw)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.
rw_downgrade(rw)Downgrade a lock from a write hold to a read hold.
rw_write_held(rw)Return non-zero if write lock is held by current lwp. Otherwise, return zero.
rw_read_held(rw)rw_lock_held(rw)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.
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 header file sys/sys/rwlock.h describes the public interface, and interfaces that machine-dependent code must provide to support RW locks.
Jim Mauro and Richard McDougall, Solaris Internals: Core Kernel Architecture, Prentice Hall, 2001, ISBN 0-13-022496-0.
| December 10, 2018 | NetBSD 9.4 |