| Safe Haskell | None |
|---|---|
| Language | GHC2021 |
SDL3.Sys.Bindgen.Atomic
Description
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:
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. An atomic spinlock.
The atomic locks are efficient spinlocks using CPU instructions, but are vulnerable to starvation and can spin forever if a thread holding a lock has been terminated. For this reason you should minimize the code executed inside an atomic lock and never do expensive things like API or system calls while holding them.
They are also vulnerable to starvation if the thread holding the lock is lower priority than other threads and doesn't get scheduled. In general you should use mutexes instead, since they have better performance and contention behavior.
The atomic locks are not safe to lock recursively.
Porting Note: The spin lock functions and type are required and can not be emulated because they are used in the atomic emulation code.
Synopsis
- newtype SDL_SpinLock = SDL_SpinLock {}
- data SDL_AtomicInt = SDL_AtomicInt {}
- data SDL_AtomicU32 = SDL_AtomicU32 {}
Documentation
newtype SDL_SpinLock Source #
- C declaration
SDL_SpinLock, defined atSDL3/SDL_atomic.h 82:13
Constructors
| SDL_SpinLock | |
Instances
data SDL_AtomicInt Source #
A type representing an atomic integer value.
This can be used to manage a value that is synchronized across multiple CPUs without a race condition; when an app sets a value with SDL_SetAtomicInt all other threads, regardless of the CPU it is running on, will see that value when retrieved with SDL_GetAtomicInt, regardless of CPU caches, etc.
This is also useful for atomic compare-and-swap operations: a thread can change the value as long as its current value matches expectations. When done in a loop, one can guarantee data consistency across threads without a lock (but the usual warnings apply: if you don't know what you're doing, or you don't do it carefully, you can confidently cause any number of disasters with this, so in most cases, you should use a mutex instead of this!).
This is a struct so people don't accidentally use numeric operations on it directly. You have to use SDL atomic functions.
- See also
sDL_CompareAndSwapAtomicInt,sDL_GetAtomicInt,sDL_SetAtomicInt,sDL_AddAtomicInt- C declaration
struct SDL_AtomicInt, defined atSDL3/SDL_atomic.h 405:16
Since: 3.2.0
Constructors
| SDL_AtomicInt | |
Instances
| Storable SDL_AtomicInt Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Methods sizeOf :: SDL_AtomicInt -> Int # alignment :: SDL_AtomicInt -> Int # peekElemOff :: Ptr SDL_AtomicInt -> Int -> IO SDL_AtomicInt # pokeElemOff :: Ptr SDL_AtomicInt -> Int -> SDL_AtomicInt -> IO () # peekByteOff :: Ptr b -> Int -> IO SDL_AtomicInt # pokeByteOff :: Ptr b -> Int -> SDL_AtomicInt -> IO () # peek :: Ptr SDL_AtomicInt -> IO SDL_AtomicInt # poke :: Ptr SDL_AtomicInt -> SDL_AtomicInt -> IO () # | |||||
| Generic SDL_AtomicInt Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Associated Types
| |||||
| Show SDL_AtomicInt Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Methods showsPrec :: Int -> SDL_AtomicInt -> ShowS # show :: SDL_AtomicInt -> String # showList :: [SDL_AtomicInt] -> ShowS # | |||||
| Eq SDL_AtomicInt Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Methods (==) :: SDL_AtomicInt -> SDL_AtomicInt -> Bool # (/=) :: SDL_AtomicInt -> SDL_AtomicInt -> Bool # | |||||
| ReadRaw SDL_AtomicInt Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Methods readRaw :: Ptr SDL_AtomicInt -> IO SDL_AtomicInt # | |||||
| StaticSize SDL_AtomicInt Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic | |||||
| WriteRaw SDL_AtomicInt Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Methods writeRaw :: Ptr SDL_AtomicInt -> SDL_AtomicInt -> IO () # | |||||
| IsStruct SDL_AtomicInt Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Methods zero :: SDL_AtomicInt # | |||||
| HasCField SDL_AtomicInt "value" Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Associated Types
| |||||
| ty ~ CInt => HasField "value" SDL_AtomicInt ty Source # |
| ||||
Defined in SDL3.Sys.Bindgen.Atomic Methods hasField :: SDL_AtomicInt -> (ty -> SDL_AtomicInt, ty) # | |||||
| ty ~ CInt => HasField "value" (Ptr SDL_AtomicInt) (Ptr ty :: Type) Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Methods getField :: Ptr SDL_AtomicInt -> Ptr ty # | |||||
| type Rep SDL_AtomicInt Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic type Rep SDL_AtomicInt = D1 ('MetaData "SDL_AtomicInt" "SDL3.Sys.Bindgen.Atomic" "sdl3-bindgen-sys-0.0.1.0-inplace" 'False) (C1 ('MetaCons "SDL_AtomicInt" 'PrefixI 'True) (S1 ('MetaSel ('Just "value") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 CInt))) | |||||
| type CFieldType SDL_AtomicInt "value" Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic | |||||
data SDL_AtomicU32 Source #
A type representing an atomic unsigned 32-bit value.
This can be used to manage a value that is synchronized across multiple CPUs without a race condition; when an app sets a value with SDL_SetAtomicU32 all other threads, regardless of the CPU it is running on, will see that value when retrieved with SDL_GetAtomicU32, regardless of CPU caches, etc.
This is also useful for atomic compare-and-swap operations: a thread can change the value as long as its current value matches expectations. When done in a loop, one can guarantee data consistency across threads without a lock (but the usual warnings apply: if you don't know what you're doing, or you don't do it carefully, you can confidently cause any number of disasters with this, so in most cases, you should use a mutex instead of this!).
This is a struct so people don't accidentally use numeric operations on it directly. You have to use SDL atomic functions.
- See also
sDL_CompareAndSwapAtomicU32,sDL_GetAtomicU32,sDL_SetAtomicU32- C declaration
struct SDL_AtomicU32, defined atSDL3/SDL_atomic.h 550:16
Since: 3.2.0
Constructors
| SDL_AtomicU32 | |
Instances
| Storable SDL_AtomicU32 Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Methods sizeOf :: SDL_AtomicU32 -> Int # alignment :: SDL_AtomicU32 -> Int # peekElemOff :: Ptr SDL_AtomicU32 -> Int -> IO SDL_AtomicU32 # pokeElemOff :: Ptr SDL_AtomicU32 -> Int -> SDL_AtomicU32 -> IO () # peekByteOff :: Ptr b -> Int -> IO SDL_AtomicU32 # pokeByteOff :: Ptr b -> Int -> SDL_AtomicU32 -> IO () # peek :: Ptr SDL_AtomicU32 -> IO SDL_AtomicU32 # poke :: Ptr SDL_AtomicU32 -> SDL_AtomicU32 -> IO () # | |||||
| Generic SDL_AtomicU32 Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Associated Types
| |||||
| Show SDL_AtomicU32 Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Methods showsPrec :: Int -> SDL_AtomicU32 -> ShowS # show :: SDL_AtomicU32 -> String # showList :: [SDL_AtomicU32] -> ShowS # | |||||
| Eq SDL_AtomicU32 Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Methods (==) :: SDL_AtomicU32 -> SDL_AtomicU32 -> Bool # (/=) :: SDL_AtomicU32 -> SDL_AtomicU32 -> Bool # | |||||
| ReadRaw SDL_AtomicU32 Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Methods readRaw :: Ptr SDL_AtomicU32 -> IO SDL_AtomicU32 # | |||||
| StaticSize SDL_AtomicU32 Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic | |||||
| WriteRaw SDL_AtomicU32 Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Methods writeRaw :: Ptr SDL_AtomicU32 -> SDL_AtomicU32 -> IO () # | |||||
| IsStruct SDL_AtomicU32 Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Methods zero :: SDL_AtomicU32 # | |||||
| HasCField SDL_AtomicU32 "value" Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Associated Types
| |||||
| ty ~ Uint32 => HasField "value" SDL_AtomicU32 ty Source # |
| ||||
Defined in SDL3.Sys.Bindgen.Atomic Methods hasField :: SDL_AtomicU32 -> (ty -> SDL_AtomicU32, ty) # | |||||
| ty ~ Uint32 => HasField "value" (Ptr SDL_AtomicU32) (Ptr ty :: Type) Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic Methods getField :: Ptr SDL_AtomicU32 -> Ptr ty # | |||||
| type Rep SDL_AtomicU32 Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic type Rep SDL_AtomicU32 = D1 ('MetaData "SDL_AtomicU32" "SDL3.Sys.Bindgen.Atomic" "sdl3-bindgen-sys-0.0.1.0-inplace" 'False) (C1 ('MetaCons "SDL_AtomicU32" 'PrefixI 'True) (S1 ('MetaSel ('Just "value") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 Uint32))) | |||||
| type CFieldType SDL_AtomicU32 "value" Source # | |||||
Defined in SDL3.Sys.Bindgen.Atomic | |||||