unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

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

NAME
     rwlock, rw_init, rw_enter, rw_exit, rw_enter_read, rw_enter_write,
     rw_exit_read, rw_exit_write, rw_assert_wrlock, rw_assert_rdlock,
     rw_assert_unlocked, rw_status, RWLOCK_INITIALIZER, rrw_init, rrw_enter,
     rrw_exit, rrw_status -- interface to read/write locks

SYNOPSIS
     #include <&lt;sys/rwlock.h>&gt;

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

     int
     rw_enter(struct rwlock *rwl, int flags);

     void
     rw_exit(struct rwlock *rwl);

     void
     rw_enter_read(struct rwlock *rwl);

     void
     rw_enter_write(struct rwlock *rwl);

     void
     rw_exit_read(struct rwlock *rwl);

     void
     rw_exit_write(struct rwlock *rwl);

     int
     rw_assert_wrlock(struct rwlock *rwl);

     void
     rw_assert_rdlock(struct rwlock *rwl);

     void
     rw_assert_unlocked(struct rwlock *rwl);

     int
     rw_status(struct rwlock *rwl);

     RWLOCK_INITIALIZER(const char *name);

     void
     rrw_init(struct rrwlock *rrwl, const char *name);

     int
     rrw_enter(struct rrwlock *rrwl, int flags);

     void
     rrw_exit(struct rrwlock *rrwl);

     int
     rrw_status(struct rrwlock *rrwl);

DESCRIPTION
     The rwlock set of functions provides a multiple-reader, single-writer
     locking mechanism to ensure mutual exclusion between different threads.

     Read locks can be acquired while the write lock is not held, and may
     coexist in distinct threads at any time.  A write lock, however, can only
     be acquired when there are no read locks held, granting exclusive access
     to a single thread.

     The rw_init() function is used to initiate the lock pointed to by rwl.
     The name argument specifies the name of the lock, which is used as the
     wait message if the thread needs to sleep.

     The rw_enter() function acquires a lock.  The flags argument specifies
     what kind of lock should be obtained and also modifies the operation.
     The possible flags are:

           RW_READ          Acquire a shared lock.
           RW_WRITE         Acquire an exclusive lock.
           RW_DOWNGRADE     Safely release an exclusive lock and acquire a
                            shared lock without letting other exclusive locks
                            in between.
           RW_INTR          When waiting for a lock, allow signals to inter-
                            rupt the sleep.
           RW_NOSLEEP       Do not wait for busy locks, fail with EBUSY
                            instead.
           RW_SLEEPFAIL     Wait for busy locks, but do not obtain them, fail
                            with EAGAIN instead.

     The rw_exit() function is used to release a held lock.

     The rw_enter_read() function acquires a read lock, sleeping if necessary.

     The rw_enter_write() function acquires a write lock, sleeping if neces-
     sary.

     The rw_exit_read() function releases a read lock.

     The rw_exit_write() function releases a write lock.

     The rw_assert_wrlock(), rw_assert_rdlock(), and rw_assert_unlocked()
     functions check the status rwl, panicking if it is not write-, read-, or
     unlocked, respectively.

     rw_status returns the current state of the lock:

           RW_WRITE        Lock is write locked by the calling thread.
           RW_WRITE_OTHER  Lock is write locked by a different thread.
           RW_READ         Lock is read locked.  The current thread may be one
                           of the threads that has it locked.
           0               Lock is not locked.

     A lock declaration may be initialised with the RWLOCK_INITIALIZER()
     macro.  The name argument specifies the name of the lock, which is used
     as the wait message if the thread needs to sleep.

     The rrwlock functions support recursive write locking by the same
     process.  They otherwise behave the same as their rwlock counterparts.

CONTEXT
     rw_init() and rrw_init() can be called during autoconf, from process con-
     text, or from interrupt context.

     All other functions can be called during autoconf or from process con-
     text.

SEE ALSO
     lockmgr(9), mutex(9)

HISTORY
     The rwlock functions first appeared in OpenBSD 3.5.

AUTHORS
     The rwlock functions were written by Artur Grabowski <art@openbsd.org>.

BSD                              July 9, 2014                              BSD