]>
Commit | Line | Data |
---|---|---|
517da941 | 1 | .\" Copyright (c) 2008-2013 Apple Inc. All rights reserved. |
0ab74447 A |
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> | |
c093abd6 | 11 | .Vt static const dispatch_time_t DISPATCH_TIME_NOW = 0ull ; |
0ab74447 A |
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 , | |
beb15981 | 52 | then the current time of the default host clock is used. |
0ab74447 A |
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 EXAMPLES | |
84 | Create a milestone two seconds in the future: | |
85 | .Bd -literal -offset indent | |
6b746eb4 | 86 | milestone = dispatch_time(DISPATCH_TIME_NOW, 2 * NSEC_PER_SEC); |
0ab74447 A |
87 | .Ed |
88 | .Pp | |
89 | Create a milestone for use as an infinite timeout: | |
90 | .Bd -literal -offset indent | |
91 | milestone = DISPATCH_TIME_FOREVER; | |
92 | .Ed | |
93 | .Pp | |
94 | Create a milestone on Tuesday, January 19, 2038: | |
95 | .Bd -literal -offset indent | |
96 | struct timespec ts; | |
97 | ts.tv_sec = 0x7FFFFFFF; | |
98 | ts.tv_nsec = 0; | |
99 | milestone = dispatch_walltime(&ts, 0); | |
100 | .Ed | |
6b746eb4 A |
101 | .Pp |
102 | Use a negative delta to create a milestone an hour before the one above: | |
103 | .Bd -literal -offset indent | |
104 | milestone = dispatch_walltime(&ts, -60 * 60 * NSEC_PER_SEC); | |
105 | .Ed | |
0ab74447 A |
106 | .Sh RETURN VALUE |
107 | These functions return an abstract value for use with | |
108 | .Fn dispatch_after , | |
109 | .Fn dispatch_group_wait , | |
517da941 | 110 | .Fn dispatch_semaphore_wait , |
0ab74447 | 111 | or |
517da941 | 112 | .Fn dispatch_source_set_timer . |
0ab74447 | 113 | .Sh SEE ALSO |
e85f4437 | 114 | .Xr dispatch 3 , |
0ab74447 A |
115 | .Xr dispatch_after 3 , |
116 | .Xr dispatch_group_create 3 , | |
117 | .Xr dispatch_semaphore_create 3 |