[apple/libplatform.git] / include / libkern / OSSpinLockDeprecated.h

/*
 * Copyright (c) 2004-2016 Apple Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_LICENSE_HEADER_END@
 */

#ifndef _OSSPINLOCK_DEPRECATED_H_
#define _OSSPINLOCK_DEPRECATED_H_

/*! @header
 * These are deprecated legacy interfaces for userspace spinlocks.
 *
 * These interfaces should no longer be used, particularily in situations where
 * threads of differing priorities may contend on the same spinlock.
 *
 * The interfaces in <os/lock.h> should be used instead in cases where a very
 * low-level lock primitive is required. In general however, using higher level
 * synchronization primitives such as those provided by the pthread or dispatch
 * subsystems should be preferred.
 *
 * Define OSSPINLOCK_USE_INLINED=1 to get inline implementations of these
 * interfaces in terms of the <os/lock.h> primitives. This is intended as a
 * transition convenience, direct use of those primitives is preferred.
 */

#ifndef OSSPINLOCK_DEPRECATED
#define OSSPINLOCK_DEPRECATED 1
#define OSSPINLOCK_DEPRECATED_MSG(_r) "Use " #_r "() from <os/lock.h> instead"
#define OSSPINLOCK_DEPRECATED_REPLACE_WITH(_r) \
	__OS_AVAILABILITY_MSG(macosx, deprecated=10.12, OSSPINLOCK_DEPRECATED_MSG(_r)) \
	__OS_AVAILABILITY_MSG(ios, deprecated=10.0, OSSPINLOCK_DEPRECATED_MSG(_r)) \
	__OS_AVAILABILITY_MSG(tvos, deprecated=10.0, OSSPINLOCK_DEPRECATED_MSG(_r)) \
	__OS_AVAILABILITY_MSG(watchos, deprecated=3.0, OSSPINLOCK_DEPRECATED_MSG(_r))
#else
#undef OSSPINLOCK_DEPRECATED
#define OSSPINLOCK_DEPRECATED 0
#define OSSPINLOCK_DEPRECATED_REPLACE_WITH(_r)
#endif

#if !(defined(OSSPINLOCK_USE_INLINED) && OSSPINLOCK_USE_INLINED)

#include    <sys/cdefs.h>
#include    <stddef.h>
#include    <stdint.h>
#include    <stdbool.h>
#include    <Availability.h>

__BEGIN_DECLS

/*! @abstract The default value for an <code>OSSpinLock</code>.
    @discussion
	The convention is that unlocked is zero, locked is nonzero.
 */
#define	OS_SPINLOCK_INIT    0


/*! @abstract Data type for a spinlock.
    @discussion
	You should always initialize a spinlock to {@link OS_SPINLOCK_INIT} before
	using it.
 */
typedef int32_t OSSpinLock OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock);


/*! @abstract Locks a spinlock if it would not block
    @result
	Returns <code>false</code> if the lock was already held by another thread,
	<code>true</code> if it took the lock successfully.
 */
OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_trylock)
__OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0)
bool    OSSpinLockTry( volatile OSSpinLock *__lock );


/*! @abstract Locks a spinlock
    @discussion
	Although the lock operation spins, it employs various strategies to back
	off if the lock is held.
 */
OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_lock)
__OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0)
void    OSSpinLockLock( volatile OSSpinLock *__lock );


/*! @abstract Unlocks a spinlock */
OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_unlock)
__OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0)
void    OSSpinLockUnlock( volatile OSSpinLock *__lock );

__END_DECLS

#else /* OSSPINLOCK_USE_INLINED */

/*
 * Inline implementations of the legacy OSSpinLock interfaces in terms of the
 * of the <os/lock.h> primitives. Direct use of those primitives is preferred.
 *
 * NOTE: the locked value of os_unfair_lock is implementation defined and
 * subject to change, code that relies on the specific locked value used by the
 * legacy OSSpinLock interface WILL break when using these inline
 * implementations in terms of os_unfair_lock.
 */

#if !OSSPINLOCK_USE_INLINED_TRANSPARENT

#include <os/lock.h>

__BEGIN_DECLS

#if __has_attribute(always_inline)
#define OSSPINLOCK_INLINE static __inline
#else
#define OSSPINLOCK_INLINE static __inline __attribute__((__always_inline__))
#endif

#define OS_SPINLOCK_INIT 0
typedef int32_t OSSpinLock;

#if  __has_extension(c_static_assert)
_Static_assert(sizeof(OSSpinLock) == sizeof(os_unfair_lock),
		"Incompatible os_unfair_lock type");
#endif

OSSPINLOCK_INLINE
void
OSSpinLockLock(volatile OSSpinLock *__lock)
{
	os_unfair_lock_t lock = (os_unfair_lock_t)__lock;
	return os_unfair_lock_lock(lock);
}

OSSPINLOCK_INLINE
bool
OSSpinLockTry(volatile OSSpinLock *__lock)
{
	os_unfair_lock_t lock = (os_unfair_lock_t)__lock;
	return os_unfair_lock_trylock(lock);
}

OSSPINLOCK_INLINE
void
OSSpinLockUnlock(volatile OSSpinLock *__lock)
{
	os_unfair_lock_t lock = (os_unfair_lock_t)__lock;
	return os_unfair_lock_unlock(lock);
}

#undef OSSPINLOCK_INLINE

__END_DECLS

#else /* OSSPINLOCK_USE_INLINED_TRANSPARENT */

#include    <sys/cdefs.h>
#include    <stddef.h>
#include    <stdint.h>
#include    <stdbool.h>
#include    <Availability.h>

#define OS_NOSPIN_LOCK_AVAILABILITY \
		__OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) \
		__TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)

__BEGIN_DECLS

#define OS_SPINLOCK_INIT 0
typedef int32_t OSSpinLock OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock);
typedef volatile OSSpinLock *_os_nospin_lock_t
		OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_t);

OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_lock)
OS_NOSPIN_LOCK_AVAILABILITY
void _os_nospin_lock_lock(_os_nospin_lock_t lock);
#undef OSSpinLockLock
#define OSSpinLockLock(lock) _os_nospin_lock_lock(lock)

OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_trylock)
OS_NOSPIN_LOCK_AVAILABILITY
bool _os_nospin_lock_trylock(_os_nospin_lock_t lock);
#undef OSSpinLockTry
#define OSSpinLockTry(lock) _os_nospin_lock_trylock(lock)

OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_unlock)
OS_NOSPIN_LOCK_AVAILABILITY
void _os_nospin_lock_unlock(_os_nospin_lock_t lock);
#undef OSSpinLockUnlock
#define OSSpinLockUnlock(lock) _os_nospin_lock_unlock(lock)

__END_DECLS

#endif /* OSSPINLOCK_USE_INLINED_TRANSPARENT */

#endif /* OSSPINLOCK_USE_INLINED */

#endif /* _OSSPINLOCK_DEPRECATED_H_ */
Commit	Line	Data
ada7c492 A	1	/*
	2	* Copyright (c) 2004-2016 Apple Inc. All rights reserved.
	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
	6	* This file contains Original Code and/or Modifications of Original Code
	7	* as defined in and that are subject to the Apple Public Source License
	8	* Version 2.0 (the 'License'). You may not use this file except in
	9	* compliance with the License. Please obtain a copy of the License at
	10	* http://www.opensource.apple.com/apsl/ and read it before using this
	11	* file.
	12	*
	13	* The Original Code and all software distributed under the License are
	14	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
	15	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	16	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	17	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	18	* Please see the License for the specific language governing rights and
	19	* limitations under the License.
	20	*
	21	* @APPLE_LICENSE_HEADER_END@
	22	*/
	23
	24	#ifndef _OSSPINLOCK_DEPRECATED_H_
	25	#define _OSSPINLOCK_DEPRECATED_H_
	26
	27	/*! @header
	28	* These are deprecated legacy interfaces for userspace spinlocks.
	29	*
	30	* These interfaces should no longer be used, particularily in situations where
	31	* threads of differing priorities may contend on the same spinlock.
	32	*
	33	* The interfaces in <os/lock.h> should be used instead in cases where a very
	34	* low-level lock primitive is required. In general however, using higher level
	35	* synchronization primitives such as those provided by the pthread or dispatch
	36	* subsystems should be preferred.
	37	*
	38	* Define OSSPINLOCK_USE_INLINED=1 to get inline implementations of these
	39	* interfaces in terms of the <os/lock.h> primitives. This is intended as a
	40	* transition convenience, direct use of those primitives is preferred.
	41	*/
	42
	43	#ifndef OSSPINLOCK_DEPRECATED
	44	#define OSSPINLOCK_DEPRECATED 1
	45	#define OSSPINLOCK_DEPRECATED_MSG(_r) "Use " #_r "() from <os/lock.h> instead"
	46	#define OSSPINLOCK_DEPRECATED_REPLACE_WITH(_r) \
	47	__OS_AVAILABILITY_MSG(macosx, deprecated=10.12, OSSPINLOCK_DEPRECATED_MSG(_r)) \
	48	__OS_AVAILABILITY_MSG(ios, deprecated=10.0, OSSPINLOCK_DEPRECATED_MSG(_r)) \
	49	__OS_AVAILABILITY_MSG(tvos, deprecated=10.0, OSSPINLOCK_DEPRECATED_MSG(_r)) \
	50	__OS_AVAILABILITY_MSG(watchos, deprecated=3.0, OSSPINLOCK_DEPRECATED_MSG(_r))
	51	#else
	52	#undef OSSPINLOCK_DEPRECATED
	53	#define OSSPINLOCK_DEPRECATED 0
	54	#define OSSPINLOCK_DEPRECATED_REPLACE_WITH(_r)
	55	#endif
	56
	57	#if !(defined(OSSPINLOCK_USE_INLINED) && OSSPINLOCK_USE_INLINED)
	58
	59	#include <sys/cdefs.h>
	60	#include <stddef.h>
	61	#include <stdint.h>
	62	#include <stdbool.h>
	63	#include <Availability.h>
	64
65	__BEGIN_DECLS
66
67	/*! @abstract The default value for an <code>OSSpinLock</code>.
68	@discussion
69	The convention is that unlocked is zero, locked is nonzero.
70	*/
71	#define OS_SPINLOCK_INIT 0
72
73
74	/*! @abstract Data type for a spinlock.
75	@discussion
76	You should always initialize a spinlock to {@link OS_SPINLOCK_INIT} before
77	using it.
78	*/
79	typedef int32_t OSSpinLock OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock);
80
81
82	/*! @abstract Locks a spinlock if it would not block
83	@result
84	Returns <code>false</code> if the lock was already held by another thread,
85	<code>true</code> if it took the lock successfully.
86	*/
87	OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_trylock)
88	__OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0)
89	bool OSSpinLockTry( volatile OSSpinLock *__lock );
90
91
92	/*! @abstract Locks a spinlock
93	@discussion
94	Although the lock operation spins, it employs various strategies to back
95	off if the lock is held.
96	*/
97	OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_lock)
98	__OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0)
99	void OSSpinLockLock( volatile OSSpinLock *__lock );
100
101
102	/! @abstract Unlocks a spinlock /
103	OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_unlock)
104	__OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0)
105	void OSSpinLockUnlock( volatile OSSpinLock *__lock );
106
107	__END_DECLS
108
109	#else /* OSSPINLOCK_USE_INLINED */
110
111	/*
112	* Inline implementations of the legacy OSSpinLock interfaces in terms of the
113	* of the <os/lock.h> primitives. Direct use of those primitives is preferred.
114	*
115	* NOTE: the locked value of os_unfair_lock is implementation defined and
116	* subject to change, code that relies on the specific locked value used by the
117	* legacy OSSpinLock interface WILL break when using these inline
118	* implementations in terms of os_unfair_lock.
119	*/
120
121	#if !OSSPINLOCK_USE_INLINED_TRANSPARENT
122
123	#include <os/lock.h>
124
125	__BEGIN_DECLS
126
127	#if __has_attribute(always_inline)
128	#define OSSPINLOCK_INLINE static __inline
129	#else
130	#define OSSPINLOCK_INLINE static __inline __attribute__((__always_inline__))
131	#endif
132
133	#define OS_SPINLOCK_INIT 0
134	typedef int32_t OSSpinLock;
135
136	#if __has_extension(c_static_assert)
137	_Static_assert(sizeof(OSSpinLock) == sizeof(os_unfair_lock),
138	"Incompatible os_unfair_lock type");
139	#endif
140
141	OSSPINLOCK_INLINE
142	void
143	OSSpinLockLock(volatile OSSpinLock *__lock)
144	{
145	os_unfair_lock_t lock = (os_unfair_lock_t)__lock;
146	return os_unfair_lock_lock(lock);
147	}
148
149	OSSPINLOCK_INLINE
150	bool
151	OSSpinLockTry(volatile OSSpinLock *__lock)
152	{
153	os_unfair_lock_t lock = (os_unfair_lock_t)__lock;
154	return os_unfair_lock_trylock(lock);
155	}
156
157	OSSPINLOCK_INLINE
158	void
159	OSSpinLockUnlock(volatile OSSpinLock *__lock)
160	{
161	os_unfair_lock_t lock = (os_unfair_lock_t)__lock;
162	return os_unfair_lock_unlock(lock);
163	}
164
165	#undef OSSPINLOCK_INLINE
166
167	__END_DECLS
168
169	#else /* OSSPINLOCK_USE_INLINED_TRANSPARENT */
170
171	#include <sys/cdefs.h>
172	#include <stddef.h>
173	#include <stdint.h>
174	#include <stdbool.h>
175	#include <Availability.h>
176
177	#define OS_NOSPIN_LOCK_AVAILABILITY \
178	__OSX_AVAILABLE(10.12) __IOS_AVAILABLE(10.0) \
179	__TVOS_AVAILABLE(10.0) __WATCHOS_AVAILABLE(3.0)
180
181	__BEGIN_DECLS
182
183	#define OS_SPINLOCK_INIT 0
184	typedef int32_t OSSpinLock OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock);
e45b4692 A	185	typedef volatile OSSpinLock *_os_nospin_lock_t
e45b4692 A	186	OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_t);
ada7c492 A	187
	188	OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_lock)
	189	OS_NOSPIN_LOCK_AVAILABILITY
	190	void _os_nospin_lock_lock(_os_nospin_lock_t lock);
	191	#undef OSSpinLockLock
	192	#define OSSpinLockLock(lock) _os_nospin_lock_lock(lock)
	193
	194	OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_trylock)
	195	OS_NOSPIN_LOCK_AVAILABILITY
	196	bool _os_nospin_lock_trylock(_os_nospin_lock_t lock);
	197	#undef OSSpinLockTry
	198	#define OSSpinLockTry(lock) _os_nospin_lock_trylock(lock)
	199
	200	OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_unlock)
	201	OS_NOSPIN_LOCK_AVAILABILITY
	202	void _os_nospin_lock_unlock(_os_nospin_lock_t lock);
	203	#undef OSSpinLockUnlock
	204	#define OSSpinLockUnlock(lock) _os_nospin_lock_unlock(lock)
	205
	206	__END_DECLS
	207
	208	#endif /* OSSPINLOCK_USE_INLINED_TRANSPARENT */
	209
	210	#endif /* OSSPINLOCK_USE_INLINED */
	211
	212	#endif /* _OSSPINLOCK_DEPRECATED_H_ */