1rwlock(9F)               Kernel Functions for Drivers               rwlock(9F)
2
3
4

NAME

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

SYNOPSIS

10       #include <sys/ksynch.h>
11
12
13
14       void rw_init(krwlock_t *rwlp, char *name, krw_type_t type, void *arg);
15
16
17       void rw_destroy(krwlock_t *rwlp);
18
19
20       void rw_enter(krwlock_t *rwlp, krw_t enter_type);
21
22
23       void rw_exit(krwlock_t *rwlp);
24
25
26       int rw_tryenter(krwlock_t *rwlp, krw_t enter_type);
27
28
29       void rw_downgrade(krwlock_t *rwlp);
30
31
32       int rw_tryupgrade(krwlock_t *rwlp);
33
34
35       int rw_read_locked(krwlock_t *rwlp);
36
37

INTERFACE LEVEL

39       Solaris DDI specific (Solaris DDI).
40

PARAMETERS

42       rwlp          Pointer to a krwlock_t readers/writer lock.
43
44
45       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
49
50       type          Type of readers/writer lock.
51
52
53       arg           Type-specific argument for initialization function.
54
55
56       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
60

DESCRIPTION

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
68
69       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
73
74       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
83
84       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
89
90       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
95
96       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
104
105       The  rw_exit()  function  releases the lock and may wake up one or more
106       threads waiting on the lock.
107
108
109       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
113
114       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
119
120       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
125
126       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

RETURN VALUES

132       0           rw_tryenter() could not obtain the lock without blocking.
133
134
135       0           rw_tryupgrade()  was  unable to perform the upgrade because
136                   of other threads holding or waiting to hold the lock.
137
138
139       0           rw_read_locked() returns 0 if the lock is held by the call‐
140                   er for write.
141
142
143       non-zero    from rw_read_locked() if the lock is held by the caller for
144                   read.
145
146
147       non-zero    successful return from rw_tryenter() or rw_tryupgrade().
148
149

CONTEXT

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

SEE ALSO

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
160
161       Writing Device Drivers
162

NOTES

164       Compiling with _LOCKTEST or _MPSTATS defined no longer has any  effect.
165       To gather lock statistics, see lockstat(1M).
166
167
168
169SunOS 5.11                        16 Jan 2006                       rwlock(9F)
Impressum