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