]> git.saurik.com Git - apple/libdispatch.git/blob - man/dispatch_time.3
libdispatch-228.18.tar.gz
[apple/libdispatch.git] / man / dispatch_time.3
1 .\" Copyright (c) 2008-2009 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 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 EXAMPLES
84 Create a milestone two seconds in the future:
85 .Bd -literal -offset indent
86 milestone = dispatch_time(DISPATCH_TIME_NOW, 2LL * NSEC_PER_SEC);
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
101 .Sh RETURN VALUE
102 These functions return an abstract value for use with
103 .Fn dispatch_after ,
104 .Fn dispatch_group_wait ,
105 or
106 .Fn dispatch_semaphore_wait .
107 .Sh SEE ALSO
108 .Xr dispatch 3 ,
109 .Xr dispatch_after 3 ,
110 .Xr dispatch_group_create 3 ,
111 .Xr dispatch_semaphore_create 3