From 77dd2685ec3814b193964deda1e28877c0d8d98c Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Fri, 20 Feb 2026 10:45:39 -0500 Subject: [PATCH] include: More `\threadsafety` documentation. Reference Issue #7140. (cherry picked from commit 1223767b2c06c6bd57ad225d0a10d5b87663a6e4) --- 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 c60e4d2612..9f03aa90d0 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 cc8ed0aa00..af604e2c7c 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 36a4121682..6b0e171b4a 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 9afcf7ecb4..654c005580 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 094e92ee76..0616cc2758 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 d287411d34..87257d1158 100644 --- a/include/SDL3/SDL_render.h +++ b/include/SDL3/SDL_render.h @@ -2509,6 +2509,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 @@ -2530,6 +2532,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 119c1f3f62..1c4d8da63a 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 2d2be82a32..ec23a1fe78 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