11/*
22 Simple DirectMedia Layer
3- Copyright (C) 1997-2024 Sam Lantinga <[email protected] > 3+ Copyright (C) 1997-2025 Sam Lantinga <[email protected] > 44
55 This software is provided 'as-is', without any express or implied
66 warranty. In no event will the authors be held liable for any damages
2020*/
2121
2222/**
23- * \file SDL_atomic.h
23+ * # CategoryAtomic
2424 *
2525 * Atomic operations.
2626 *
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.
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.
3230 *
33- * The list of "safe" functions to use are:
34- * SDL_AtomicLock()
35- * SDL_AtomicUnlock()
36- * SDL_AtomicIncRef()
37- * SDL_AtomicDecRef()
31+ * ***Seriously, here be dragons!***
3832 *
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
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
4536 *
4637 * There's also lots of good information here:
47- * http://www.1024cores.net/home/lock-free-algorithms
48- * http://preshing.com/
4938 *
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.
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.
5546 *
5647 * All of the atomic operations that modify memory are full memory barriers.
5748 */
@@ -94,7 +85,7 @@ typedef int SDL_SpinLock;
9485 * ***Please note that spinlocks are dangerous if you don't know what you're
9586 * doing. Please be careful using any sort of spinlock!***
9687 *
97- * \param lock a pointer to a lock variable
88+ * \param lock a pointer to a lock variable.
9889 * \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already
9990 * held.
10091 *
@@ -111,7 +102,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTryLock(SDL_SpinLock *lock);
111102 * ***Please note that spinlocks are dangerous if you don't know what you're
112103 * doing. Please be careful using any sort of spinlock!***
113104 *
114- * \param lock a pointer to a lock variable
105+ * \param lock a pointer to a lock variable.
115106 *
116107 * \since This function is available since SDL 2.0.0.
117108 *
@@ -128,7 +119,7 @@ extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock);
128119 * ***Please note that spinlocks are dangerous if you don't know what you're
129120 * doing. Please be careful using any sort of spinlock!***
130121 *
131- * \param lock a pointer to a lock variable
122+ * \param lock a pointer to a lock variable.
132123 *
133124 * \since This function is available since SDL 2.0.0.
134125 *
@@ -257,20 +248,23 @@ typedef void (*SDL_KernelMemoryBarrierFunc)();
257248
258249
259250/**
260- * \brief A type representing an atomic integer value. It is a struct
261- * so people don't accidentally use numeric operations on it.
251+ * A type representing an atomic integer value.
252+ *
253+ * It is a struct so people don't accidentally use numeric operations on it.
262254 */
263- typedef struct { int value ; } SDL_atomic_t ;
255+ typedef struct SDL_atomic_t {
256+ int value ;
257+ } SDL_atomic_t ;
264258
265259/**
266260 * Set an atomic variable to a new value if it is currently an old value.
267261 *
268262 * ***Note: If you don't know what this function is for, you shouldn't use
269263 * it!***
270264 *
271- * \param a a pointer to an SDL_atomic_t variable to be modified
272- * \param oldval the old value
273- * \param newval the new value
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.
274268 * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
275269 *
276270 * \since This function is available since SDL 2.0.0.
@@ -289,8 +283,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCAS(SDL_atomic_t *a, int oldval, int
289283 * ***Note: If you don't know what this function is for, you shouldn't use
290284 * it!***
291285 *
292- * \param a a pointer to an SDL_atomic_t variable to be modified
293- * \param v the desired value
286+ * \param a a pointer to an SDL_atomic_t variable to be modified.
287+ * \param v the desired value.
294288 * \returns the previous value of the atomic variable.
295289 *
296290 * \since This function is available since SDL 2.0.2.
@@ -305,7 +299,7 @@ extern DECLSPEC int SDLCALL SDL_AtomicSet(SDL_atomic_t *a, int v);
305299 * ***Note: If you don't know what this function is for, you shouldn't use
306300 * it!***
307301 *
308- * \param a a pointer to an SDL_atomic_t variable
302+ * \param a a pointer to an SDL_atomic_t variable.
309303 * \returns the current value of an atomic variable.
310304 *
311305 * \since This function is available since SDL 2.0.2.
@@ -322,8 +316,8 @@ extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_atomic_t *a);
322316 * ***Note: If you don't know what this function is for, you shouldn't use
323317 * it!***
324318 *
325- * \param a a pointer to an SDL_atomic_t variable to be modified
326- * \param v the desired value to add
319+ * \param a a pointer to an SDL_atomic_t variable to be modified.
320+ * \param v the desired value to add.
327321 * \returns the previous value of the atomic variable.
328322 *
329323 * \since This function is available since SDL 2.0.2.
@@ -356,9 +350,9 @@ extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *a, int v);
356350 * ***Note: If you don't know what this function is for, you shouldn't use
357351 * it!***
358352 *
359- * \param a a pointer to a pointer
360- * \param oldval the old pointer value
361- * \param newval the new pointer value
353+ * \param a a pointer to a pointer.
354+ * \param oldval the old pointer value.
355+ * \param newval the new pointer value.
362356 * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
363357 *
364358 * \since This function is available since SDL 2.0.0.
@@ -375,8 +369,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCASPtr(void **a, void *oldval, void *
375369 * ***Note: If you don't know what this function is for, you shouldn't use
376370 * it!***
377371 *
378- * \param a a pointer to a pointer
379- * \param v the desired pointer value
372+ * \param a a pointer to a pointer.
373+ * \param v the desired pointer value.
380374 * \returns the previous value of the pointer.
381375 *
382376 * \since This function is available since SDL 2.0.2.
@@ -392,7 +386,7 @@ extern DECLSPEC void* SDLCALL SDL_AtomicSetPtr(void **a, void* v);
392386 * ***Note: If you don't know what this function is for, you shouldn't use
393387 * it!***
394388 *
395- * \param a a pointer to a pointer
389+ * \param a a pointer to a pointer.
396390 * \returns the current value of a pointer.
397391 *
398392 * \since This function is available since SDL 2.0.2.
0 commit comments