dispatch_semaphore_create(3) Library Functions Manual dispatch_semaphore_create(3)

dispatch_semaphore_create, dispatch_semaphore_signal, dispatch_semaphore_wait — synchronized counting semaphore

#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);

Dispatch semaphores are used to synchronize threads.

The () 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 () 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.

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);

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);

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.

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

dispatch(3), dispatch_object(3)

Unbalanced dispatch semaphores cannot be released. For a given semaphore, the count at the time dispatch_release() is called must be equal to or larger than the count the semaphore was created with. In other words, at the time of releasing the semaphore, there must have been at least as many dispatch_semaphore_signal() calls as there were successful dispatch_semaphore_wait() calls that did not timeout.

May 1, 2009 Darwin