OSSpinLockDeprecated.h (6687B) - Raw
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); 185 typedef volatile OSSpinLock *_os_nospin_lock_t 186 OSSPINLOCK_DEPRECATED_REPLACE_WITH(os_unfair_lock_t); 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_ */