[apple/libdispatch.git] / dispatch / once.h

/*
 * Copyright (c) 2008-2010 Apple Inc. All rights reserved.
 *
 * @APPLE_APACHE_LICENSE_HEADER_START@
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * @APPLE_APACHE_LICENSE_HEADER_END@
 */

#ifndef __DISPATCH_ONCE__
#define __DISPATCH_ONCE__

#ifndef __DISPATCH_INDIRECT__
#error "Please #include <dispatch/dispatch.h> instead of this file directly."
#include <dispatch/base.h> // for HeaderDoc
#endif

__BEGIN_DECLS

/*!
 * @typedef dispatch_once_t
 *
 * @abstract
 * A predicate for use with dispatch_once(). It must be initialized to zero.
 * Note: static and global variables default to zero.
 */
typedef long dispatch_once_t;

/*!
 * @function dispatch_once
 *
 * @abstract
 * Execute a block once and only once.
 *
 * @param predicate
 * A pointer to a dispatch_once_t that is used to test whether the block has
 * completed or not.
 *
 * @param block
 * The block to execute once.
 *
 * @discussion
 * Always call dispatch_once() before using or testing any variables that are
 * initialized by the block.
 */
#ifdef __BLOCKS__
__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
void
dispatch_once(dispatch_once_t *predicate, dispatch_block_t block);

DISPATCH_INLINE DISPATCH_ALWAYS_INLINE DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
void
_dispatch_once(dispatch_once_t *predicate, dispatch_block_t block)
{
	if (DISPATCH_EXPECT(*predicate, ~0l) != ~0l) {
		dispatch_once(predicate, block);
	}
}
#undef dispatch_once
#define dispatch_once _dispatch_once
#endif

__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
DISPATCH_EXPORT DISPATCH_NONNULL1 DISPATCH_NONNULL3 DISPATCH_NOTHROW
void
dispatch_once_f(dispatch_once_t *predicate, void *context,
		dispatch_function_t function);

DISPATCH_INLINE DISPATCH_ALWAYS_INLINE DISPATCH_NONNULL1 DISPATCH_NONNULL3
DISPATCH_NOTHROW
void
_dispatch_once_f(dispatch_once_t *predicate, void *context,
		dispatch_function_t function)
{
	if (DISPATCH_EXPECT(*predicate, ~0l) != ~0l) {
		dispatch_once_f(predicate, context, function);
	}
}
#undef dispatch_once_f
#define dispatch_once_f _dispatch_once_f

__END_DECLS

#endif
Commit	Line	Data
0ab74447	1	/*
e85f4437	2	* Copyright (c) 2008-2010 Apple Inc. All rights reserved.
0ab74447 A	3	*
0ab74447 A	4	* @APPLE_APACHE_LICENSE_HEADER_START@
e85f4437	5	*
0ab74447 A	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
e85f4437	9	*
0ab74447	10	* http://www.apache.org/licenses/LICENSE-2.0
e85f4437	11	*
0ab74447 A	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.
e85f4437	17	*
0ab74447 A	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__
e85f4437 A	58	__OSX_AVAILABLE_STARTING(__MAC_10_6,__IPHONE_4_0)
e85f4437 A	59	DISPATCH_EXPORT DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
0ab74447 A	60	void
0ab74447 A	61	dispatch_once(dispatch_once_t *predicate, dispatch_block_t block);
0ab74447	62
e85f4437	63	DISPATCH_INLINE DISPATCH_ALWAYS_INLINE DISPATCH_NONNULL_ALL DISPATCH_NOTHROW
0ab74447	64	void
e85f4437 A	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
0ab74447 A	73	#endif
0ab74447 A	74
e85f4437 A	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
0ab74447 A	94	__END_DECLS
	95
	96	#endif