223 lines
9.8 KiB
HTML
223 lines
9.8 KiB
HTML
|
<head>
|
||
|
|
<title>lock(3) - Plan 9 from User Space</title>
|
||
|
|
<meta content="text/html; charset=utf-8" http-equiv=Content-Type>
|
||
|
|
</head>
|
||
|
|
<body bgcolor=#ffffff>
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0 width=100%>
|
||
|
|
<tr height=10><td>
|
||
|
|
<tr><td width=20><td>
|
||
|
|
<tr><td width=20><td><b>LOCK(3)</b><td align=right><b>LOCK(3)</b>
|
||
|
|
<tr><td width=20><td colspan=2>
|
||
|
|
<br>
|
||
|
|
<p><font size=+1><b>NAME </b></font><br>
|
||
|
|
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||
|
|
|
||
|
|
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<br>
|
||
|
|
|
||
|
|
</table>
|
||
|
|
<p><font size=+1><b>SYNOPSIS </b></font><br>
|
||
|
|
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||
|
|
|
||
|
|
<tt><font size=+1>#include <u.h><br>
|
||
|
|
#include <libc.h><br>
|
||
|
|
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
void lock(Lock *l)<br>
|
||
|
|
int canlock(Lock *l)<br>
|
||
|
|
void unlock(Lock *l)<br>
|
||
|
|
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
void qlock(QLock *l)<br>
|
||
|
|
int canqlock(QLock *l)<br>
|
||
|
|
void qunlock(QLock *l)<br>
|
||
|
|
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
void rlock(RWLock *l)<br>
|
||
|
|
int canrlock(RWLock *l)<br>
|
||
|
|
void runlock(RWLock *l)<br>
|
||
|
|
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
void wlock(RWLock *l)<br>
|
||
|
|
int canwlock(RWLock *l)<br>
|
||
|
|
void wunlock(RWLock *l)<br>
|
||
|
|
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
typedef struct Rendez {<br>
|
||
|
|
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||
|
|
|
||
|
|
QLock *l;<br>
|
||
|
|
|
||
|
|
</table>
|
||
|
|
</font></tt>
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||
|
|
|
||
|
|
<i>...<br>
|
||
|
|
</i>
|
||
|
|
</table>
|
||
|
|
<tt><font size=+1>} Rendez;<br>
|
||
|
|
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
void rsleep(Rendez *r)<br>
|
||
|
|
int rwakeup(Rendez *r)<br>
|
||
|
|
int rwakeupall(Rendez *r)<br>
|
||
|
|
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
#include <thread.h><br>
|
||
|
|
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
typedef struct Ref {<br>
|
||
|
|
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||
|
|
|
||
|
|
long ref;<br>
|
||
|
|
|
||
|
|
</table>
|
||
|
|
} Ref;<br>
|
||
|
|
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
void incref(Ref*)<br>
|
||
|
|
long decref(Ref*)<br>
|
||
|
|
</font></tt>
|
||
|
|
</table>
|
||
|
|
<p><font size=+1><b>DESCRIPTION </b></font><br>
|
||
|
|
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||
|
|
|
||
|
|
These routines are used to synchronize processes sharing memory.
|
||
|
|
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
<tt><font size=+1>Locks</font></tt> are spin locks, <tt><font size=+1>QLocks</font></tt> and <tt><font size=+1>RWLocks</font></tt> are different types of
|
||
|
|
queueing locks, and <tt><font size=+1>Rendezes</font></tt> are rendezvous points.
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
Locks and rendezvous points have trivial implementations in programs
|
||
|
|
not using the thread library (see <a href="../man3/thread.html"><i>thread</i>(3)</a>), since such programs
|
||
|
|
have no concurrency.
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
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.
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
<i>Lock</i> blocks until the lock has been obtained. <i>Canlock</i> is non-blocking.
|
||
|
|
It tries to obtain a lock and returns a non-zero value if it was
|
||
|
|
successful, 0 otherwise. <i>Unlock</i> releases a lock.
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
<tt><font size=+1>QLocks</font></tt> have the same interface but are not spin locks; instead
|
||
|
|
if the lock is taken <i>qlock</i> will suspend execution of the calling
|
||
|
|
thread until it is released.
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
Although <tt><font size=+1>Locks</font></tt> are the more primitive lock, they have limitations;
|
||
|
|
for example, they cannot synchronize between tasks in the same
|
||
|
|
<i>proc</i>. Use <tt><font size=+1>QLocks</font></tt> instead.
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
<tt><font size=+1>RWLocks</font></tt> manage access to a data structure that has distinct readers
|
||
|
|
and writers. <i>Rlock</i> grants read access; <i>runlock</i> releases it. <i>Wlock</i>
|
||
|
|
grants write access; <i>wunlock</i> releases it. <i>Canrlock</i> and <i>canwlock</i>
|
||
|
|
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.
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
All types of lock should be initialized to all zeros before use;
|
||
|
|
this puts them in the unlocked state.
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
<tt><font size=+1>Rendezes</font></tt> are rendezvous points. Each <tt><font size=+1>Rendez</font></tt> <i>r</i> is protected by
|
||
|
|
a <tt><font size=+1>QLock</font></tt> <i>r</i><tt><font size=+1>−></font></tt><i>l</i>, which must be held by the callers of <i>rsleep</i>, <i>rwakeup</i>,
|
||
|
|
and <i>rwakeupall</i>. <i>Rsleep</i> atomically releases <i>r</i><tt><font size=+1>−></font></tt><i>l</i> and suspends execution
|
||
|
|
of the calling task. After resuming execution, <i>rsleep</i> will reacquire
|
||
|
|
<i>r</i><tt><font size=+1>−></font></tt><i>l</i> before returning. If any processes
|
||
|
|
are sleeping on <i>r</i>, <i>rwakeup</i> wakes one of them. it returns 1 if
|
||
|
|
a process was awakened, 0 if not. <i>Rwakeupall</i> wakes all processes
|
||
|
|
sleeping on <i>r</i>, returning the number of processes awakened. <i>Rwakeup</i>
|
||
|
|
and <i>rwakeupall</i> do not release <i>r</i><tt><font size=+1>−></font></tt><i>l</i> and do not suspend execution
|
||
|
|
of the current task.
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
Before use, <tt><font size=+1>Rendezes</font></tt> should be initialized to all zeros except
|
||
|
|
for <i>r</i><tt><font size=+1>−></font></tt><i>l</i> pointer, which should point at the <tt><font size=+1>QLock</font></tt> that will guard
|
||
|
|
<i>r</i>.
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
A <tt><font size=+1>Ref</font></tt> contains a <tt><font size=+1>long</font></tt> that can be incremented and decremented
|
||
|
|
atomically: <i>Incref</i> increments the <i>Ref</i> in one atomic operation.
|
||
|
|
<i>Decref</i> atomically decrements the <tt><font size=+1>Ref</font></tt> and returns zero if the resulting
|
||
|
|
value is zero, non-zero otherwise.<br>
|
||
|
|
|
||
|
|
</table>
|
||
|
|
<p><font size=+1><b>SOURCE </b></font><br>
|
||
|
|
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||
|
|
|
||
|
|
<tt><font size=+1>/usr/local/plan9/src/lib9/qlock.c<br>
|
||
|
|
/usr/local/plan9/src/libthread<br>
|
||
|
|
</font></tt>
|
||
|
|
</table>
|
||
|
|
<p><font size=+1><b>BUGS </b></font><br>
|
||
|
|
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td>
|
||
|
|
|
||
|
|
<tt><font size=+1>Locks</font></tt> are not always spin locks. Instead they are usually implemented
|
||
|
|
using the <i>pthreads</i> library’s <tt><font size=+1>pthread_mutex_t</font></tt>, whose implementation
|
||
|
|
method is not defined.
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
On <i>pthreads</i>-based systems, the implementation of <tt><font size=+1>Lock</font></tt> never calls
|
||
|
|
<i>pthread_mutex_destroy</i> to free the <tt><font size=+1>pthread_mutex_t</font></tt>’s. This leads
|
||
|
|
to resource leaks on FreeBSD 5 (though not on Linux 2.6, where
|
||
|
|
<i>pthread_mutex_destroy</i> is a no-op).
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table>
|
||
|
|
|
||
|
|
On systems that do not have a usable <i>pthreads</i> implementation,
|
||
|
|
the <tt><font size=+1>Lock</font></tt> implementation provided by <i>libthread</i> is still not exactly
|
||
|
|
a spin lock. After each unsuccessful attempt, <i>lock</i> calls <tt><font size=+1>sleep(0)</font></tt>
|
||
|
|
to yield the CPU; this handles the common case where some other
|
||
|
|
process holds the lock. After a thousand
|
||
|
|
unsuccessful attempts, <i>lock</i> sleeps for 100ms between attempts.
|
||
|
|
Another another thousand unsuccessful attempts, <i>lock</i> sleeps for
|
||
|
|
a full second between attempts. <tt><font size=+1>Locks</font></tt> 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.<br>
|
||
|
|
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<td width=20>
|
||
|
|
<tr height=20><td>
|
||
|
|
</table>
|
||
|
|
<!-- TRAILER -->
|
||
|
|
<table border=0 cellpadding=0 cellspacing=0 width=100%>
|
||
|
|
<tr height=15><td width=10><td><td width=10>
|
||
|
|
<tr><td><td>
|
||
|
|
<center>
|
||
|
|
<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a>
|
||
|
|
</center>
|
||
|
|
</table>
|
||
|
|
<!-- TRAILER -->
|
||
|
|
</body></html>
|