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

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(3), dispatch_after(3), dispatch_group_create(3), dispatch_semaphore_create(3)

Darwin                                             May 1, 2009                                  dispatch_time(3)