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 /*!
  44  * @function dispatch_once
  45  *
  46  * @abstract
  47  * Execute a block once and only once.
  48  *
  49  * @param predicate
  50  * A pointer to a dispatch_once_t that is used to test whether the block has
  51  * completed or not.
  52  *
  53  * @param block
  54  * The block to execute once.
  55  *
  56  * @discussion
  57  * Always call dispatch_once() before using or testing any variables that are
  58  * initialized by the block.
  59  */
  60 #ifdef __BLOCKS__
  61 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  62 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
  63 DISPATCH_SWIFT3_UNAVAILABLE("Use lazily initialized globals instead")
  64 void
  65 dispatch_once(dispatch_once_t *predicate,
  66                 DISPATCH_NOESCAPE dispatch_block_t block);
  67
  68 DISPATCH_INLINE DISPATCH_ALWAYS_INLINE DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
  69 DISPATCH_SWIFT3_UNAVAILABLE("Use lazily initialized globals instead")
  70 void
  71 _dispatch_once(dispatch_once_t *predicate,
  72                 DISPATCH_NOESCAPE dispatch_block_t block)
  73 {
  74         if (DISPATCH_EXPECT(*predicate, ~0l) != ~0l) {
  75                 dispatch_once(predicate, block);
  76         } else {
  77                 dispatch_compiler_barrier();
  78         }
  79         DISPATCH_COMPILER_CAN_ASSUME(*predicate == ~0l);
  80 }
  81 #undef dispatch_once
  82 #define dispatch_once _dispatch_once
  83 #endif
  84
  85 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  86 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
  87 DISPATCH_SWIFT3_UNAVAILABLE("Use lazily initialized globals instead")
  88 void
  89 dispatch_once_f(dispatch_once_t *predicate, void *_Nullable context,
  90                 dispatch_function_t function);
  91
  92 DISPATCH_INLINE DISPATCH_ALWAYS_INLINE DISPATCH_NONNULL1 DISPATCH_NONNULL3
  93 DISPATCH_NOTHROW
  94 DISPATCH_SWIFT3_UNAVAILABLE("Use lazily initialized globals instead")
  95 void
  96 _dispatch_once_f(dispatch_once_t *predicate, void *_Nullable context,
  97                 dispatch_function_t function)
  98 {
  99         if (DISPATCH_EXPECT(*predicate, ~0l) != ~0l) {
 100                 dispatch_once_f(predicate, context, function);
 101         } else {
 102                 dispatch_compiler_barrier();
 103         }
 104         DISPATCH_COMPILER_CAN_ASSUME(*predicate == ~0l);
 105 }
 106 #undef dispatch_once_f
 107 #define dispatch_once_f _dispatch_once_f
 108
 109 __END_DECLS
 110
 111 DISPATCH_ASSUME_NONNULL_END
 112
 113 #endif