1dispatch_time(3)         BSD Library Functions Manual         dispatch_time(3)
2

NAME

4     dispatch_time, dispatch_walltime — Calculate temporal milestones
5

SYNOPSIS

7     #include <dispatch/dispatch.h>
8
9     static const dispatch_time_t DISPATCH_TIME_NOW = 0ull;
10     static const dispatch_time_t DISPATCH_WALLTIME_NOW = ~1ull;
11     static const dispatch_time_t DISPATCH_TIME_FOREVER = ~0ull;
12
13     dispatch_time_t
14     dispatch_time(dispatch_time_t base, int64_t offset);
15
16     dispatch_time_t
17     dispatch_walltime(struct timespec *base, int64_t offset);
18

DESCRIPTION

20     The dispatch_time() and dispatch_walltime() functions provide a simple
21     mechanism for expressing temporal milestones for use with dispatch func‐
22     tions that need timeouts or operate on a schedule.
23
24     The dispatch_time_t type is a semi-opaque integer, with only the special
25     values DISPATCH_TIME_NOW, DISPATCH_WALLTIME_NOW and DISPATCH_TIME_FOREVER
26     being externally defined. All other values are represented using an
27     internal format that is not safe for integer arithmetic or comparison.
28     The internal format is subject to change.
29
30     The dispatch_time() function returns a milestone relative to an existing
31     milestone after adding offset nanoseconds.  If the base parameter maps
32     internally to a wall clock or is DISPATCH_WALLTIME_NOW, then the returned
33     value is relative to the wall clock.  Otherwise, if base is
34     DISPATCH_TIME_NOW, then the current time of the default host clock is
35     used. On Apple platforms, the value of the default host clock is obtained
36     from mach_absolute_time().
37
38     The dispatch_walltime() function is useful for creating a milestone rela‐
39     tive to a fixed point in time using the wall clock, as specified by the
40     optional base parameter. If base is NULL, then the current time of the
41     wall clock is used.  dispatch_walltime(NULL, offset) is equivalent to
42     dispatch_time(DISPATCH_WALLTIME_NOW, offset).
43

EDGE CONDITIONS

45     The dispatch_time() and dispatch_walltime() functions detect overflow and
46     underflow conditions when applying the offset parameter.
47
48     Overflow causes DISPATCH_TIME_FOREVER to be returned. When base is
49     DISPATCH_TIME_FOREVER, then the offset parameter is ignored.
50
51     Underflow causes the smallest representable value to be returned for a
52     given clock.
53

EXAMPLES

55     Create a milestone two seconds in the future, relative to the default
56     clock:
57
58           milestone = dispatch_time(DISPATCH_TIME_NOW, 2 * NSEC_PER_SEC);
59
60     Create a milestone two seconds in the future, in wall clock time:
61
62           milestone = dispatch_time(DISPATCH_WALLTIME_NOW, 2 * NSEC_PER_SEC);
63
64     Create a milestone for use as an infinite timeout:
65
66           milestone = DISPATCH_TIME_FOREVER;
67
68     Create a milestone on Tuesday, January 19, 2038:
69
70           struct timespec ts;
71           ts.tv_sec = 0x7FFFFFFF;
72           ts.tv_nsec = 0;
73           milestone = dispatch_walltime(&ts, 0);
74
75     Use a negative delta to create a milestone an hour before the one above:
76
77           milestone = dispatch_walltime(&ts, -60 * 60 * NSEC_PER_SEC);
78

RETURN VALUE

80     These functions return an abstract value for use with dispatch_after(),
81     dispatch_group_wait(), dispatch_semaphore_wait(), or
82     dispatch_source_set_timer().
83

SEE ALSO

85     dispatch(3), dispatch_after(3), dispatch_group_create(3),
86     dispatch_semaphore_create(3)
87
88Darwin                            May 1, 2009                           Darwin
Impressum