sys/man/9/qlock

   1 .TH QLOCK 9
   2 .SH NAME
   3 qlock, qunlock, canqlock, rlock, runlock, wlock, wunlock \- serial synchronisation
   4 .SH SYNOPSIS
   5 .de PB
   6 .PP
   7 .ft L
   8 .nf
   9 ..
  10 .PB
  11 typedef struct
  12 {
  13         Lock    use;                    /* to access Qlock structure */
  14         Proc    *head;          /* next process waiting for object */
  15         Proc    *tail;          /* last process waiting for object */
  16         int     locked;         /* flag */
  17 } QLock;
  18 .PB
  19 typedef struct
  20 {
  21         Lock            use;
  22         Proc            *head;  /* list of waiting processes */
  23         Proc            *tail;
  24         uintptr wpc;            /* pc of writer */
  25         Proc            *wproc; /* writing proc */
  26         int             readers;        /* number of readers */
  27         int             writer; /* number of writers */
  28 } RWlock;
  29 .ta \w'\fLvoid 'u
  30 .PP
  31 .B
  32 void    eqlock(QLock *l)
  33 .PP
  34 .B
  35 void    qlock(QLock *l)
  36 .PP
  37 .B
  38 void    qunlock(QLock *l)
  39 .PP
  40 .B
  41 int     canqlock(QLock *l)
  42 .PP
  43 .B
  44 void    rlock(RWlock *l)
  45 .PP
  46 .B
  47 void    runlock(RWlock *l)
  48 .PP
  49 .B
  50 int     canrlock(RWlock *l)
  51 .PP
  52 .B
  53 void    wlock(RWlock *l)
  54 .PP
  55 .B
  56 void    wunlock(RWlock *l)
  57 .SH DESCRIPTION
  58 The primitive locking functions described in
  59 .IR lock (9)
  60 guarantee mutual exclusion, but they implement spin locks,
  61 and should not be used if the process might
  62 .IR sleep (9)
  63 within a critical section.
  64 The following functions serialise access to a resource by forming an orderly
  65 queue of processes.
  66 .PP
  67 Each resource to be controlled is given an associated
  68 .B QLock
  69 structure; it is usually most straightforward to put the
  70 .B QLock
  71 in the structure that represents the resource.
  72 It must be initialised to zero before use
  73 (as guaranteed for global variables and for structures allocated by
  74 .IR malloc ).
  75 .PP
  76 On return from
  77 .IR qlock ,
  78 the process has acquired the lock
  79 .IR l ,
  80 and can assume exclusive access to the associated resource.
  81 If the lock is not immediately available, the requesting process is placed on a
  82 FIFO queue of processes that have requested the lock.
  83 Processes on this list are blocked in the
  84 .L Queueing
  85 state.
  86 .PP
  87 .I Eqlock
  88 is an interruptible form of
  89 .IR qlock.
  90 .PP
  91 .I Qunlock
  92 unlocks
  93 .I l
  94 and schedules the first process queued for it (if any).
  95 .PP
  96 .I Canqlock
  97 is a non-blocking form of
  98 .IR qlock .
  99 It tries to obtain the lock
 100 .I l
 101 and returns true if successful, and 0 otherwise;
 102 it always returns immediately.
 103 .PP
 104 .B RWlock
 105 is a form of lock for resources that have distinct readers and writers.
 106 It allows concurrent readers but gives each writer exclusive access.
 107 A caller announces its read or write intentions by choice of lock (and unlock) function;
 108 the system assumes the caller will not modify a structure accessed under read lock.
 109 .PP
 110 .I Rlock
 111 acquires
 112 .I l
 113 for reading.
 114 The holder can read but agrees not to modify the resource.
 115 There may be several concurrent readers.
 116 .I Canrlock
 117 is non-blocking: it returns non-zero if it successfully acquired the lock immediately,
 118 and 0 if the resource was unavailable.
 119 .PP
 120 .I Runlock
 121 returns a read lock;
 122 the last reader out enables the first writer waiting (if any).
 123 .PP
 124 .I Wlock
 125 acquires a write lock.
 126 The holder of such a lock may assume exclusive access to the resource,
 127 and is allowed to modify it.
 128 .PP
 129 .I Wunlock
 130 returns a write lock.
 131 The next pending process, whether reader or writer, is scheduled.
 132 .SH SOURCE
 133 .B /sys/src/9/port/qlock.c
 134 .br
 135 .SH SEE ALSO
 136 .IR lock (9),
 137 .IR malloc (9),
 138 .IR splhi (9)