aboutsummaryrefslogtreecommitdiff
path: root/man/man3/lock.3
blob: 4308e369f8f4d59c67bec050e8316f09de66be40 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
.TH LOCK 3
.SH NAME
lock, canlock, unlock,
qlock, canqlock, qunlock,
rlock, canrlock, runlock,
wlock, canwlock, wunlock,
rsleep, rwakeup, rwakeupall
incref, decref
\- spin locks, queueing rendezvous locks, reader-writer locks, rendezvous points, and reference counts
.SH SYNOPSIS
.ft L
.nf
#include <u.h>
#include <libc.h>
.PP
.ft L
.nf
void	lock(Lock *l)
int	canlock(Lock *l)
void	unlock(Lock *l)
.PP
.ft L
.nf
void	qlock(QLock *l)
int	canqlock(QLock *l)
void	qunlock(QLock *l)
.PP
.ft L
.nf
void	rlock(RWLock *l)
int	canrlock(RWLock *l)
void	runlock(RWLock *l)
.PP
.ft L
.nf
void	wlock(RWLock *l)
int	canwlock(RWLock *l)
void	wunlock(RWLock *l)
.PP
.ft L
.nf
typedef struct Rendez {
	QLock *l;
	\fI...\fP
} Rendez;
.PP
.ft L
.nf
void	rsleep(Rendez *r)
int	rwakeup(Rendez *r)
int	rwakeupall(Rendez *r)
.PP
.ft L
#include <thread.h>
.PP
.ft L
.nf
typedef struct Ref {
	long ref;
} Ref;
.PP
.ft L
.nf
void incref(Ref*)
long decref(Ref*)
.fi
.SH DESCRIPTION
These routines are used  to synchronize processes sharing memory.
.PP
.B Locks
are spin locks,
.B QLocks
and
.B RWLocks
are different types of queueing locks,
and
.B Rendezes
are rendezvous points.
.PP
Locks and rendezvous points have trivial implementations in programs
not using the thread library
(see
.IR thread (3)),
since such programs have no concurrency.
.PP
Used carelessly, spin locks can be expensive and can easily generate deadlocks.
Their use is discouraged, especially in programs that use the
thread library because they prevent context switches between threads.
.PP
.I Lock
blocks until the lock has been obtained.
.I Canlock
is non-blocking.
It tries to obtain a lock and returns a non-zero value if it
was successful, 0 otherwise.
.I Unlock
releases a lock.
.PP
.B QLocks
have the same interface but are not spin locks; instead if the lock is taken
.I qlock
will suspend execution of the calling thread until it is released.
.PP
Although
.B Locks
are the more primitive lock, they have limitations; for example,
they cannot synchronize between tasks in the same
.IR proc .
Use
.B QLocks
instead.
.PP
.B RWLocks
manage access to a data structure that has distinct readers and writers.
.I Rlock
grants read access;
.I runlock
releases it.
.I Wlock
grants write access;
.I wunlock
releases it.
.I Canrlock
and
.I canwlock
are the non-blocking versions.
There may be any number of simultaneous readers,
but only one writer.
Moreover,
if write access is granted no one may have
read access until write access is released.
.PP
All types of lock should be initialized to all zeros before use; this
puts them in the unlocked state.
.PP
.B Rendezes
are rendezvous points.  Each
.B Rendez
.I r
is protected by a
.B QLock
.IB r -> l \fR,
which must be held by the callers of
.IR rsleep ,
.IR rwakeup ,
and
.IR rwakeupall .
.I Rsleep
atomically releases
.IB r -> l
and suspends execution of the calling task.
After resuming execution,
.I rsleep
will reacquire
.IB r -> l
before returning.
If any processes are sleeping on
.IR r ,
.I rwakeup
wakes one of them.
it returns 1 if a process was awakened, 0 if not.
.I Rwakeupall
wakes all processes sleeping on
.IR r ,
returning the number of processes awakened.
.I Rwakeup
and
.I rwakeupall
do not release
.IB r -> l
and do not suspend execution of the current task.
.PP
Before use,
.B Rendezes
should be initialized to all zeros except for
.IB r -> l
pointer, which should point at the
.B QLock
that will guard
.IR r .
.PP
A
.B Ref
contains a
.B long
that can be incremented and decremented atomically:
.I Incref
increments the
.I Ref
in one atomic operation.
.I Decref
atomically decrements the
.B Ref
and returns zero if the resulting value is zero, non-zero otherwise.
.SH SOURCE
.B \*9/src/lib9/qlock.c
.br
.B \*9/src/libthread
.SH BUGS
.B Locks
are not always spin locks.
Instead they are usually implemented using the 
.I pthreads
library's
.BR pthread_mutex_t ,
whose implementation method is not defined.
.PP
On
.IR pthreads -based
systems, the implementation of
.B Lock
never calls
.I pthread_mutex_destroy
to free the
.BR pthread_mutex_t 's.
This leads to resource leaks on FreeBSD 5
(though not on Linux 2.6, where
.I pthread_mutex_destroy
is a no-op).
.BR 
.PP
On systems that do not have a usable
.I pthreads
implementation, the
.B Lock
implementation provided by
.I libthread
is still not exactly a spin lock.
After each unsuccessful attempt,
.I lock
calls
.B sleep(0)
to yield the CPU; this handles the common case
where some other process holds the lock.
After a thousand unsuccessful attempts,
.I lock
sleeps for 100ms between attempts.
Another another thousand unsuccessful attempts,
.I lock
sleeps for a full second between attempts.
.B Locks
are not intended to be held for long periods of time.
The 100ms and full second sleeps are only heuristics to
avoid tying up the CPU when a process deadlocks.
As discussed above,
if a lock is to be held for much more than a few instructions,
the queueing lock types should be almost always be used.