man/dispatch_semaphore_create.3

   1 .\" Copyright (c) 2008-2010 Apple Inc. All rights reserved.
   2 .Dd May 1, 2009
   3 .Dt dispatch_semaphore_create 3
   4 .Os Darwin
   5 .Sh NAME
   6 .Nm dispatch_semaphore_create ,
   7 .Nm dispatch_semaphore_signal ,
   8 .Nm dispatch_semaphore_wait
   9 .Nd synchronized counting semaphore
  10 .Sh SYNOPSIS
  11 .Fd #include <dispatch/dispatch.h>
  12 .Ft dispatch_semaphore_t
  13 .Fo dispatch_semaphore_create
  14 .Fa "long count"
  15 .Fc
  16 .Ft long
  17 .Fo dispatch_semaphore_signal
  18 .Fa "dispatch_semaphore_t semaphore"
  19 .Fc
  20 .Ft long
  21 .Fo dispatch_semaphore_wait
  22 .Fa "dispatch_semaphore_t semaphore" "dispatch_time_t timeout"
  23 .Fc
  24 .Sh DESCRIPTION
  25 Dispatch semaphores are used to synchronize threads.
  26 The
  27 .Fa timeout
  28 parameter is creatable with the
  29 .Xr dispatch_time 3
  30 or
  31 .Xr dispatch_walltime 3
  32 functions.
  33 .Sh COMPLETION SYNCHRONIZATION
  34 If the
  35 .Fa count
  36 parameter is equal to zero, then the semaphore is useful for synchronizing
  37 completion of work.
  38 For example:
  39 .Bd -literal -offset indent
  40 sema = dispatch_semaphore_create(0);
  41
  42 dispatch_async(queue, ^{
  43         foo();
  44         dispatch_semaphore_signal(sema);
  45 });
  46
  47 bar();
  48
  49 dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
  50 .Ed
  51 .Sh FINITE RESOURCE POOL
  52 If the
  53 .Fa count
  54 parameter is greater than zero, then the semaphore is useful for managing a
  55 finite pool of resources.
  56 For example, a library that wants to limit Unix descriptor usage:
  57 .Bd -literal -offset indent
  58 sema = dispatch_semaphore_create(getdtablesize() / 4);
  59 .Ed
  60 .Pp
  61 At each Unix FD allocation:
  62 .Bd -literal -offset indent
  63 dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
  64 fd = open("/etc/services", O_RDONLY);
  65 .Ed
  66 .Pp
  67 When each FD is closed:
  68 .Bd -literal -offset indent
  69 close(fd);
  70 dispatch_semaphore_signal(sema);
  71 .Ed
  72 .Sh RETURN VALUES
  73 The
  74 .Fn dispatch_semaphore_create
  75 function returns NULL if no memory is available or if the
  76 .Fa count
  77 parameter is less than zero.
  78 .Pp
  79 The
  80 .Fn dispatch_semaphore_signal
  81 function returns non-zero when a thread is woken.
  82 Otherwise, zero is returned.
  83 .Pp
  84 The
  85 .Fn dispatch_semaphore_wait
  86 function returns zero upon success and non-zero after the timeout expires. If
  87 the timeout is DISPATCH_TIME_FOREVER, then
  88 .Fn dispatch_semaphore_wait
  89 waits forever and always returns zero.
  90 .Sh MEMORY MODEL
  91 Dispatch semaphores are retained and released via calls to
  92 .Fn dispatch_retain
  93 and
  94 .Fn dispatch_release .
  95 .Sh CAVEATS
  96 Unbalanced dispatch semaphores cannot be released.
  97 For a given semaphore, calls to
  98 .Fn dispatch_semaphore_signal
  99 and
 100 .Fn dispatch_semaphore_wait
 101 must be balanced before
 102 .Fn dispatch_release
 103 is called on it.
 104 .Pp
 105 Dispatch semaphores are strict counting semaphores.
 106 In other words, dispatch semaphores do not saturate at any particular value.
 107 Saturation can be achieved through atomic compare-and-swap logic.
 108 What follows is a saturating binary semaphore:
 109 .Bd -literal
 110 void
 111 saturating_semaphore_signal(dispatch_semaphore_t dsema, int *sent)
 112 {
 113         if (__sync_bool_compare_and_swap(sent, 0, 1)) {
 114                 dispatch_semaphore_signal(dsema);
 115         }
 116 }
 117
 118 void
 119 saturating_semaphore_wait(dispatch_semaphore_t dsema, int *sent)
 120 {
 121         *sent = 0;
 122         dispatch_semaphore_wait(dsema, DISPATCH_TIME_FOREVER);
 123 }
 124 .Ed
 125 .Sh SEE ALSO
 126 .Xr dispatch 3 ,
 127 .Xr dispatch_object 3