rwlock(9F) Kernel Functions for Drivers rwlock(9F)
rwlock, rw_init, rw_destroy, rw_enter, rw_exit, rw_tryenter, rw_downgrade, rw_tryupgrade, rw_read_locked - readers/writer lock functions
void rw_init(krwlock_t *rwlp, char *name, krw_type_t type, void *arg);
void rw_destroy(krwlock_t *rwlp);
void rw_enter(krwlock_t *rwlp, krw_t enter_type);
void rw_exit(krwlock_t *rwlp);
int rw_tryenter(krwlock_t *rwlp, krw_t enter_type);
void rw_downgrade(krwlock_t *rwlp);
int rw_tryupgrade(krwlock_t *rwlp);
int rw_read_locked(krwlock_t *rwlp);
Solaris DDI specific (Solaris DDI).
rwlp Pointer to a krwlock_t readers/writer lock.
name Descriptive string. This is obsolete and should be NULL. (Non-null strings are legal, but they're a waste of kernel mem-
type Type of readers/writer lock.
arg Type-specific argument for initialization function.
enter_type One of the values RW_READER or RW_WRITER, indicating whether the lock is to be acquired non-exclusively (RW_READER) or
A multiple-readers, single-writer lock is represented by the krwlock_t data type. This type of lock will allow many threads to have simul-
taneous read-only access to an object. Only one thread may have write access at any one time. An object which is searched more frequently
than it is changed is a good candidate for a readers/writer lock.
Readers/writer locks are slightly more expensive than mutex locks, and the advantage of multiple read access may not occur if the lock will
only be held for a short time.
rw_init() initializes a readers/writer lock. It is an error to initialize a lock more than once. The type argument should be set to
RW_DRIVER. If the lock is used by the interrupt handler, the type-specific argument, arg, should be the ddi_iblock_cookie returned from
ddi_get_iblock_cookie(9F) or ddi_get_soft_iblock_cookie(9F). If the lock is not used by any interrupt handler, the argument should be NULL.
rw_destroy() releases any resources that might have been allocated by rw_init(). It should be called before freeing the memory containing
the lock. The lock must not be held by any thread when it is destroyed.
rw_enter() acquires the lock, and blocks if necessary. If enter_type is RW_READER, the caller blocks if there is a writer or a thread
attempting to enter for writing. If enter_type is RW_WRITER, the caller blocks if any thread holds the lock.
NOTE: It is a programming error for any thread to acquire an rwlock it already holds, even as a reader. Doing so can deadlock the system:
if thread R acquires the lock as a reader, then thread W tries to acquire the lock as a writer, W will set write-wanted and block. When R
tries to get its second read hold on the lock, it will honor the write-wanted bit and block waiting for W; but W cannot run until R drops
the lock. Thus threads R and W deadlock.
rw_exit() releases the lock and may wake up one or more threads waiting on the lock.
rw_tryenter() attempts to enter the lock, like rw_enter(), but never blocks. It returns a non-zero value if the lock was successfully
entered, and zero otherwise.
A thread which holds the lock exclusively (entered with RW_WRITER), may call rw_downgrade() to convert to holding the lock non-exclusively
(as if entered with RW_READER). One or more waiting readers may be unblocked.
rw_tryupgrade() can be called by a thread which holds the lock for reading to attempt to convert to holding it for writing. This upgrade
can only succeed if no other thread is holding the lock and no other thread is blocked waiting to acquire the lock for writing.
rw_read_locked() returns non-zero if the calling thread holds the lock for read, and zero if the caller holds the lock for write. The call-
er must hold the lock. The system may panic if rw_read_locked() is called for a lock that isn't held by the caller.
0 rw_tryenter() could not obtain the lock without blocking.
0 rw_tryupgrade() was unable to perform the upgrade because of other threads holding or waiting to hold the lock.
0 rw_read_locked() returns 0 if the lock is held by the caller for write.
non-zero from rw_read_locked() if the lock is held by the caller for read.
non-zero successful return from rw_tryenter() or rw_tryupgrade().
These functions can be called from user or interrupt context, except for rw_init() and rw_destroy(), which can be called from user context
condvar(9F), ddi_add_intr(9F), ddi_get_iblock_cookie(9F), ddi_get_soft_iblock_cookie(9F), mutex(9F), semaphore(9F)
Writing Device Drivers
Compiling with _LOCKTEST or _MPSTATS defined no longer has any effect. To gather lock statistics, see lockstat(1M).
SunOS 5.10 10 Sep 2002 rwlock(9F)