From 1223767b2c06c6bd57ad225d0a10d5b87663a6e4 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Fri, 20 Feb 2026 10:45:39 -0500
Subject: [PATCH] include: More `\threadsafety` documentation.
Reference Issue #7140.
---
include/SDL3/SDL_locale.h | 2 ++
include/SDL3/SDL_messagebox.h | 4 ++++
include/SDL3/SDL_metal.h | 6 ++++++
include/SDL3/SDL_misc.h | 2 ++
include/SDL3/SDL_power.h | 2 ++
include/SDL3/SDL_render.h | 4 ++++
include/SDL3/SDL_stdinc.h | 16 ++++++++++++++++
include/SDL3/SDL_system.h | 12 ++++++++++++
8 files changed, 48 insertions(+)
diff --git a/include/SDL3/SDL_locale.h b/include/SDL3/SDL_locale.h
index c60e4d2612c9b..9f03aa90d0556 100644
--- a/include/SDL3/SDL_locale.h
+++ b/include/SDL3/SDL_locale.h
@@ -102,6 +102,8 @@ typedef struct SDL_Locale
* allocation that should be freed with SDL_free() when it is no
* longer needed.
*
+ * \threadsafety This function is not thread safe.
+ *
* \since This function is available since SDL 3.2.0.
*/
extern SDL_DECLSPEC SDL_Locale ** SDLCALL SDL_GetPreferredLocales(int *count);
diff --git a/include/SDL3/SDL_messagebox.h b/include/SDL3/SDL_messagebox.h
index cc8ed0aa007bc..af604e2c7ceed 100644
--- a/include/SDL3/SDL_messagebox.h
+++ b/include/SDL3/SDL_messagebox.h
@@ -168,6 +168,8 @@ typedef struct SDL_MessageBoxData
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
+ * \threadsafety This function should only be called on the main thread.
+ *
* \since This function is available since SDL 3.2.0.
*
* \sa SDL_ShowSimpleMessageBox
@@ -210,6 +212,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *me
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
+ * \threadsafety This function should only be called on the main thread.
+ *
* \since This function is available since SDL 3.2.0.
*
* \sa SDL_ShowMessageBox
diff --git a/include/SDL3/SDL_metal.h b/include/SDL3/SDL_metal.h
index 36a4121682894..6b0e171b4aa34 100644
--- a/include/SDL3/SDL_metal.h
+++ b/include/SDL3/SDL_metal.h
@@ -65,6 +65,8 @@ typedef void *SDL_MetalView;
* \param window the window.
* \returns handle NSView or UIView.
*
+ * \threadsafety This function should only be called on the main thread.
+ *
* \since This function is available since SDL 3.2.0.
*
* \sa SDL_Metal_DestroyView
@@ -80,6 +82,8 @@ extern SDL_DECLSPEC SDL_MetalView SDLCALL SDL_Metal_CreateView(SDL_Window *windo
*
* \param view the SDL_MetalView object.
*
+ * \threadsafety This function should only be called on the main thread.
+ *
* \since This function is available since SDL 3.2.0.
*
* \sa SDL_Metal_CreateView
@@ -92,6 +96,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_Metal_DestroyView(SDL_MetalView view);
* \param view the SDL_MetalView object.
* \returns a pointer.
*
+ * \threadsafety This function should only be called on the main thread.
+ *
* \since This function is available since SDL 3.2.0.
*/
extern SDL_DECLSPEC void * SDLCALL SDL_Metal_GetLayer(SDL_MetalView view);
diff --git a/include/SDL3/SDL_misc.h b/include/SDL3/SDL_misc.h
index 9afcf7ecb444e..654c0055807ce 100644
--- a/include/SDL3/SDL_misc.h
+++ b/include/SDL3/SDL_misc.h
@@ -65,6 +65,8 @@ extern "C" {
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
+ * \threadsafety This function should only be called on the main thread.
+ *
* \since This function is available since SDL 3.2.0.
*/
extern SDL_DECLSPEC bool SDLCALL SDL_OpenURL(const char *url);
diff --git a/include/SDL3/SDL_power.h b/include/SDL3/SDL_power.h
index 094e92ee760ba..0616cc27588f8 100644
--- a/include/SDL3/SDL_power.h
+++ b/include/SDL3/SDL_power.h
@@ -93,6 +93,8 @@ typedef enum SDL_PowerState
* \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure;
* call SDL_GetError() for more information.
*
+ * \threadsafety This function is not thread safe.
+ *
* \since This function is available since SDL 3.2.0.
*/
extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *seconds, int *percent);
diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h
index a20ab9bca1a53..986130ce46b46 100644
--- a/include/SDL3/SDL_render.h
+++ b/include/SDL3/SDL_render.h
@@ -2507,6 +2507,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer,
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
+ * \threadsafety This function should only be called on the main thread.
+ *
* \since This function is available since SDL 3.4.0.
*
* \sa SDL_RenderGeometry
@@ -2528,6 +2530,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetRenderTextureAddressMode(SDL_Renderer *r
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
+ * \threadsafety This function should only be called on the main thread.
+ *
* \since This function is available since SDL 3.4.0.
*
* \sa SDL_SetRenderTextureAddressMode
diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h
index 119c1f3f62672..1c4d8da63ad3e 100644
--- a/include/SDL3/SDL_stdinc.h
+++ b/include/SDL3/SDL_stdinc.h
@@ -5815,6 +5815,8 @@ typedef struct SDL_iconv_data_t *SDL_iconv_t;
* \returns a handle that must be freed with SDL_iconv_close, or
* SDL_ICONV_ERROR on failure.
*
+ * \threadsafety It is safe to call this function from any thread.
+ *
* \since This function is available since SDL 3.2.0.
*
* \sa SDL_iconv
@@ -5830,6 +5832,8 @@ extern SDL_DECLSPEC SDL_iconv_t SDLCALL SDL_iconv_open(const char *tocode,
* \param cd The character set conversion handle.
* \returns 0 on success, or -1 on failure.
*
+ * \threadsafety It is safe to call this function from any thread.
+ *
* \since This function is available since SDL 3.2.0.
*
* \sa SDL_iconv
@@ -5868,6 +5872,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_iconv_close(SDL_iconv_t cd);
* \param outbytesleft The number of bytes in the output buffer.
* \returns the number of conversions on success, or a negative error code.
*
+ * \threadsafety Do not use the same SDL_iconv_t from two threads at once.
+ *
* \since This function is available since SDL 3.2.0.
*
* \sa SDL_iconv_open
@@ -5903,6 +5909,8 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_iconv(SDL_iconv_t cd, const char **inbuf,
* \param inbytesleft the size of the input string _in bytes_.
* \returns a new string, converted to the new encoding, or NULL on error.
*
+ * \threadsafety It is safe to call this function from any thread.
+ *
* \since This function is available since SDL 3.2.0.
*
* \sa SDL_iconv_open
@@ -5926,6 +5934,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode,
* \param S the string to convert.
* \returns a new string, converted to the new encoding, or NULL on error.
*
+ * \threadsafety It is safe to call this macro from any thread.
+ *
* \since This macro is available since SDL 3.2.0.
*/
#define SDL_iconv_utf8_locale(S) SDL_iconv_string("", "UTF-8", S, SDL_strlen(S)+1)
@@ -5940,6 +5950,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode,
* \param S the string to convert.
* \returns a new string, converted to the new encoding, or NULL on error.
*
+ * \threadsafety It is safe to call this macro from any thread.
+ *
* \since This macro is available since SDL 3.2.0.
*/
#define SDL_iconv_utf8_ucs2(S) SDL_reinterpret_cast(Uint16 *, SDL_iconv_string("UCS-2", "UTF-8", S, SDL_strlen(S)+1))
@@ -5954,6 +5966,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode,
* \param S the string to convert.
* \returns a new string, converted to the new encoding, or NULL on error.
*
+ * \threadsafety It is safe to call this macro from any thread.
+ *
* \since This macro is available since SDL 3.2.0.
*/
#define SDL_iconv_utf8_ucs4(S) SDL_reinterpret_cast(Uint32 *, SDL_iconv_string("UCS-4", "UTF-8", S, SDL_strlen(S)+1))
@@ -5968,6 +5982,8 @@ extern SDL_DECLSPEC char * SDLCALL SDL_iconv_string(const char *tocode,
* \param S the string to convert.
* \returns a new string, converted to the new encoding, or NULL on error.
*
+ * \threadsafety It is safe to call this macro from any thread.
+ *
* \since This macro is available since SDL 3.2.0.
*/
#define SDL_iconv_wchar_utf8(S) SDL_iconv_string("UTF-8", "WCHAR_T", SDL_reinterpret_cast(const char *, S), (SDL_wcslen(S)+1)*sizeof(wchar_t))
diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h
index 2d2be82a32da4..ec23a1fe78071 100644
--- a/include/SDL3/SDL_system.h
+++ b/include/SDL3/SDL_system.h
@@ -86,6 +86,8 @@ typedef bool (SDLCALL *SDL_WindowsMessageHook)(void *userdata, MSG *msg);
* \param callback the SDL_WindowsMessageHook function to call.
* \param userdata a pointer to pass to every iteration of `callback`.
*
+ * \threadsafety This function should only be called on the main thread.
+ *
* \since This function is available since SDL 3.2.0.
*
* \sa SDL_WindowsMessageHook
@@ -169,6 +171,8 @@ typedef bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent);
* \param callback the SDL_X11EventHook function to call.
* \param userdata a pointer to pass to every iteration of `callback`.
*
+ * \threadsafety This function should only be called on the main thread.
+ *
* \since This function is available since SDL 3.2.0.
*/
extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback, void *userdata);
@@ -186,6 +190,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback,
* \returns true on success or false 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.2.0.
*/
extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int priority);
@@ -202,6 +208,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriority(Sint64 threadID, int
* \returns true on success or false 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.2.0.
*/
extern SDL_DECLSPEC bool SDLCALL SDL_SetLinuxThreadPriorityAndPolicy(Sint64 threadID, int sdlPriority, int schedPolicy);
@@ -264,6 +272,8 @@ typedef void (SDLCALL *SDL_iOSAnimationCallback)(void *userdata);
* \returns true on success or false on failure; call SDL_GetError() for more
* information.
*
+ * \threadsafety This function should only be called on the main thread.
+ *
* \since This function is available since SDL 3.2.0.
*
* \sa SDL_SetiOSEventPump
@@ -277,6 +287,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetiOSAnimationCallback(SDL_Window *window,
*
* \param enabled true to enable the event pump, false to disable it.
*
+ * \threadsafety This function should only be called on the main thread.
+ *
* \since This function is available since SDL 3.2.0.
*
* \sa SDL_SetiOSAnimationCallback