Other Alias
dispatch_semaphore_create, dispatch_semaphore_signalSYNOPSIS
Fd #include <dispatch/dispatch.h> Ft dispatch_semaphore_t Fo dispatch_semaphore_create Fa long count Fc Ft long Fo dispatch_semaphore_signal Fa dispatch_semaphore_t semaphore Fc Ft long Fo dispatch_semaphore_wait Fa dispatch_semaphore_t semaphore dispatch_time_t timeout FcDESCRIPTION
Dispatch semaphores are used to synchronize threads. The Fa timeout parameter is creatable with the dispatch_time3 or dispatch_walltime3 functions.COMPLETION SYNCHRONIZATION
If the Fa 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 Fa 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 Fn dispatch_semaphore_create function returns NULL if no memory is available or if the Fa count parameter is less than zero.The Fn dispatch_semaphore_signal function returns non-zero when a thread is woken. Otherwise, zero is returned.
The Fn dispatch_semaphore_wait function returns zero upon success and non-zero after the timeout expires. If the timeout is DISPATCH_TIME_FOREVER, then Fn dispatch_semaphore_wait waits forever and always returns zero.
MEMORY MODEL
Dispatch semaphores are retained and released via calls to Fn dispatch_retain and Fn dispatch_release .CAVEATS
Dispatch semaphores are strict counting semaphores. In other words, dispatch semaphores do not saturate at any particular value. Saturation can be achieved through atomic compare-and-swap logic. What follows is a saturating binary semaphore:void saturating_semaphore_signal(dispatch_semaphore_t dsema, int *sent) { if (__sync_bool_compare_and_swap(sent, 0, 1)) { dispatch_semaphore_signal(dsema); } } void saturating_semaphore_wait(dispatch_semaphore_t dsema, int *sent) { *sent = 0; dispatch_semaphore_wait(dsema, DISPATCH_TIME_FOREVER); }