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 */
79typedef 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 */
87OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_trylock)
88__OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0)
89bool 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 */
97OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_lock)
98__OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0)
99void OSSpinLockLock( volatile OSSpinLock *__lock );
100
101
102/*! @abstract Unlocks a spinlock */
103OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_unlock)
104__OSX_AVAILABLE_STARTING(__MAC_10_4, __IPHONE_2_0)
105void 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
134typedef 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
141OSSPINLOCK_INLINE
142void
143OSSpinLockLock(volatile OSSpinLock *__lock)
144{
145 os_unfair_lock_t lock = (os_unfair_lock_t)__lock;
146 return os_unfair_lock_lock(lock);
147}
148
149OSSPINLOCK_INLINE
150bool
151OSSpinLockTry(volatile OSSpinLock *__lock)
152{
153 os_unfair_lock_t lock = (os_unfair_lock_t)__lock;
154 return os_unfair_lock_trylock(lock);
155}
156
157OSSPINLOCK_INLINE
158void
159OSSpinLockUnlock(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
184typedef int32_t OSSpinLock OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock);
185typedef volatile OSSpinLock *_os_nospin_lock_t
186 OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_t);
187
188OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_lock)
189OS_NOSPIN_LOCK_AVAILABILITY
190void _os_nospin_lock_lock(_os_nospin_lock_t lock);
191#undef OSSpinLockLock
192#define OSSpinLockLock(lock) _os_nospin_lock_lock(lock)
193
194OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_trylock)
195OS_NOSPIN_LOCK_AVAILABILITY
196bool _os_nospin_lock_trylock(_os_nospin_lock_t lock);
197#undef OSSpinLockTry
198#define OSSpinLockTry(lock) _os_nospin_lock_trylock(lock)
199
200OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_unlock)
201OS_NOSPIN_LOCK_AVAILABILITY
202void _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_ */