svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
rw_init(9f)
rwlock(9F) Kernel Functions rwlock(9F)
NAME
rwlock, rw_create, rw_init, rw_destroy, rw_enter, rw_enter_sig,
rw_exit, rw_tryenter, rw_downgrade, rw_tryupgrade, rw_read_locked -
readers/writer lock functions
SYNOPSIS
#include <sys/ksynch.h>
void rw_init(krwlock_t *rwlp, char *name, krw_type_t type, void *arg);
int rw_create(krwlock_t *rwlp, int kmflags, krw_type_t type, void * arg);
void rw_destroy(krwlock_t *rwlp);
void rw_enter(krwlock_t *rwlp, krw_t enter_type);
int rw_enter_sig(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);
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI).
PARAMETERS
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 ker‐
nel memory.)
type Type of readers/writer lock. RW_DEFAULT and RW_DRIVER for
non-NUMA rwlock. RW_NUMA_DEFAULT for NUMA aware rwlock
and RW_NUMA_READ_REENTRANT for reader re-entrant NUMA
aware rwlock.
arg Type-specific argument for initialization function.
kmflags Determines whether caller can sleep for memory while al‐
locating it for NUMA aware rwlock. Possible flags are
KM_SLEEP to allow sleeping until memory is available, or
KM_NOSLEEP to return failure (-1) immediately if memory
is not available.
enter_type One of the values RW_READER or RW_WRITER, indicating
whether the lock is to be acquired non-exclusively
(RW_READER) or exclusively (RW_WRITER).
DESCRIPTION
A multiple-readers, single-writer lock is represented by the krwlock_t
data type. This type of lock will allow many threads to have simultane‐
ous read-only access to an object. Only one thread may have write ac‐
cess 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 rw_init() function initializes a readers/writer lock. It is an er‐
ror 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 interrupt priority returned
from ddi_intr_get_pri(9F) or ddi_intr_get_softint_pri(9F). Note that
arg should be the value of the interrupt priority cast by calling the
DDI_INTR_PRI macro. If the lock is not used by any interrupt handler,
the argument should be NULL.
The rw_create() function creates and initializes readers/writer lock.
The kmflags argument determines whether the caller can sleep while al‐
locating memory for rwlock. KM_SLEEP should be used to allow sleeping
until memory is available, or KM_NOSLEEP to return with failure (-1)
immediately if memory is not available. If RW_DRIVER is passed in type
then it initializes a non-NUMA rwlock which is same as calling rw_init
with type RW_DRIVER. If RW_NUMA_DEFAULT is passed in type, then it ini‐
tializes a NUMA aware rwlock. If RW_NUMA_READ_REENTRANT is passed in
type, then it initializes a reader re-entrant NUMA aware rwlock. Reader
re-entrancy feature allows threads who have already obtained a read
lock to re-enter the lock as a reader again even if there are waiting
writers. Callers who have not obtained a read lock give waiting writers
priority. However, NUMA aware RWlock does not allow re-entrant writers,
nor does it allow a re-entrant mix of reads and writes (that is, it
does not allow a caller who has already obtained a read lock to be able
to then grab a write lock without first dropping all read locks, and
vice versa). It is necessary to call rw_destroy for NUMA aware RWlock
to avoid memory leaks.
Note -
RW_NUMA_DEFAULT and RW_NUMA_READ_REENTRANT cannot be passed in
rw_init as type. rw_init and rw_create are same if type is RW_DRIVER
or RW_DEFAULT.
The rw_destroy() function 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.
The rw_enter() function 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: If the lock is not reader re-entrant NUMA aware rwlock, then 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.
The rw_enter_sig() function is similar to rw_enter(), except it returns
the appropriate error number if a signal (for example, by kill(2)) is
sent to the thread. Where the operation is interrupted, EINTR is re‐
turned.
The rw_exit() function releases the lock and may wake up one or more
threads waiting on the lock.
The rw_tryenter() function attempts to enter the lock, like rw_enter(),
but never blocks. It returns a non-zero value if the lock was success‐
fully entered, and zero otherwise. In case of reader re-entrant NUMA
aware RWlock, rw_tryupgrade can only succeed if the lock is held only
once.
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 un‐
blocked.
The rw_tryupgrade() 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 rw_read_locked() function returns non-zero if the calling 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
rw_read_locked() is called for a lock that isn't held by the caller.
RETURN VALUES
1 rw_create() was successful.
-1 rw_create() was not successful.
0 rw_enter_sig() was successful.
EINTR rw_enter_sig() was interrupted.
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().
CONTEXT
These functions can be called from user, interrupt, or kernel context,
except for rw_init() and rw_destroy(), which can be called from user
context only.
SEE ALSO
condvar(9F), ddi_intr_add_handler(9F), ddi_intr_alloc(9F),
ddi_intr_get_pri(9F), ddi_intr_get_softint_pri(9F), mutex(9F), sema‐
phore(9F)
Writing Device Drivers in Oracle Solaris 11.4
NOTES
Compiling with _LOCKTEST or _MPSTATS defined no longer has any effect.
To gather lock statistics, see lockstat(8).
Oracle Solaris 11.4 21 Feb 2022 rwlock(9F)