dispatch_walltime(3) [osx man page]

dispatch_time(3)					   BSD Library Functions Manual 					  dispatch_time(3)

NAME

     dispatch_time, dispatch_walltime -- Calculate temporal milestones

SYNOPSIS

     #include <dispatch/dispatch.h>

     static const dispatch_time_t DISPATCH_TIME_NOW = 0ull;
     static const dispatch_time_t DISPATCH_TIME_FOREVER = ~0ull;

     dispatch_time_t
     dispatch_time(dispatch_time_t base, int64_t offset);

     dispatch_time_t
     dispatch_walltime(struct timespec *base, int64_t offset);

DESCRIPTION

     The dispatch_time() and dispatch_walltime() functions provide a simple mechanism for expressing temporal milestones for use with dispatch
     functions that need timeouts or operate on a schedule.

     The dispatch_time_t type is a semi-opaque integer, with only the special values DISPATCH_TIME_NOW and DISPATCH_TIME_FOREVER being externally
     defined. All other values are represented using an internal format that is not safe for integer arithmetic or comparison.	The internal for-
     mat is subject to change.

     The dispatch_time() function returns a milestone relative to an existing milestone after adding offset nanoseconds.  If the base parameter
     maps internally to a wall clock, then the returned value is relative to the wall clock.  Otherwise, if base is DISPATCH_TIME_NOW, then the
     the current time of the default host clock is used.

     The dispatch_walltime() function is useful for creating a milestone relative to a fixed point in time using the wall clock, as specified by
     the optional base parameter. If base is NULL, then the current time of the wall clock is used.

EDGE CONDITIONS

     The dispatch_time() and dispatch_walltime() functions detect overflow and underflow conditions when applying the offset parameter.

     Overflow causes DISPATCH_TIME_FOREVER to be returned. When base is DISPATCH_TIME_FOREVER, then the offset parameter is ignored.

     Underflow causes the smallest representable value to be returned for a given clock.

CAVEATS

     Under the C language, untyped numbers default to the int type. This can lead to truncation bugs when arithmetic operations with other numbers
     are expected to generate a int64_t sized result, such as the offset argument to dispatch_time() and dispatch_walltime().  When in doubt, use
     ull as a suffix. For example:

	   3ull * NSEC_PER_SEC

EXAMPLES

     Create a milestone two seconds in the future:

	   milestone = dispatch_time(DISPATCH_TIME_NOW, 2LL * NSEC_PER_SEC);

     Create a milestone for use as an infinite timeout:

	   milestone = DISPATCH_TIME_FOREVER;

     Create a milestone on Tuesday, January 19, 2038:

	   struct timespec ts;
	   ts.tv_sec = 0x7FFFFFFF;
	   ts.tv_nsec = 0;
	   milestone = dispatch_walltime(&ts, 0);

RETURN VALUE

     These functions return an abstract value for use with dispatch_after(), dispatch_group_wait(), dispatch_semaphore_wait(), or
     dispatch_source_set_timer().

SEE ALSO

     dispatch(3), dispatch_after(3), dispatch_group_create(3), dispatch_semaphore_create(3)

Darwin								    May 1, 2009 							    Darwin

Check Out this Related Man Page

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

     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)

Darwin								    May 1, 2009 							    Darwin

Linux and UNIX Man Pages

dispatch_walltime(3) [osx man page]

Check Out this Related Man Page