mirror
/
SDL
mirror of https://github.com/libsdl-org/SDL.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs: Added more '\threadsafety` tags. 

Reference Issue #7140.
This commit is contained in:
Ryan C. Gordon 2024-10-24 14:36:06 -04:00
parent 731853077a
commit 10e52e1899
No known key found for this signature in database
GPG Key ID: FA148B892AB48044
7 changed files with 127 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
include/SDL3/SDL_assert.h
View File

@ -116,7 +116,7 @@ extern "C" {
* isn't supported (SDL doesn't know how to trigger a breakpoint), this macro
* does nothing.
*
* \threadsafety It is safe to call this function from any thread.
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
@ -240,6 +240,8 @@ typedef struct SDL_AssertData
* \param line line number.
* \returns assert state.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*/
extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *data,
@ -305,6 +307,8 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
*
* \param condition boolean value to test.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_assert(condition) if (assertion_enabled && (condition)) { trigger_assertion; }
@ -336,6 +340,8 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
*
* \param condition boolean value to test.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_assert_release(condition) SDL_disabled_assert(condition)
@ -363,6 +369,8 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
*
* \param condition boolean value to test.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_assert_paranoid(condition) SDL_disabled_assert(condition)
@ -389,7 +397,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
#endif
/**
* An assertion test that always performed.
* An assertion test that is always performed.
*
* This macro is always enabled no matter what SDL_ASSERT_LEVEL is set to. You
* almost never want to use this, as it could trigger on an end-user's system,
@ -405,6 +413,8 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
*
* \param condition boolean value to test.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_assert_always(condition) SDL_enabled_assert(condition)
@ -418,6 +428,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
* \param userdata what was passed as `userdata` to SDL_SetAssertionHandler().
* \returns an SDL_AssertState value indicating how to handle the failure.
*
* \threadsafety This callback may be called from any thread that triggers an
* assert at any time.
*
* \since This datatype is available since SDL 3.1.3.
*/
typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)(
@ -440,6 +453,8 @@ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)(
* fails or NULL for the default handler.
* \param userdata a pointer that is passed to `handler`.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_GetAssertionHandler
@ -459,6 +474,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetAssertionHandler(
* \returns the default SDL_AssertionHandler that is called when an assert
* triggers.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_GetAssertionHandler
@ -482,6 +499,8 @@ extern SDL_DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(
* was passed to SDL_SetAssertionHandler().
* \returns the SDL_AssertionHandler that is called when an assert triggers.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_SetAssertionHandler
@ -508,7 +527,13 @@ extern SDL_DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void **
* ```
*
* \returns a list of all failed assertions or NULL if the list is empty. This
* memory should not be modified or freed by the application.
* memory should not be modified or freed by the application. This
* pointer remains valid until the next call to SDL_Quit() or
* SDL_ResetAssertionReport().
*
* \threadsafety This function is not thread safe. Other threads calling
* SDL_ResetAssertionReport() simultaneously, may render the
* returned pointer invalid.
*
* \since This function is available since SDL 3.1.3.
*
@ -524,6 +549,10 @@ extern SDL_DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void);
* no items. In addition, any previously-triggered assertions will be reset to
* a trigger_count of zero, and their always_ignore state will be false.
*
* \threadsafety This function is not thread safe. Other threads triggering
* an assertion, or simultaneously calling this function may
* cause memory leaks or crashes.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_GetAssertionReport

10
include/SDL3/SDL_atomic.h
View File

@ -90,6 +90,8 @@ typedef int SDL_SpinLock;
* \param lock a pointer to a lock variable.
* \returns true if the lock succeeded, false if the lock is already held.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_LockSpinlock
@ -105,6 +107,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_TryLockSpinlock(SDL_SpinLock *lock);
*
* \param lock a pointer to a lock variable.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_TryLockSpinlock
@ -122,6 +126,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockSpinlock(SDL_SpinLock *lock);
*
* \param lock a pointer to a lock variable.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_LockSpinlock
@ -415,6 +421,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddAtomicInt(SDL_AtomicInt *a, int v);
* \param a a pointer to an SDL_AtomicInt to increment.
* \returns the previous value of the atomic variable.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_AtomicDecRef
@ -433,6 +441,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddAtomicInt(SDL_AtomicInt *a, int v);
* \returns true if the variable reached zero after decrementing, false
* otherwise.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*
* \sa SDL_AtomicIncRef

2
include/SDL3/SDL_audio.h
View File

@ -966,6 +966,8 @@ extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_CreateAudioStream(const SDL_Au
* \returns a valid property ID on success or 0 on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*/
extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_AudioStream *stream);

2
include/SDL3/SDL_blendmode.h
View File

@ -177,6 +177,8 @@ typedef enum SDL_BlendFactor
* \returns an SDL_BlendMode that represents the chosen factors and
* operations.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_SetRenderDrawBlendMode

22
include/SDL3/SDL_clipboard.h
View File

@ -49,6 +49,8 @@ extern "C" {
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \threadsafety You may only call this function from the main thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_GetClipboardText
@ -66,6 +68,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardText(const char *text);
* SDL_GetError() for more information. This should be freed with
* SDL_free() when it is no longer needed.
*
* \threadsafety You may only call this function from the main thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_HasClipboardText
@ -78,6 +82,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetClipboardText(void);
*
* \returns true if the clipboard has text, or false if it does not.
*
* \threadsafety You may only call this function from the main thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_GetClipboardText
@ -92,6 +98,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardText(void);
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \threadsafety You may only call this function from the main thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_GetPrimarySelectionText
@ -109,6 +117,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetPrimarySelectionText(const char *text);
* failure; call SDL_GetError() for more information. This should be
* freed with SDL_free() when it is no longer needed.
*
* \threadsafety You may only call this function from the main thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_HasPrimarySelectionText
@ -122,6 +132,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_GetPrimarySelectionText(void);
*
* \returns true if the primary selection has text, or false if it does not.
*
* \threadsafety You may only call this function from the main thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_GetPrimarySelectionText
@ -187,6 +199,8 @@ typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata);
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \threadsafety You may only call this function from the main thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_ClearClipboardData
@ -201,6 +215,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
* \threadsafety You may only call this function from the main thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_SetClipboardData
@ -219,6 +235,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ClearClipboardData(void);
* for more information. This should be freed with SDL_free() when it
* is no longer needed.
*
* \threadsafety You may only call this function from the main thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_HasClipboardData
@ -233,6 +251,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetClipboardData(const char *mime_type, s
* \returns true if there exists data in clipboard for the provided mime type,
* false if it does not.
*
* \threadsafety You may only call this function from the main thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_SetClipboardData
@ -249,6 +269,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasClipboardData(const char *mime_type);
* failure; call SDL_GetError() for more information. This should be
* freed with SDL_free() when it is no longer needed.
*
* \threadsafety You may only call this function from the main thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_SetClipboardData

16
include/SDL3/SDL_endian.h
View File

@ -404,6 +404,8 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; }
* \param x the value to swap, in littleendian byte order.
* \returns `x` in native byte order.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_Swap16LE(x) SwapOnlyIfNecessary(x)
@ -418,6 +420,8 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; }
* \param x the value to swap, in littleendian byte order.
* \returns `x` in native byte order.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_Swap32LE(x) SwapOnlyIfNecessary(x)
@ -432,6 +436,8 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; }
* \param x the value to swap, in littleendian byte order.
* \returns `x` in native byte order.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_Swap64LE(x) SwapOnlyIfNecessary(x)
@ -446,6 +452,8 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; }
* \param x the value to swap, in littleendian byte order.
* \returns `x` in native byte order.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_SwapFloatLE(x) SwapOnlyIfNecessary(x)
@ -460,6 +468,8 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; }
* \param x the value to swap, in bigendian byte order.
* \returns `x` in native byte order.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_Swap16BE(x) SwapOnlyIfNecessary(x)
@ -474,6 +484,8 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; }
* \param x the value to swap, in bigendian byte order.
* \returns `x` in native byte order.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_Swap32BE(x) SwapOnlyIfNecessary(x)
@ -488,6 +500,8 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; }
* \param x the value to swap, in bigendian byte order.
* \returns `x` in native byte order.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_Swap64BE(x) SwapOnlyIfNecessary(x)
@ -502,6 +516,8 @@ SDL_FORCE_INLINE Uint32 SDL_Swap64(Uint64 x) { return x_but_byteswapped; }
* \param x the value to swap, in bigendian byte order.
* \returns `x` in native byte order.
*
* \threadsafety It is safe to call this macro from any thread.
*
* \since This macro is available since SDL 3.1.3.
*/
#define SDL_SwapFloatBE(x) SwapOnlyIfNecessary(x)

54
include/SDL3/SDL_events.h
View File

@ -1007,10 +1007,6 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL
*
* This function updates the event queue and internal input device state.
*
* **WARNING**: This should only be run in the thread that initialized the
* video subsystem, and for extra safety, you should consider only doing those
* things on the main thread in any case.
*
* SDL_PumpEvents() gathers all the pending input information from devices and
* places it in the event queue. Without calls to SDL_PumpEvents() no events
* would ever be placed on the queue. Often the need for calls to
@ -1019,6 +1015,10 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL
* polling or waiting for events (e.g. you are filtering them), then you must
* call SDL_PumpEvents() to force an event queue update.
*
* \threadsafety This should only be run in the thread that initialized the
* video subsystem, and for extra safety, you should consider
* only doing those things on the main thread in any case.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_PollEvent
@ -1060,8 +1060,6 @@ typedef enum SDL_EventAction
* Otherwise, the events may not be ready to be filtered when you call
* SDL_PeepEvents().
*
* This function is thread-safe.
*
* \param events destination buffer for the retrieved events, may be NULL to
* leave the events in the queue and return the number of events
* that would have been stored.
@ -1076,6 +1074,8 @@ typedef enum SDL_EventAction
* \returns the number of events actually stored or -1 on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_PollEvent
@ -1095,6 +1095,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event *events, int numevents,
* \returns true if events matching `type` are present, or false if events
* matching `type` are not present.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_HasEvents
@ -1114,6 +1116,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasEvent(Uint32 type);
* \returns true if events with type >= `minType` and <= `maxType` are
* present, or false if not.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_HasEvents
@ -1140,6 +1144,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
*
* \param type the type of event to be cleared; see SDL_EventType for details.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_FlushEvents
@ -1165,6 +1171,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
* \param maxType the high end of event type to be cleared, inclusive; see
* SDL_EventType for details.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_FlushEvent
@ -1207,6 +1215,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType)
* the queue, or NULL.
* \returns true if this got an event or false if there are none available.
*
* \threadsafety This should only be run in the thread that initialized the
* video subsystem, and for extra safety, you should consider
* only doing those things on the main thread in any case.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_PushEvent
@ -1229,6 +1241,10 @@ extern SDL_DECLSPEC bool SDLCALL SDL_PollEvent(SDL_Event *event);
* \returns true on success or false if there was an error while waiting for
* events; call SDL_GetError() for more information.
*
* \threadsafety This should only be run in the thread that initialized the
* video subsystem, and for extra safety, you should consider
* only doing those things on the main thread in any case.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_PollEvent
@ -1257,6 +1273,10 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WaitEvent(SDL_Event *event);
* \returns true if this got an event or false if the timeout elapsed without
* any events available.
*
* \threadsafety This should only be run in the thread that initialized the
* video subsystem, and for extra safety, you should consider
* only doing those things on the main thread in any case.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_PollEvent
@ -1277,8 +1297,6 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 t
* Note: Pushing device input events onto the queue doesn't modify the state
* of the device within SDL.
*
* This function is thread-safe, and can be called from other threads safely.
*
* Note: Events pushed onto the queue with SDL_PushEvent() get passed through
* the event filter but events added with SDL_PeepEvents() do not.
*
@ -1291,6 +1309,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 t
* call SDL_GetError() for more information. A common reason for
* error is the event queue being full.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_PeepEvents
@ -1354,9 +1374,7 @@ typedef bool (SDLCALL *SDL_EventFilter)(void *userdata, SDL_Event *event);
* \param filter an SDL_EventFilter function to call when an event happens.
* \param userdata a pointer that is passed to `filter`.
*
* \threadsafety SDL may call the filter callback at any time from any thread;
* the application is responsible for locking resources the
* callback touches that need to be protected.
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
@ -1379,6 +1397,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, void
* be stored here.
* \returns true on success or false if there is no event filter set.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_SetEventFilter
@ -1426,6 +1446,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, void
* \param filter the function originally passed to SDL_AddEventWatch().
* \param userdata the pointer originally passed to SDL_AddEventWatch().
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_AddEventWatch
@ -1443,6 +1465,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_RemoveEventWatch(SDL_EventFilter filter, vo
* \param filter the SDL_EventFilter function to call when an event happens.
* \param userdata a pointer that is passed to `filter`.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_GetEventFilter
@ -1456,6 +1480,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, void *
* \param type the type of event; see SDL_EventType for details.
* \param enabled whether to process the event or not.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_EventEnabled
@ -1468,6 +1494,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetEventEnabled(Uint32 type, bool enabled);
* \param type the type of event; see SDL_EventType for details.
* \returns true if the event is being processed, false otherwise.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_SetEventEnabled
@ -1482,6 +1510,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_EventEnabled(Uint32 type);
* \returns the beginning event number, or 0 if numevents is invalid or if
* there are not enough user-defined events left.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_PushEvent
@ -1494,6 +1524,8 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
* \param event an event containing a `windowID`.
* \returns the associated window on success or NULL if there is none.
*
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.3.
*
* \sa SDL_PollEvent