Module atomic

Available on crate feature dep_sdl3 only.

Atomic operations.

IMPORTANT: If you are not an expert in concurrent lockless programming, you should not be using any functions in this file. You should be protecting your data structures with full mutexes instead.

Seriously, here be dragons!

You can find out a little more about lockless programming and the subtle issues that can arise here: https://learn.microsoft.com/en-us/windows/win32/dxtecharts/lockless-programming

There’s also lots of good information here:

• https://www.1024cores.net/home/lock-free-algorithms
• https://preshing.com/

These operations may or may not actually be implemented using processor specific atomic operations. When possible they are implemented as true processor specific atomic operations. When that is not possible the are implemented using locks that do use the available atomic operations.

All of the atomic operations that modify memory are full memory barriers.

Structs

SDL_AtomicInt

A type representing an atomic integer value.

SDL_AtomicU32

A type representing an atomic unsigned 32-bit value.

Functions

SDL_AddAtomicInt^⚠

Add to an atomic variable.

SDL_AtomicDecRef^⚠

Decrement an atomic variable used as a reference count.

SDL_AtomicIncRef^⚠

Increment an atomic variable used as a reference count.

SDL_CPUPauseInstruction

SDL_CompareAndSwapAtomicInt^⚠

Set an atomic variable to a new value if it is currently an old value.

SDL_CompareAndSwapAtomicPointer^⚠

Set a pointer to a new value if it is currently an old value.

SDL_CompareAndSwapAtomicU32^⚠

Set an atomic variable to a new value if it is currently an old value.

SDL_CompilerBarrier

SDL_GetAtomicInt^⚠

Get the value of an atomic variable.

SDL_GetAtomicPointer^⚠

Get the value of a pointer atomically.

SDL_GetAtomicU32^⚠

Get the value of an atomic variable.

SDL_LockSpinlock^⚠

Lock a spin lock by setting it to a non-zero value.

SDL_MemoryBarrierAcquire

SDL_MemoryBarrierAcquireFunction^⚠

Insert a memory acquire barrier (function version).

SDL_MemoryBarrierRelease

SDL_MemoryBarrierReleaseFunction^⚠

Insert a memory release barrier (function version).

SDL_SetAtomicInt^⚠

Set an atomic variable to a value.

SDL_SetAtomicPointer^⚠

Set a pointer to a value atomically.

SDL_SetAtomicU32^⚠

Set an atomic variable to a value.

SDL_TryLockSpinlock^⚠

Try to lock a spin lock by setting it to a non-zero value.

SDL_UnlockSpinlock^⚠

Unlock a spin lock by setting it to 0.

Type Aliases

SDL_SpinLock

An atomic spinlock.