.\" Copyright (c) 2008-2013 Apple Inc. All rights reserved.
.Dd May 1, 2009
.Dt dispatch_time 3
.Os Darwin
.Sh NAME
.Nm dispatch_time ,
.Nm dispatch_walltime
.Nd Calculate temporal milestones
.Sh SYNOPSIS
.Fd #include <dispatch/dispatch.h>
.Vt static const dispatch_time_t DISPATCH_TIME_NOW = 0ull ;
.Vt static const dispatch_time_t DISPATCH_WALLTIME_NOW = ~1ull ;
.Vt static const dispatch_time_t DISPATCH_TIME_FOREVER = ~0ull ;
.Ft dispatch_time_t
.Fo dispatch_time
.Fa "dispatch_time_t base" "int64_t offset"
.Fc
.Ft dispatch_time_t
.Fo dispatch_walltime
.Fa "struct timespec *base" "int64_t offset"
.Fc
.Sh DESCRIPTION
The
.Fn dispatch_time
and
.Fn dispatch_walltime
functions provide a simple mechanism for expressing temporal milestones for use
with dispatch functions that need timeouts or operate on a schedule.
.Pp
The
.Fa dispatch_time_t
type is a semi-opaque integer, with only the special values
.Vt DISPATCH_TIME_NOW ,
.Vt DISPATCH_WALLTIME_NOW
and
.Vt 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.
.Pp
The
.Fn dispatch_time
function returns a milestone relative to an existing milestone after adding
.Fa offset
nanoseconds.
If the
.Fa base
parameter maps internally to a wall clock or is
.Vt DISPATCH_WALLTIME_NOW ,
then the returned value is relative to the wall clock.
Otherwise, if
.Fa base
is
.Vt DISPATCH_TIME_NOW ,
then the current time of the default host clock is used. On Apple platforms,
the value of the default host clock is obtained from
.Vt mach_absolute_time() .
.Pp
The
.Fn 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
.Fa base
parameter. If
.Fa base
is NULL, then the current time of the wall clock is used.
.Vt dispatch_walltime(NULL, offset)
is equivalent to
.Vt dispatch_time(DISPATCH_WALLTIME_NOW, offset) .
.Sh EDGE CONDITIONS
The
.Fn dispatch_time
and
.Fn dispatch_walltime
functions detect overflow and underflow conditions when applying the
.Fa offset
parameter.
.Pp
Overflow causes
.Vt DISPATCH_TIME_FOREVER
to be returned. When
.Fa base
is
.Vt DISPATCH_TIME_FOREVER ,
then the
.Fa offset
parameter is ignored.
.Pp
Underflow causes the smallest representable value to be
returned for a given clock.
.Sh EXAMPLES
Create a milestone two seconds in the future, relative to the default clock:
.Bd -literal -offset indent
milestone = dispatch_time(DISPATCH_TIME_NOW, 2 * NSEC_PER_SEC);
.Ed
.Pp
Create a milestone two seconds in the future, in wall clock time:
.Bd -literal -offset indent
milestone = dispatch_time(DISPATCH_WALLTIME_NOW, 2 * NSEC_PER_SEC);
.Ed
.Pp
Create a milestone for use as an infinite timeout:
.Bd -literal -offset indent
milestone = DISPATCH_TIME_FOREVER;
.Ed
.Pp
Create a milestone on Tuesday, January 19, 2038:
.Bd -literal -offset indent
struct timespec ts;
ts.tv_sec = 0x7FFFFFFF;
ts.tv_nsec = 0;
milestone = dispatch_walltime(&ts, 0);
.Ed
.Pp
Use a negative delta to create a milestone an hour before the one above:
.Bd -literal -offset indent
milestone = dispatch_walltime(&ts, -60 * 60 * NSEC_PER_SEC);
.Ed
.Sh RETURN VALUE
These functions return an abstract value for use with
.Fn dispatch_after ,
.Fn dispatch_group_wait ,
.Fn dispatch_semaphore_wait ,
or
.Fn dispatch_source_set_timer .
.Sh SEE ALSO
.Xr dispatch 3 ,
.Xr dispatch_after 3 ,
.Xr dispatch_group_create 3 ,
.Xr dispatch_semaphore_create 3