Man page - dispatch_semaphore_create(3)
Packages contains this manual
- dispatch_queue_create(3)
- dispatch_time(3)
- dispatch_read(3)
- dispatch_semaphore_create(3)
- dispatch_async(3)
- dispatch_io_create(3)
- dispatch_data_create(3)
- dispatch_source_create(3)
- dispatch_io_read(3)
- dispatch_once(3)
- dispatch_apply(3)
- dispatch_api(3)
- dispatch(3)
- dispatch_after(3)
- dispatch_object(3)
- dispatch_group_create(3)
apt-get install libdispatch-dev
Manual
dispatch_semaphore_creat (3) Library Functions Manual dispatch_semaphore_creat (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 dispatch_semaphore_wait () function decrements the semaphore. If the resulting value is less than zero, it waits for a signal from a thread that increments the semaphore by calling dispatch_semaphore_signal () before returning. The timeout parameter is creatable with the dispatch_time (3) or dispatch_walltime (3) functions. If the timeout is reached without a signal being received, the semaphore is re-incremented before the function returns.
The dispatch_semaphore_signal () function increments the counting semaphore. If the previous value was less than zero, it wakes one of the threads that are waiting in dispatch_semaphore_wait () before returning.
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 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 dispatch_semaphore_create (3)