1 /* 2 Simple DirectMedia Layer 3 Copyright (C) 1997-2021 Sam Lantinga <slouken@libsdl.org> 4 5 This software is provided 'as-is', without any express or implied 6 warranty. In no event will the authors be held liable for any damages 7 arising from the use of this software. 8 9 Permission is granted to anyone to use this software for any purpose, 10 including commercial applications, and to alter it and redistribute it 11 freely, subject to the following restrictions: 12 13 1. The origin of this software must not be misrepresented; you must not 14 claim that you wrote the original software. If you use this software 15 in a product, an acknowledgment in the product documentation would be 16 appreciated but is not required. 17 2. Altered source versions must be plainly marked as such, and must not be 18 misrepresented as being the original software. 19 3. This notice may not be removed or altered from any source distribution. 20 */ 21 22 /** 23 * \file SDL_atomic.h 24 * 25 * Atomic operations. 26 * 27 * IMPORTANT: 28 * If you are not an expert in concurrent lockless programming, you should 29 * only be using the atomic lock and reference counting functions in this 30 * file. In all other cases you should be protecting your data structures 31 * with full mutexes. 32 * 33 * The list of "safe" functions to use are: 34 * SDL_AtomicLock() 35 * SDL_AtomicUnlock() 36 * SDL_AtomicIncRef() 37 * SDL_AtomicDecRef() 38 * 39 * Seriously, here be dragons! 40 * ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 41 * 42 * You can find out a little more about lockless programming and the 43 * subtle issues that can arise here: 44 * http://msdn.microsoft.com/en-us/library/ee418650%28v=vs.85%29.aspx 45 * 46 * There's also lots of good information here: 47 * http://www.1024cores.net/home/lock-free-algorithms 48 * http://preshing.com/ 49 * 50 * These operations may or may not actually be implemented using 51 * processor specific atomic operations. When possible they are 52 * implemented as true processor specific atomic operations. When that 53 * is not possible the are implemented using locks that *do* use the 54 * available atomic operations. 55 * 56 * All of the atomic operations that modify memory are full memory barriers. 57 */ 58 59 #ifndef SDL_atomic_h_ 60 #define SDL_atomic_h_ 61 62 #include "SDL_stdinc.h" 63 #include "SDL_platform.h" 64 65 #include "begin_code.h" 66 67 /* Set up for C function definitions, even when using C++ */ 68 #ifdef __cplusplus 69 extern "C" { 70 #endif 71 72 /** 73 * \name SDL AtomicLock 74 * 75 * The atomic locks are efficient spinlocks using CPU instructions, 76 * but are vulnerable to starvation and can spin forever if a thread 77 * holding a lock has been terminated. For this reason you should 78 * minimize the code executed inside an atomic lock and never do 79 * expensive things like API or system calls while holding them. 80 * 81 * The atomic locks are not safe to lock recursively. 82 * 83 * Porting Note: 84 * The spin lock functions and type are required and can not be 85 * emulated because they are used in the atomic emulation code. 86 */ 87 /* @{ */ 88 89 typedef int SDL_SpinLock; 90 91 /** 92 * Try to lock a spin lock by setting it to a non-zero value. 93 * 94 * ***Please note that spinlocks are dangerous if you don't know what you're 95 * doing. Please be careful using any sort of spinlock!*** 96 * 97 * \param lock a pointer to a lock variable 98 * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already 99 * held. 100 * 101 * \sa SDL_AtomicLock 102 * \sa SDL_AtomicUnlock 103 */ 104 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTryLock(SDL_SpinLock *lock); 105 106 /** 107 * Lock a spin lock by setting it to a non-zero value. 108 * 109 * ***Please note that spinlocks are dangerous if you don't know what you're 110 * doing. Please be careful using any sort of spinlock!*** 111 * 112 * \param lock a pointer to a lock variable 113 * 114 * \sa SDL_AtomicTryLock 115 * \sa SDL_AtomicUnlock 116 */ 117 extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock); 118 119 /** 120 * Unlock a spin lock by setting it to 0. 121 * 122 * Always returns immediately. 123 * 124 * ***Please note that spinlocks are dangerous if you don't know what you're 125 * doing. Please be careful using any sort of spinlock!*** 126 * 127 * \param lock a pointer to a lock variable 128 * 129 * \since This function is available since SDL 2.0.0. 130 * 131 * \sa SDL_AtomicLock 132 * \sa SDL_AtomicTryLock 133 */ 134 extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock); 135 136 /* @} *//* SDL AtomicLock */ 137 138 139 /** 140 * The compiler barrier prevents the compiler from reordering 141 * reads and writes to globally visible variables across the call. 142 */ 143 #if defined(_MSC_VER) && (_MSC_VER > 1200) && !defined(__clang__) 144 void _ReadWriteBarrier(void); 145 #pragma intrinsic(_ReadWriteBarrier) 146 #define SDL_CompilerBarrier() _ReadWriteBarrier() 147 #elif (defined(__GNUC__) && !defined(__EMSCRIPTEN__)) || (defined(__SUNPRO_C) && (__SUNPRO_C >= 0x5120)) 148 /* This is correct for all CPUs when using GCC or Solaris Studio 12.1+. */ 149 #define SDL_CompilerBarrier() __asm__ __volatile__ ("" : : : "memory") 150 #elif defined(__WATCOMC__) 151 extern _inline void SDL_CompilerBarrier (void); 152 #pragma aux SDL_CompilerBarrier = "" parm [] modify exact []; 153 #else 154 #define SDL_CompilerBarrier() \ 155 { SDL_SpinLock _tmp = 0; SDL_AtomicLock(&_tmp); SDL_AtomicUnlock(&_tmp); } 156 #endif 157 158 /** 159 * Memory barriers are designed to prevent reads and writes from being 160 * reordered by the compiler and being seen out of order on multi-core CPUs. 161 * 162 * A typical pattern would be for thread A to write some data and a flag, and 163 * for thread B to read the flag and get the data. In this case you would 164 * insert a release barrier between writing the data and the flag, 165 * guaranteeing that the data write completes no later than the flag is 166 * written, and you would insert an acquire barrier between reading the flag 167 * and reading the data, to ensure that all the reads associated with the flag 168 * have completed. 169 * 170 * In this pattern you should always see a release barrier paired with an 171 * acquire barrier and you should gate the data reads/writes with a single 172 * flag variable. 173 * 174 * For more information on these semantics, take a look at the blog post: 175 * http://preshing.com/20120913/acquire-and-release-semantics 176 */ 177 extern DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void); 178 extern DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); 179 180 #if defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__)) 181 #define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("lwsync" : : : "memory") 182 #define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("lwsync" : : : "memory") 183 #elif defined(__GNUC__) && defined(__aarch64__) 184 #define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("dmb ish" : : : "memory") 185 #define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("dmb ish" : : : "memory") 186 #elif defined(__GNUC__) && defined(__arm__) 187 #if 0 /* defined(__LINUX__) || defined(__ANDROID__) */ 188 /* Information from: 189 https://chromium.googlesource.com/chromium/chromium/+/trunk/base/atomicops_internals_arm_gcc.h#19 190 191 The Linux kernel provides a helper function which provides the right code for a memory barrier, 192 hard-coded at address 0xffff0fa0 193 */ 194 typedef void (*SDL_KernelMemoryBarrierFunc)(); 195 #define SDL_MemoryBarrierRelease() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() 196 #define SDL_MemoryBarrierAcquire() ((SDL_KernelMemoryBarrierFunc)0xffff0fa0)() 197 #elif 0 /* defined(__QNXNTO__) */ 198 #include <sys/cpuinline.h> 199 200 #define SDL_MemoryBarrierRelease() __cpu_membarrier() 201 #define SDL_MemoryBarrierAcquire() __cpu_membarrier() 202 #else 203 #if defined(__ARM_ARCH_7__) || defined(__ARM_ARCH_7A__) || defined(__ARM_ARCH_7EM__) || defined(__ARM_ARCH_7R__) || defined(__ARM_ARCH_7M__) || defined(__ARM_ARCH_7S__) || defined(__ARM_ARCH_8A__) 204 #define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("dmb ish" : : : "memory") 205 #define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("dmb ish" : : : "memory") 206 #elif defined(__ARM_ARCH_6__) || defined(__ARM_ARCH_6J__) || defined(__ARM_ARCH_6K__) || defined(__ARM_ARCH_6T2__) || defined(__ARM_ARCH_6Z__) || defined(__ARM_ARCH_6ZK__) || defined(__ARM_ARCH_5TE__) 207 #ifdef __thumb__ 208 /* The mcr instruction isn't available in thumb mode, use real functions */ 209 #define SDL_MEMORY_BARRIER_USES_FUNCTION 210 #define SDL_MemoryBarrierRelease() SDL_MemoryBarrierReleaseFunction() 211 #define SDL_MemoryBarrierAcquire() SDL_MemoryBarrierAcquireFunction() 212 #else 213 #define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("mcr p15, 0, %0, c7, c10, 5" : : "r"(0) : "memory") 214 #define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("mcr p15, 0, %0, c7, c10, 5" : : "r"(0) : "memory") 215 #endif /* __thumb__ */ 216 #else 217 #define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("" : : : "memory") 218 #define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("" : : : "memory") 219 #endif /* __LINUX__ || __ANDROID__ */ 220 #endif /* __GNUC__ && __arm__ */ 221 #else 222 #if (defined(__SUNPRO_C) && (__SUNPRO_C >= 0x5120)) 223 /* This is correct for all CPUs on Solaris when using Solaris Studio 12.1+. */ 224 #include <mbarrier.h> 225 #define SDL_MemoryBarrierRelease() __machine_rel_barrier() 226 #define SDL_MemoryBarrierAcquire() __machine_acq_barrier() 227 #else 228 /* This is correct for the x86 and x64 CPUs, and we'll expand this over time. */ 229 #define SDL_MemoryBarrierRelease() SDL_CompilerBarrier() 230 #define SDL_MemoryBarrierAcquire() SDL_CompilerBarrier() 231 #endif 232 #endif 233 234 /** 235 * \brief A type representing an atomic integer value. It is a struct 236 * so people don't accidentally use numeric operations on it. 237 */ 238 typedef struct { int value; } SDL_atomic_t; 239 240 /** 241 * Set an atomic variable to a new value if it is currently an old value. 242 * 243 * ***Note: If you don't know what this function is for, you shouldn't use 244 * it!*** 245 * 246 * \param a a pointer to an SDL_atomic_t variable to be modified 247 * \param oldval the old value 248 * \param newval the new value 249 * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise. 250 * 251 * \since This function is available since SDL 2.0.0. 252 * 253 * \sa SDL_AtomicCASPtr 254 * \sa SDL_AtomicGet 255 * \sa SDL_AtomicSet 256 */ 257 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCAS(SDL_atomic_t *a, int oldval, int newval); 258 259 /** 260 * Set an atomic variable to a value. 261 * 262 * This function also acts as a full memory barrier. 263 * 264 * ***Note: If you don't know what this function is for, you shouldn't use 265 * it!*** 266 * 267 * \param a a pointer to an SDL_atomic_t variable to be modified 268 * \param v the desired value 269 * \returns the previous value of the atomic variable. 270 * 271 * \sa SDL_AtomicGet 272 */ 273 extern DECLSPEC int SDLCALL SDL_AtomicSet(SDL_atomic_t *a, int v); 274 275 /** 276 * Get the value of an atomic variable. 277 * 278 * ***Note: If you don't know what this function is for, you shouldn't use 279 * it!*** 280 * 281 * \param a a pointer to an SDL_atomic_t variable 282 * \returns the current value of an atomic variable. 283 * 284 * \sa SDL_AtomicSet 285 */ 286 extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_atomic_t *a); 287 288 /** 289 * Add to an atomic variable. 290 * 291 * This function also acts as a full memory barrier. 292 * 293 * ***Note: If you don't know what this function is for, you shouldn't use 294 * it!*** 295 * 296 * \param a a pointer to an SDL_atomic_t variable to be modified 297 * \param v the desired value to add 298 * \returns the previous value of the atomic variable. 299 * 300 * \sa SDL_AtomicDecRef 301 * \sa SDL_AtomicIncRef 302 */ 303 extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v); 304 305 /** 306 * \brief Increment an atomic variable used as a reference count. 307 */ 308 #ifndef SDL_AtomicIncRef 309 #define SDL_AtomicIncRef(a) SDL_AtomicAdd(a, 1) 310 #endif 311 312 /** 313 * \brief Decrement an atomic variable used as a reference count. 314 * 315 * \return SDL_TRUE if the variable reached zero after decrementing, 316 * SDL_FALSE otherwise 317 */ 318 #ifndef SDL_AtomicDecRef 319 #define SDL_AtomicDecRef(a) (SDL_AtomicAdd(a, -1) == 1) 320 #endif 321 322 /** 323 * Set a pointer to a new value if it is currently an old value. 324 * 325 * ***Note: If you don't know what this function is for, you shouldn't use 326 * it!*** 327 * 328 * \param a a pointer to a pointer 329 * \param oldval the old pointer value 330 * \param newval the new pointer value 331 * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise. 332 * 333 * \since This function is available since SDL 2.0.0. 334 * 335 * \sa SDL_AtomicCAS 336 * \sa SDL_AtomicGetPtr 337 * \sa SDL_AtomicSetPtr 338 */ 339 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCASPtr(void **a, void *oldval, void *newval); 340 341 /** 342 * Set a pointer to a value atomically. 343 * 344 * ***Note: If you don't know what this function is for, you shouldn't use 345 * it!*** 346 * 347 * \param a a pointer to a pointer 348 * \param v the desired pointer value 349 * \returns the previous value of the pointer. 350 * 351 * \sa SDL_AtomicCASPtr 352 * \sa SDL_AtomicGetPtr 353 */ 354 extern DECLSPEC void* SDLCALL SDL_AtomicSetPtr(void **a, void* v); 355 356 /** 357 * Get the value of a pointer atomically. 358 * 359 * ***Note: If you don't know what this function is for, you shouldn't use 360 * it!*** 361 * 362 * \param a a pointer to a pointer 363 * \returns the current value of a pointer. 364 * 365 * \sa SDL_AtomicCASPtr 366 * \sa SDL_AtomicSetPtr 367 */ 368 extern DECLSPEC void* SDLCALL SDL_AtomicGetPtr(void **a); 369 370 /* Ends C function definitions when using C++ */ 371 #ifdef __cplusplus 372 } 373 #endif 374 375 #include "close_code.h" 376 377 #endif /* SDL_atomic_h_ */ 378 379 /* vi: set ts=4 sw=4 expandtab: */ 380