table of contents
dispatch_time(3) | 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¶
Thedispatch_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¶
Thedispatch_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);
milestone = DISPATCH_TIME_FOREVER;
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 withdispatch_after
(),
dispatch_group_wait
(), or
dispatch_semaphore_wait
().
SEE ALSO¶
dispatch(3), dispatch_after(3), dispatch_group_create(3), dispatch_semaphore_create(3)May 1, 2009 | Darwin |