_lwp_sema_init(2) [sunos man page]

_lwp_sema_wait(2)						   System Calls 						 _lwp_sema_wait(2)

NAME

       _lwp_sema_wait, _lwp_sema_trywait, _lwp_sema_init, _lwp_sema_post - semaphore operations

SYNOPSIS

       #include <sys/lwp.h>

       int _lwp_sema_wait(lwp_sema_t *sema);

       int _lwp_sema_trywait(lwp_sema_t *sema);

       int _lwp_sema_init(lwp_sema_t *sema, int count);

       int _lwp_sema_post(lwp_sema_t *sema);

DESCRIPTION

       Conceptually,  a  semaphore  is an non-negative integer count that is atomically incremented and decremented. Typically this represents the
       number of resources available. The _lwp_sema_init() function initializes the count, _lwp_sema_post() atomically increments the  count,  and
       _lwp_sema_wait() waits for the count to become greater than 0 and then atomically decrements it.

       LWP  semaphores	must  be  initialized  before  use.  The _lwp_sema_init() function initializes the count associated with the LWP semaphore
       pointed to by sema to count.

       The _lwp_sema_wait() function blocks the calling LWP until the semaphore count becomes greater than 0 and then atomically decrements it.

       The _lwp_sema_trywait() function atomically decrements the count if it is greater than zero. Otherwise it returns an error.

       The _lwp_sema_post() function atomically increments the semaphore count. If there are any LWPs blocked on the semaphore, one is unblocked.

RETURN VALUES

       Upon successful completion, 0 is returned. A non-zero value indicates an error.

ERRORS

       The _lwp_sema_init(), _lwp_sema_trywait(), _lwp_sema_wait(), and _lwp_sema_post() functions will fail if:

       EINVAL	       The sema argument points to an invalid semaphore.

       EFAULT	       The sema argument points to an illegal address.

       The  _lwp_sema_wait() function will fail if:

       EINTR	       The function execution was interrupted by a signal or fork(2).

       The  _lwp_sema_trywait() function will fail if:

       EBUSY	       The function was called on a semaphore with a zero count.

       The  _lwp_sema_post() function will fail if:

       EOVERFLOW       The value of the sema argument exceeds SEM_VALUE_MAX.

SEE ALSO

       fork(2)

SunOS 5.10							    8 May 1998							 _lwp_sema_wait(2)

dispatch_semaphore_create(3)				   BSD Library Functions Manual 			      dispatch_semaphore_create(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.

     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_FOR-
     EVER, 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 							    Darwin