man/dispatch_semaphore_create.3

   1 .\" Copyright (c) 2008-2012 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 .Pp
  27 The
  28 .Fn dispatch_semaphore_wait
  29 function decrements the semaphore. If the resulting value is less than zero,
  30 it waits for a signal from a thread that increments the semaphore by calling
  31 .Fn dispatch_semaphore_signal
  32 before returning.
  33 The
  34 .Fa timeout
  35 parameter is creatable with the
  36 .Xr dispatch_time 3
  37 or
  38 .Xr dispatch_walltime 3
  39 functions.
  40 .Pp
  41 The
  42 .Fn dispatch_semaphore_signal
  43 function increments the counting semaphore. If the previous value was less than zero,
  44 it wakes one of the threads that are waiting in
  45 .Fn dispatch_semaphore_wait
  46 before returning.
  47 .Sh COMPLETION SYNCHRONIZATION
  48 If the
  49 .Fa count
  50 parameter is equal to zero, then the semaphore is useful for synchronizing
  51 completion of work.
  52 For example:
  53 .Bd -literal -offset indent
  54 sema = dispatch_semaphore_create(0);
  55
  56 dispatch_async(queue, ^{
  57         foo();
  58         dispatch_semaphore_signal(sema);
  59 });
  60
  61 bar();
  62
  63 dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
  64 .Ed
  65 .Sh FINITE RESOURCE POOL
  66 If the
  67 .Fa count
  68 parameter is greater than zero, then the semaphore is useful for managing a
  69 finite pool of resources.
  70 For example, a library that wants to limit Unix descriptor usage:
  71 .Bd -literal -offset indent
  72 sema = dispatch_semaphore_create(getdtablesize() / 4);
  73 .Ed
  74 .Pp
  75 At each Unix FD allocation:
  76 .Bd -literal -offset indent
  77 dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
  78 fd = open("/etc/services", O_RDONLY);
  79 .Ed
  80 .Pp
  81 When each FD is closed:
  82 .Bd -literal -offset indent
  83 close(fd);
  84 dispatch_semaphore_signal(sema);
  85 .Ed
  86 .Sh RETURN VALUES
  87 The
  88 .Fn dispatch_semaphore_create
  89 function returns NULL if no memory is available or if the
  90 .Fa count
  91 parameter is less than zero.
  92 .Pp
  93 The
  94 .Fn dispatch_semaphore_signal
  95 function returns non-zero when a thread is woken.
  96 Otherwise, zero is returned.
  97 .Pp
  98 The
  99 .Fn dispatch_semaphore_wait
 100 function returns zero upon success and non-zero after the timeout expires. If
 101 the timeout is DISPATCH_TIME_FOREVER, then
 102 .Fn dispatch_semaphore_wait
 103 waits forever and always returns zero.
 104 .Sh MEMORY MODEL
 105 Dispatch semaphores are retained and released via calls to
 106 .Fn dispatch_retain
 107 and
 108 .Fn dispatch_release .
 109 .Sh CAVEATS
 110 Unbalanced dispatch semaphores cannot be released.
 111 For a given semaphore, calls to
 112 .Fn dispatch_semaphore_signal
 113 and
 114 .Fn dispatch_semaphore_wait
 115 must be balanced before
 116 .Fn dispatch_release
 117 is called on it.
 118 .Sh SEE ALSO
 119 .Xr dispatch 3 ,
 120 .Xr dispatch_object 3