Kernel Functions for Drivers rwlock(9F)
NAME
rwlock, rwinit, rwdestroy, rwenter, rwexit, rwtryenter,
rwdowngrade, rwtryupgrade, rwreadlocked - readers/writer
lock functions
SYNOPSIS
#include
void rwinit(krwlockt *rwlp, char *name, krwtypet type, void *arg);
void rwdestroy(krwlockt *rwlp);
void rwenter(krwlockt *rwlp, krwt entertype);
void rwexit(krwlockt *rwlp);
int rwtryenter(krwlockt *rwlp, krwt entertype);
void rwdowngrade(krwlockt *rwlp);
int rwtryupgrade(krwlockt *rwlp);
int rwreadlocked(krwlockt *rwlp);
INTERFACE LEVEL
Solaris DI specific (Solaris DI).
PARAMETERS
rwlp Pointer to a krwlockt readers/writer lock.
name Descriptive string. This is obsolete and
should be NUL. (Non-null strings are legal,
but they're a waste of kernel memory.)
type Type of readers/writer lock.
arg Type-specific argument for initialization
function.
SunOS 5.11 Last change: 16 Jan 2006 1
Kernel Functions for Drivers rwlock(9F)
entertype One of the values RWREADER or RWRITER,
indicating whether the lock is to be acquired
non-exclusively (RWREADER) or exclusively
(RWRITER).
DESCRIPTION
A multiple-readers, single-writer lock is represented by the
krwlockt data type. This type of lock will allow many
threads to have simultaneous 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.
The rwinit() function initializes a readers/writer lock. It
is an error to initialize a lock more than once. The type
argument should be set to RWDRIVER. If the lock is used by
the interrupt handler, the type-specific argument, arg,
should be the interrupt priority returned from
ddiintrgetpri(9F) or ddiintrgetsoftintpri(9F). Note
that arg should be the value of the interrupt priority cast
by calling the DINTRPRI macro. If the lock is not used
by any interrupt handler, the argument should be NUL.
The rwdestroy() function releases any resources that might
have been allocated by rwinit(). It should be called before
freeing the memory containing the lock. The lock must not be
held by any thread when it is destroyed.
The rwenter() function acquires the lock, and blocks if
necessary. If entertype is RWREADER, the caller blocks if
there is a writer or a thread attempting to enter for writ-
ing. If entertype is RWRITER, 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.
SunOS 5.11 Last change: 16 Jan 2006 2
Kernel Functions for Drivers rwlock(9F)
The rwexit() function releases the lock and may wake up one
or more threads waiting on the lock.
The rwtryenter() function attempts to enter the lock, like
rwenter(), 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
RWRITER), may call rwdowngrade() to convert to holding
the lock non-exclusively (as if entered with RWREADER). One
or more waiting readers may be unblocked.
The rwtryupgrade() function 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.
The rwreadlocked() function returns non-zero if the cal-
ling thread holds the lock for read, and zero if the caller
holds the lock for write. The caller must hold the lock. The
system may panic if rwreadlocked() is called for a lock
that isn't held by the caller.
RETURN VALUES
0 rwtryenter() could not obtain the lock without
blocking.
0 rwtryupgrade() was unable to perform the
upgrade because of other threads holding or
waiting to hold the lock.
0 rwreadlocked() returns 0 if the lock is held
by the caller for write.
non-zero from rwreadlocked() if the lock is held by the
caller for read.
non-zero successful return from rwtryenter() or
rwtryupgrade().
CONTEXT
SunOS 5.11 Last change: 16 Jan 2006 3
Kernel Functions for Drivers rwlock(9F)
These functions can be called from user, interrupt, or ker-
nel context, except for rwinit() and rwdestroy(), which
can be called from user context only.
SEE ALSO
condvar(9F), ddiintralloc(9F), ddiintraddhandler(9F),
ddiintrgetpri(9F), ddiintrgetsoftintpri(9F),
mutex(9F), semaphore(9F)
Writing Device Drivers
NOTES
Compiling with LOCKTEST or MPSTATS defined no longer has
any effect. To gather lock statistics, see lockstat(1M).
SunOS 5.11 Last change: 16 Jan 2006 4
|
