SYNOPSIS

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 Fc

DESCRIPTION

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