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

SEE ALSO

dispatch(3), dispatch_object(3)

CAVEATS

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.