]> git.saurik.com Git - apple/libdispatch.git/blob - man/dispatch_time.3
libdispatch-703.1.4.tar.gz
[apple/libdispatch.git] / man / dispatch_time.3
1 .\" Copyright (c) 2008-2013 Apple Inc. All rights reserved.
2 .Dd May 1, 2009
3 .Dt dispatch_time 3
4 .Os Darwin
5 .Sh NAME
6 .Nm dispatch_time ,
7 .Nm dispatch_walltime
8 .Nd Calculate temporal milestones
9 .Sh SYNOPSIS
10 .Fd #include <dispatch/dispatch.h>
11 .Vt static const dispatch_time_t DISPATCH_TIME_NOW = 0ull ;
12 .Vt static const dispatch_time_t DISPATCH_TIME_FOREVER = ~0ull ;
13 .Ft dispatch_time_t
14 .Fo dispatch_time
15 .Fa "dispatch_time_t base" "int64_t offset"
16 .Fc
17 .Ft dispatch_time_t
18 .Fo dispatch_walltime
19 .Fa "struct timespec *base" "int64_t offset"
20 .Fc
21 .Sh DESCRIPTION
22 The
23 .Fn dispatch_time
24 and
25 .Fn dispatch_walltime
26 functions provide a simple mechanism for expressing temporal milestones for use
27 with dispatch functions that need timeouts or operate on a schedule.
28 .Pp
29 The
30 .Fa dispatch_time_t
31 type is a semi-opaque integer, with only the special values
32 .Vt DISPATCH_TIME_NOW
33 and
34 .Vt DISPATCH_TIME_FOREVER
35 being externally defined. All other values are represented using an internal
36 format that is not safe for integer arithmetic or comparison.
37 The internal format is subject to change.
38 .Pp
39 The
40 .Fn dispatch_time
41 function returns a milestone relative to an existing milestone after adding
42 .Fa offset
43 nanoseconds.
44 If the
45 .Fa base
46 parameter maps internally to a wall clock, then the returned value is
47 relative to the wall clock.
48 Otherwise, if
49 .Fa base
50 is
51 .Vt DISPATCH_TIME_NOW ,
52 then the current time of the default host clock is used.
53 .Pp
54 The
55 .Fn dispatch_walltime
56 function is useful for creating a milestone relative to a fixed point in time
57 using the wall clock, as specified by the optional
58 .Fa base
59 parameter. If
60 .Fa base
61 is NULL, then the current time of the wall clock is used.
62 .Sh EDGE CONDITIONS
63 The
64 .Fn dispatch_time
65 and
66 .Fn dispatch_walltime
67 functions detect overflow and underflow conditions when applying the
68 .Fa offset
69 parameter.
70 .Pp
71 Overflow causes
72 .Vt DISPATCH_TIME_FOREVER
73 to be returned. When
74 .Fa base
75 is
76 .Vt DISPATCH_TIME_FOREVER ,
77 then the
78 .Fa offset
79 parameter is ignored.
80 .Pp
81 Underflow causes the smallest representable value to be
82 returned for a given clock.
83 .Sh CAVEATS
84 Under the C language, untyped numbers default to the
85 .Vt int
86 type. This can lead to truncation bugs when arithmetic operations with other
87 numbers are expected to generate a
88 .Vt int64_t
89 sized result, such as the
90 .Fa offset
91 argument to
92 .Fn dispatch_time
93 and
94 .Fn dispatch_walltime .
95 When in doubt, use
96 .Vt ull
97 as a suffix. For example:
98 .Bd -literal -offset indent
99 3ull * NSEC_PER_SEC
100 .Ed
101 .Sh EXAMPLES
102 Create a milestone two seconds in the future:
103 .Bd -literal -offset indent
104 milestone = dispatch_time(DISPATCH_TIME_NOW, 2LL * NSEC_PER_SEC);
105 .Ed
106 .Pp
107 Create a milestone for use as an infinite timeout:
108 .Bd -literal -offset indent
109 milestone = DISPATCH_TIME_FOREVER;
110 .Ed
111 .Pp
112 Create a milestone on Tuesday, January 19, 2038:
113 .Bd -literal -offset indent
114 struct timespec ts;
115 ts.tv_sec = 0x7FFFFFFF;
116 ts.tv_nsec = 0;
117 milestone = dispatch_walltime(&ts, 0);
118 .Ed
119 .Sh RETURN VALUE
120 These functions return an abstract value for use with
121 .Fn dispatch_after ,
122 .Fn dispatch_group_wait ,
123 .Fn dispatch_semaphore_wait ,
124 or
125 .Fn dispatch_source_set_timer .
126 .Sh SEE ALSO
127 .Xr dispatch 3 ,
128 .Xr dispatch_after 3 ,
129 .Xr dispatch_group_create 3 ,
130 .Xr dispatch_semaphore_create 3