dispatch_time

Section: C Library Functions (3)
Page Index

BSD mandoc
Darwin

NAME

dispatch_time dispatch_walltime - Calculate temporal milestones

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

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.

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.

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

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

EDGE CONDITIONS

The Fn dispatch_time and Fn dispatch_walltime functions detect overflow and underflow conditions when applying the Fa offset parameter.

Overflow causes Vt DISPATCH_TIME_FOREVER to be returned. When Fa base is Vt DISPATCH_TIME_FOREVER , then the Fa 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, relative to the default clock:

milestone = dispatch_time(DISPATCH_TIME_NOW, 2 * NSEC_PER_SEC);

Create a milestone two seconds in the future, in wall clock time:

milestone = dispatch_time(DISPATCH_WALLTIME_NOW, 2 * 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);

Use a negative delta to create a milestone an hour before the one above:

milestone = dispatch_walltime(&ts, -60 * 60 * NSEC_PER_SEC);

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 .