dispatch/once.h

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