Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

dispatch_semaphore_create(3) [osx man page]

dispatch_semaphore_create(3)				   BSD Library Functions Manual 			      dispatch_semaphore_create(3)

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 parameter is creatable with the dispatch_time(3) or dispatch_walltime(3) functions. 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_FOR- EVER, 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 semaphore, 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

Check Out this Related Man Page

dispatch_semaphore_create(3)				   BSD Library Functions Manual 			      dispatch_semaphore_create(3)

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 parameter is creatable with the dispatch_time(3) or dispatch_walltime(3) functions. 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_FOR- EVER, 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
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); } SEE ALSO
dispatch(3), dispatch_object(3) Darwin May 1, 2009 Darwin
Man Page