From 10e52e1899df56f9c242072dd3654a05a46988cf Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <icculus@icculus.org>
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 78a28674cf..f52eecafad 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 45e7b67883..479e8edd0e 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 6f9d2eba53..567b0616e3 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 be89a48b98..0998c1a1ee 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 1c0359a69f..b23bdb7866 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 5a91ae6afc..8881804431 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 8987134fb0..e15428ef57 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