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 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 .Sh SEE ALSO
 105 .Xr dispatch 3 ,
 106 .Xr dispatch_object 3