This manual page is for Mac OS X version 10.6

Reading manual pages

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 = 0;
     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 tempo-ral temporal
     ral 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 for-mat format
     mat that is not safe for integer arithmetic or comparison.  The internal format 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 rela-tive relative
     tive 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.

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(), or
     dispatch_semaphore_wait().

SEE ALSO
     dispatch_after(3), dispatch_group_create(3), dispatch_semaphore_create(3)

Darwin                                           May 1, 2009                                          Darwin