GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  DISPATCH_SEMAPHORE_WAIT (3)

NAME

dispatch_semaphore_create, dispatch_semaphore_signal, dispatch_semaphore_wait - synchronized counting semaphore

CONTENTS

Synopsis
Description
Completion Synchronization
Finite Resource Pool
Return Values
Memory Model
Caveats
See Also

SYNOPSIS


.Fd #include <dispatch/dispatch.h> dispatch_semaphore_t
.Fo dispatch_semaphore_create long count
.Fc long
.Fo dispatch_semaphore_signal dispatch_semaphore_t semaphore
.Fc long
.Fo dispatch_semaphore_wait dispatch_semaphore_t semaphore dispatch_time_t timeout
.Fc

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_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

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)
Search for    or go to Top of page |  Section 3 |  Main Index


Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.