1/*
2 * Copyright (c) 2008-2010 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_ONCE__
22#define __DISPATCH_ONCE__
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
29DISPATCH_ASSUME_NONNULL_BEGIN
30DISPATCH_ASSUME_ABI_SINGLE_BEGIN
31
32__BEGIN_DECLS
33
34/*!
35 * @typedef dispatch_once_t
36 *
37 * @abstract
38 * A predicate for use with dispatch_once(). It must be initialized to zero.
39 * Note: static and global variables default to zero.
40 */
41DISPATCH_SWIFT3_UNAVAILABLE("Use lazily initialized globals instead")
42typedef intptr_t dispatch_once_t;
43
44#if defined(__x86_64__) || defined(__i386__) || defined(__s390x__)
45#define DISPATCH_ONCE_INLINE_FASTPATH 1
46#elif defined(__APPLE__)
47#define DISPATCH_ONCE_INLINE_FASTPATH 1
48#else
49#define DISPATCH_ONCE_INLINE_FASTPATH 0
50#endif
51
52/*!
53 * @function dispatch_once
54 *
55 * @abstract
56 * Execute a block once and only once.
57 *
58 * @param predicate
59 * A pointer to a dispatch_once_t that is used to test whether the block has
60 * completed or not.
61 *
62 * @param block
63 * The block to execute once.
64 *
65 * @discussion
66 * Always call dispatch_once() before using or testing any variables that are
67 * initialized by the block.
68 */
69#ifdef __BLOCKS__
70API_AVAILABLE(macos(10.6), ios(4.0))
71DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
72DISPATCH_SWIFT3_UNAVAILABLE("Use lazily initialized globals instead")
73void
74dispatch_once(dispatch_once_t *predicate,
75 DISPATCH_NOESCAPE dispatch_block_t block);
76
77#if DISPATCH_ONCE_INLINE_FASTPATH
78DISPATCH_INLINE DISPATCH_ALWAYS_INLINE DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
79DISPATCH_NO_UBSAN
80DISPATCH_SWIFT3_UNAVAILABLE("Use lazily initialized globals instead")
81void
82_dispatch_once(dispatch_once_t *predicate,
83 DISPATCH_NOESCAPE dispatch_block_t block)
84{
85 if (DISPATCH_EXPECT(*predicate, ~0l) != ~0l) {
86 dispatch_once(predicate, block);
87 } else {
88 dispatch_compiler_barrier();
89 }
90 DISPATCH_COMPILER_CAN_ASSUME(*predicate == ~0l);
91}
92#undef dispatch_once
93#define dispatch_once _dispatch_once
94#endif
95#endif // DISPATCH_ONCE_INLINE_FASTPATH
96
97API_AVAILABLE(macos(10.6), ios(4.0))
98DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
99DISPATCH_SWIFT3_UNAVAILABLE("Use lazily initialized globals instead")
100void
101dispatch_once_f(dispatch_once_t *predicate, void *_Nullable context,
102 dispatch_function_t function);
103
104#if DISPATCH_ONCE_INLINE_FASTPATH
105DISPATCH_INLINE DISPATCH_ALWAYS_INLINE DISPATCH_NONNULL1 DISPATCH_NONNULL3
106DISPATCH_NOTHROW DISPATCH_NO_UBSAN
107DISPATCH_SWIFT3_UNAVAILABLE("Use lazily initialized globals instead")
108void
109_dispatch_once_f(dispatch_once_t *predicate, void *_Nullable context,
110 dispatch_function_t function)
111{
112 if (DISPATCH_EXPECT(*predicate, ~0l) != ~0l) {
113 dispatch_once_f(predicate, context, function);
114 } else {
115 dispatch_compiler_barrier();
116 }
117 DISPATCH_COMPILER_CAN_ASSUME(*predicate == ~0l);
118}
119#undef dispatch_once_f
120#define dispatch_once_f _dispatch_once_f
121#endif // DISPATCH_ONCE_INLINE_FASTPATH
122
123__END_DECLS
124
125DISPATCH_ASSUME_ABI_SINGLE_END
126DISPATCH_ASSUME_NONNULL_END
127
128#endif