manpagez: man pages & more
man dispatch_semaphore_create(3)
Home | html | info | man
dispatch_semaphore_cr... BSD Library Functions Manual dispatch_semaphore_cr...


NAME

     dispatch_semaphore_create, dispatch_semaphore_signal,
     dispatch_semaphore_wait -- synchronized counting semaphore


SYNOPSIS

     #include <dispatch/dispatch.h>

     dispatch_semaphore_t
     dispatch_semaphore_create(long count);

     long
     dispatch_semaphore_signal(dispatch_semaphore_t semaphore);

     long
     dispatch_semaphore_wait(dispatch_semaphore_t semaphore,
         dispatch_time_t timeout);


DESCRIPTION

     Dispatch semaphores are used to synchronize threads.  The timeout parame-
     ter is creatable with the dispatch_time(3) or dispatch_walltime(3) func-
     tions.


COMPLETION SYNCHRONIZATION

     If the count parameter is equal to zero, then the semaphore is useful for
     synchronizing completion of work.  For example:

           sema = dispatch_semaphore_create(0);

           dispatch_async(queue, ^{
                   foo();
                   dispatch_semaphore_signal(sema);
           });

           bar();

           dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);


FINITE RESOURCE POOL

     If the count parameter is greater than zero, then the semaphore is useful
     for managing a finite pool of resources.  For example, a library that
     wants to limit Unix descriptor usage:

           sema = dispatch_semaphore_create(getdtablesize() / 4);

     At each Unix FD allocation:

           dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
           fd = open("/etc/services", O_RDONLY);

     When each FD is closed:

           close(fd);
           dispatch_semaphore_signal(sema);


RETURN VALUES

     The dispatch_semaphore_create() function returns NULL if no memory is
     available or if the count parameter is less than zero.

     The dispatch_semaphore_signal() function returns non-zero when a thread
     is woken.  Otherwise, zero is returned.

     The dispatch_semaphore_wait() function returns zero upon success and non-
     zero after the timeout expires. If the timeout is DISPATCH_TIME_FOREVER,
     then dispatch_semaphore_wait() waits forever and always returns zero.


MEMORY MODEL

     Dispatch semaphores are retained and released via calls to
     dispatch_retain() and dispatch_release().


CAVEATS

     Unbalanced dispatch semaphores cannot be released.  For a given sema-
     phore, calls to dispatch_semaphore_signal() and dispatch_semaphore_wait()
     must be balanced before dispatch_release() is called on it.


SEE ALSO

     dispatch(3), dispatch_object(3)

Darwin                            May 1, 2009                           Darwin

Mac OS X 10.8 - Generated Sat Aug 25 17:59:47 CDT 2012
© manpagez.com 2000-2021
Individual documents may contain additional copyright information.