sys/man/2/semacquire

   1 .TH SEMACQUIRE 2
   2 .SH NAME
   3 semacquire, tsemacquire, semrelease - user level semaphores
   4 .SH SYNOPSIS
   5 .B #include <u.h>
   6 .br
   7 .B #include <libc.h>
   8 .PP
   9 .B
  10 int semacquire(long *addr, int block);
  11 .PP
  12 .B
  13 int tsemacquire(long *addr, ulong ms);
  14 .PP
  15 .B
  16 long semrelease(long *addr, long count);
  17 .SH DESCRIPTION
  18 .IR Semacquire ,
  19 .IR tsemacquire ,
  20 and
  21 .I semrelease
  22 facilitate scheduling between processes sharing memory.
  23 Processes arrange to share memory by using
  24 .I rfork
  25 with the
  26 .B RFMEM
  27 flag
  28 (see
  29 .IR fork (2)),
  30 .IR segattach (2),
  31 or
  32 .IR thread (2).
  33 .PP
  34 The semaphore's value is the integer pointed at by
  35 .IR addr .
  36 .I Semacquire
  37 atomically waits until the semaphore has a positive value
  38 and then decrements that value.
  39 If
  40 .I block
  41 is zero
  42 and the semaphore is not immediately available,
  43 .I semacquire
  44 returns 0 instead of waiting.
  45 .I Tsemacquire
  46 only waits
  47 .I ms
  48 milliseconds for the semaphore to attain a positive value
  49 and, if available in that time, decrements that value.
  50 It returns 0 otherwise.
  51 Both functions return 1 if the semaphore was acquired
  52 and -1 on error
  53 (e.g., if they were interrupted).
  54 .I Semrelease
  55 adds
  56 .I count
  57 to the semaphore's value
  58 and returns the new value.
  59 .PP
  60 .I Semacquire
  61 (and analogously for
  62 .IR tsemacquire )
  63 and
  64 .I semrelease
  65 can be thought of as efficient, correct replacements for:
  66 .IP
  67 .EX
  68 int
  69 semacquire(long *addr, int block)
  70 {
  71         while(*addr == 0){
  72                 if(!block)
  73                         return 0;
  74                 if(interrupted)
  75                         return -1;
  76         }
  77         --*addr;
  78         return 1;
  79 }
  80
  81 int
  82 semrelease(long *addr, int count)
  83 {
  84         return *addr += count;
  85 }
  86 .EE
  87 .PP
  88 Like
  89 .IR rendezvous (2),
  90 .IR semacquire ,
  91 .IR tsemacquire ,
  92 and
  93 .I semrelease
  94 are not typically used directly.
  95 Instead, they are intended to be used to coordinate
  96 scheduling in higher-level abstractions such as
  97 locks, rendezvous points, and channels
  98 (see
  99 .IR lock (2)
 100 and
 101 .IR thread (2)).
 102 Also like
 103 .IR rendezvous ,
 104 .IR semacquire ,
 105 .IR tsemacquire ,
 106 and
 107 .I semrelease
 108 cannot be used to coordinate between threads
 109 in a single process.
 110 Use locks, rendezvous points, or channels instead.
 111 .SH SOURCE
 112 .B /sys/src/9/port/sysproc.c
 113 .SH SEE ALSO
 114 .IR fork (2),
 115 .IR lock (2),
 116 .IR rendezvous (2),
 117 .IR segattach (2),
 118 .IR thread (2)
 119 .SH DIAGNOSTICS
 120 These functions set
 121 .IR errstr .