1rwlock(9F) Kernel Functions for Drivers rwlock(9F)
2
6 rwlock, rw_init, rw_destroy, rw_enter, rw_exit, rw_tryenter, rw_down‐
7 grade, rw_tryupgrade, rw_read_locked - readers/writer lock functions
8
10 #include <sys/ksynch.h>
11 void rw_init(krwlock_t *rwlp, char *name, krw_type_t type, void *arg);
15 void rw_destroy(krwlock_t *rwlp);
18 void rw_enter(krwlock_t *rwlp, krw_t enter_type);
21 void rw_exit(krwlock_t *rwlp);
24 int rw_tryenter(krwlock_t *rwlp, krw_t enter_type);
27 void rw_downgrade(krwlock_t *rwlp);
30 int rw_tryupgrade(krwlock_t *rwlp);
33 int rw_read_locked(krwlock_t *rwlp);
36
39 Solaris DDI specific (Solaris DDI).
40
42 rwlp Pointer to a krwlock_t readers/writer lock.
43 name Descriptive string. This is obsolete and should be NULL.
46 (Non-null strings are legal, but they're a waste of ker‐
47 nel memory.)
48 type Type of readers/writer lock.
51 arg Type-specific argument for initialization function.
54 enter_type One of the values RW_READER or RW_WRITER, indicating
57 whether the lock is to be acquired non-exclusively
58 (RW_READER) or exclusively (RW_WRITER).
59
62 A multiple-readers, single-writer lock is represented by the krwlock_t
63 data type. This type of lock will allow many threads to have simultane‐
64 ous read-only access to an object. Only one thread may have write
65 access at any one time. An object which is searched more frequently
66 than it is changed is a good candidate for a readers/writer lock.
67 Readers/writer locks are slightly more expensive than mutex locks, and
70 the advantage of multiple read access may not occur if the lock will
71 only be held for a short time.
72 The rw_init() function initializes a readers/writer lock. It is an
75 error to initialize a lock more than once. The type argument should be
76 set to RW_DRIVER. If the lock is used by the interrupt handler, the
77 type-specific argument, arg, should be the interrupt priority returned
78 from ddi_intr_get_pri(9F) or ddi_intr_get_softint_pri(9F). Note that
79 arg should be the value of the interrupt priority cast by calling the
80 DDI_INTR_PRI macro. If the lock is not used by any interrupt handler,
81 the argument should be NULL.
82 The rw_destroy() function releases any resources that might have been
85 allocated by rw_init(). It should be called before freeing the memory
86 containing the lock. The lock must not be held by any thread when it is
87 destroyed.
88 The rw_enter() function acquires the lock, and blocks if necessary. If
91 enter_type is RW_READER, the caller blocks if there is a writer or a
92 thread attempting to enter for writing. If enter_type is RW_WRITER, the
93 caller blocks if any thread holds the lock.
94 NOTE: It is a programming error for any thread to acquire an rwlock it
97 already holds, even as a reader. Doing so can deadlock the system: if
98 thread R acquires the lock as a reader, then thread W tries to acquire
99 the lock as a writer, W will set write-wanted and block. When R tries
100 to get its second read hold on the lock, it will honor the write-wanted
101 bit and block waiting for W; but W cannot run until R drops the lock.
102 Thus threads R and W deadlock.
103 The rw_exit() function releases the lock and may wake up one or more
106 threads waiting on the lock.
107 The rw_tryenter() function attempts to enter the lock, like rw_enter(),
110 but never blocks. It returns a non-zero value if the lock was success‐
111 fully entered, and zero otherwise.
112 A thread which holds the lock exclusively (entered with RW_WRITER), may
115 call rw_downgrade() to convert to holding the lock non-exclusively (as
116 if entered with RW_READER). One or more waiting readers may be
117 unblocked.
118 The rw_tryupgrade() function can be called by a thread which holds the
121 lock for reading to attempt to convert to holding it for writing. This
122 upgrade can only succeed if no other thread is holding the lock and no
123 other thread is blocked waiting to acquire the lock for writing.
124 The rw_read_locked() function returns non-zero if the calling thread
127 holds the lock for read, and zero if the caller holds the lock for
128 write. The caller must hold the lock. The system may panic if
129 rw_read_locked() is called for a lock that isn't held by the caller.
130
132 0 rw_tryenter() could not obtain the lock without blocking.
133 0 rw_tryupgrade() was unable to perform the upgrade because
136 of other threads holding or waiting to hold the lock.
137 0 rw_read_locked() returns 0 if the lock is held by the call‐
140 er for write.
141 non-zero from rw_read_locked() if the lock is held by the caller for
144 read.
145 non-zero successful return from rw_tryenter() or rw_tryupgrade().
148
151 These functions can be called from user, interrupt, or kernel context,
152 except for rw_init() and rw_destroy(), which can be called from user
153 context only.
154
156 condvar(9F), ddi_intr_alloc(9F), ddi_intr_add_handler(9F),
157 ddi_intr_get_pri(9F), ddi_intr_get_softint_pri(9F), mutex(9F), sema‐
158 phore(9F)
159 Writing Device Drivers
162
164 Compiling with _LOCKTEST or _MPSTATS defined no longer has any effect.
165 To gather lock statistics, see lockstat(1M).
166SunOS 5.11 16 Jan 2006 rwlock(9F)