src/once.h

   1 /*
   2  * Copyright (c) 2008-2009 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_NA)
  59 DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
  60 void
  61 dispatch_once(dispatch_once_t *predicate, dispatch_block_t block);
  62 #ifdef __GNUC__
  63 #define dispatch_once(x, ...) do { if (__builtin_expect(*(x), ~0l) != ~0l) dispatch_once((x), (__VA_ARGS__)); } while (0)
  64 #endif
  65 #endif
  66
  67 __OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_NA)
  68 DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
  69 void
  70 dispatch_once_f(dispatch_once_t *predicate, void *context, void (*function)(void *));
  71 #ifdef __GNUC__
  72 #define dispatch_once_f(x, y, z) do { if (__builtin_expect(*(x), ~0l) != ~0l) dispatch_once_f((x), (y), (z)); } while (0)
  73 #endif
  74
  75 __END_DECLS
  76
  77 #endif