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