1/*
2 * Copyright (c) 2008-2011 Apple Inc. All rights reserved.
3 *
4 * @APPLE_APACHE_LICENSE_HEADER_START@
5 *
6 * Licensed under the Apache License, Version 2.0 (the "License");
7 * you may not use this file except in compliance with the License.
8 * You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing, software
13 * distributed under the License is distributed on an "AS IS" BASIS,
14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 * See the License for the specific language governing permissions and
16 * limitations under the License.
17 *
18 * @APPLE_APACHE_LICENSE_HEADER_END@
19 */
20
21#ifndef __DISPATCH_TIME__
22#define __DISPATCH_TIME__
23
24#ifndef __DISPATCH_INDIRECT__
25#error "Please #include <dispatch/dispatch.h> instead of this file directly."
26#include <dispatch/base.h> // for HeaderDoc
27#endif
28
29#include <stdint.h>
30
31// <rdar://problem/6368156&7563559>
32#if TARGET_OS_MAC
33#include <mach/clock_types.h>
34#endif
35
36DISPATCH_ASSUME_NONNULL_BEGIN
37DISPATCH_ASSUME_ABI_SINGLE_BEGIN
38
39#ifdef NSEC_PER_SEC
40#undef NSEC_PER_SEC
41#endif
42#ifdef USEC_PER_SEC
43#undef USEC_PER_SEC
44#endif
45#ifdef NSEC_PER_USEC
46#undef NSEC_PER_USEC
47#endif
48#ifdef NSEC_PER_MSEC
49#undef NSEC_PER_MSEC
50#endif
51#ifdef MSEC_PER_SEC
52#undef MSEC_PER_SEC
53#endif
54#define MSEC_PER_SEC 1000ull
55#define NSEC_PER_SEC 1000000000ull
56#define NSEC_PER_MSEC 1000000ull
57#define USEC_PER_SEC 1000000ull
58#define NSEC_PER_USEC 1000ull
59
60__BEGIN_DECLS
61
62struct timespec;
63
64/*!
65 * @typedef dispatch_time_t
66 *
67 * @abstract
68 * A somewhat abstract representation of time; where zero means "now" and
69 * DISPATCH_TIME_FOREVER means "infinity" and every value in between is an
70 * opaque encoding.
71 */
72typedef uint64_t dispatch_time_t;
73
74enum {
75 DISPATCH_WALLTIME_NOW DISPATCH_ENUM_API_AVAILABLE
76 (macos(10.14), ios(12.0), tvos(12.0), watchos(5.0)) = ~1ull,
77};
78
79#define DISPATCH_TIME_NOW (0ull)
80#define DISPATCH_TIME_FOREVER (~0ull)
81
82/*!
83 * @function dispatch_time
84 *
85 * @abstract
86 * Create a dispatch_time_t relative to the current value of the default or
87 * wall time clock, or modify an existing dispatch_time_t.
88 *
89 * @discussion
90 * On Apple platforms, the default clock is based on mach_absolute_time().
91 *
92 * @param when
93 * An optional dispatch_time_t to add nanoseconds to. If DISPATCH_TIME_NOW is
94 * passed, then dispatch_time() will use the default clock (which is based on
95 * mach_absolute_time() on Apple platforms). If DISPATCH_WALLTIME_NOW is used,
96 * dispatch_time() will use the value returned by gettimeofday(3).
97 * dispatch_time(DISPATCH_WALLTIME_NOW, delta) is equivalent to
98 * dispatch_walltime(NULL, delta).
99 *
100 * @param delta
101 * Nanoseconds to add.
102 *
103 * @result
104 * A new dispatch_time_t.
105 */
106API_AVAILABLE(macos(10.6), ios(4.0))
107DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_NOTHROW
108DISPATCH_REFINED_FOR_SWIFT
109dispatch_time_t
110dispatch_time(dispatch_time_t when, int64_t delta);
111
112/*!
113 * @function dispatch_walltime
114 *
115 * @abstract
116 * Create a dispatch_time_t using the wall clock.
117 *
118 * @discussion
119 * On Mac OS X the wall clock is based on gettimeofday(3).
120 *
121 * @param when
122 * A struct timespec to add time to. If NULL is passed, then
123 * dispatch_walltime() will use the result of gettimeofday(3).
124 * dispatch_walltime(NULL, delta) returns the same value as
125 * dispatch_time(DISPATCH_WALLTIME_NOW, delta).
126 *
127 * @param delta
128 * Nanoseconds to add.
129 *
130 * @result
131 * A new dispatch_time_t.
132 */
133API_AVAILABLE(macos(10.6), ios(4.0))
134DISPATCH_EXPORT DISPATCH_WARN_RESULT DISPATCH_NOTHROW
135DISPATCH_REFINED_FOR_SWIFT
136dispatch_time_t
137dispatch_walltime(const struct timespec *_Nullable when, int64_t delta);
138
139__END_DECLS
140
141DISPATCH_ASSUME_ABI_SINGLE_END
142DISPATCH_ASSUME_NONNULL_END
143
144#endif