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 __BEGIN_DECLS
  30
  31 /*!
  32  * @typedef dispatch_once_t
  33  *
  34  * @abstract
  35  * A predicate for use with dispatch_once(). It must be initialized to zero.
  36  * Note: static and global variables default to zero.
  37  */
  38 typedef long dispatch_once_t;
  39
  40 /*!
  41  * @function dispatch_once
  42  *
  43  * @abstract
  44  * Execute a block once and only once.
  45  *
  46  * @param predicate
  47  * A pointer to a dispatch_once_t that is used to test whether the block has
  48  * completed or not.
  49  *
  50  * @param block
  51  * The block to execute once.
  52  *
  53  * @discussion
  54  * Always call dispatch_once() before using or testing any variables that are
  55  * initialized by the block.
  56  */
  57 #ifdef __BLOCKS__
  58 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  59 DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
  60 void
  61 dispatch_once(dispatch_once_t *predicate, dispatch_block_t block);
  62
  63 DISPATCH_INLINE DISPATCH_ALWAYS_INLINE DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
  64 void
  65 _dispatch_once(dispatch_once_t *predicate, dispatch_block_t block)
  66 {
  67         if (DISPATCH_EXPECT(*predicate, ~0l) != ~0l) {
  68                 dispatch_once(predicate, block);
  69         }
  70 }
  71 #undef dispatch_once
  72 #define dispatch_once _dispatch_once
  73 #endif
  74
  75 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
  76 DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
  77 void
  78 dispatch_once_f(dispatch_once_t *predicate, void *context,
  79                 dispatch_function_t function);
  80
  81 DISPATCH_INLINE DISPATCH_ALWAYS_INLINE DISPATCH_NONNULL1 DISPATCH_NONNULL3
  82 DISPATCH_NOTHROW
  83 void
  84 _dispatch_once_f(dispatch_once_t *predicate, void *context,
  85                 dispatch_function_t function)
  86 {
  87         if (DISPATCH_EXPECT(*predicate, ~0l) != ~0l) {
  88                 dispatch_once_f(predicate, context, function);
  89         }
  90 }
  91 #undef dispatch_once_f
  92 #define dispatch_once_f _dispatch_once_f
  93
  94 __END_DECLS
  95
  96 #endif