include/libkern/OSSpinLockDeprecated.h

   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_ */