From 10e52e1899df56f9c242072dd3654a05a46988cf Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Thu, 24 Oct 2024 14:36:06 -0400
Subject: [PATCH] docs: Added more '\threadsafety` tags.
Reference Issue #7140.
---
include/SDL3/SDL_assert.h | 35 +++++++++++++++++++++--
include/SDL3/SDL_atomic.h | 10 +++++++
include/SDL3/SDL_audio.h | 2 ++
include/SDL3/SDL_blendmode.h | 2 ++
include/SDL3/SDL_clipboard.h | 22 +++++++++++++++
include/SDL3/SDL_endian.h | 16 +++++++++++
include/SDL3/SDL_events.h | 54 ++++++++++++++++++++++++++++--------
7 files changed, 127 insertions(+), 14 deletions(-)
diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h
index 78a28674cf10d..f52eecafad37b 100644
--- a/include/SDL3/SDL_assert.h
+++ b/include/SDL3/SDL_assert.h
@@ -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
diff --git a/include/SDL3/SDL_atomic.h b/include/SDL3/SDL_atomic.h
index 45e7b678836a1..479e8edd0e030 100644
--- a/include/SDL3/SDL_atomic.h
+++ b/include/SDL3/SDL_atomic.h
@@ -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
diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index 6f9d2eba53e40..567b0616e3cd2 100644
--- a/include/SDL3/SDL_audio.h
+++ b/include/SDL3/SDL_audio.h
@@ -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);
diff --git a/include/SDL3/SDL_blendmode.h b/include/SDL3/SDL_blendmode.h
index be89a48b9875e..0998c1a1eef05 100644
--- a/include/SDL3/SDL_blendmode.h
+++ b/include/SDL3/SDL_blendmode.h
@@ -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
diff --git a/include/SDL3/SDL_clipboard.h b/include/SDL3/SDL_clipboard.h
index 1c0359a69f9d6..b23bdb7866f7e 100644
--- a/include/SDL3/SDL_clipboard.h
+++ b/include/SDL3/SDL_clipboard.h
@@ -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
diff --git a/include/SDL3/SDL_endian.h b/include/SDL3/SDL_endian.h
index 5a91ae6afcaa5..8881804431c9e 100644
--- a/include/SDL3/SDL_endian.h
+++ b/include/SDL3/SDL_endian.h
@@ -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)
diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h
index 8987134fb04b4..e15428ef57aa9 100644
--- a/include/SDL3/SDL_events.h
+++ b/include/SDL3/SDL_events.h
@@ -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