From 2318961b6f2c7477ed01077f4b5e6456d7a9a702 Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Tue, 22 Oct 2024 13:47:28 -0400 Subject: [PATCH] docs: Add `\threadsafety` to some low-hanging fruit across a few headers. Reference Issue #7140. --- include/SDL3/SDL_cpuinfo.h | 36 ++++++++++++++++++++++++++++++++++++ include/SDL3/SDL_error.h | 10 ++++++++++ include/SDL3/SDL_stdinc.h | 8 ++++++++ include/SDL3/SDL_timer.h | 16 ++++++++++++++++ 4 files changed, 70 insertions(+) diff --git a/include/SDL3/SDL_cpuinfo.h b/include/SDL3/SDL_cpuinfo.h index ef4a90c697..cf77705fd7 100644 --- a/include/SDL3/SDL_cpuinfo.h +++ b/include/SDL3/SDL_cpuinfo.h @@ -60,6 +60,8 @@ extern "C" { * technologies such as hyperthreading, the number of logical cores * may be more than the number of physical cores. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetNumLogicalCPUCores(void); @@ -72,6 +74,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumLogicalCPUCores(void); * * \returns the L1 cache line size of the CPU, in bytes. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void); @@ -84,6 +88,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void); * * \returns true if the CPU has AltiVec features or false if not. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern SDL_DECLSPEC bool SDLCALL SDL_HasAltiVec(void); @@ -95,6 +101,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasAltiVec(void); * * \returns true if the CPU has MMX features or false if not. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern SDL_DECLSPEC bool SDLCALL SDL_HasMMX(void); @@ -106,6 +114,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasMMX(void); * * \returns true if the CPU has SSE features or false if not. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasSSE2 @@ -122,6 +132,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE(void); * * \returns true if the CPU has SSE2 features or false if not. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasSSE @@ -138,6 +150,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE2(void); * * \returns true if the CPU has SSE3 features or false if not. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasSSE @@ -154,6 +168,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE3(void); * * \returns true if the CPU has SSE4.1 features or false if not. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasSSE @@ -170,6 +186,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE41(void); * * \returns true if the CPU has SSE4.2 features or false if not. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasSSE @@ -186,6 +204,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasSSE42(void); * * \returns true if the CPU has AVX features or false if not. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasAVX2 @@ -200,6 +220,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX(void); * * \returns true if the CPU has AVX2 features or false if not. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasAVX @@ -214,6 +236,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX2(void); * * \returns true if the CPU has AVX-512F features or false if not. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasAVX @@ -230,6 +254,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasAVX512F(void); * * \returns true if the CPU has ARM SIMD features or false if not. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_HasNEON @@ -243,6 +269,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasARMSIMD(void); * * \returns true if the CPU has ARM NEON features or false if not. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern SDL_DECLSPEC bool SDLCALL SDL_HasNEON(void); @@ -255,6 +283,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasNEON(void); * * \returns true if the CPU has LOONGARCH LSX features or false if not. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern SDL_DECLSPEC bool SDLCALL SDL_HasLSX(void); @@ -267,6 +297,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasLSX(void); * * \returns true if the CPU has LOONGARCH LASX features or false if not. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern SDL_DECLSPEC bool SDLCALL SDL_HasLASX(void); @@ -276,6 +308,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasLASX(void); * * \returns the amount of RAM configured in the system in MiB. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetSystemRAM(void); @@ -295,6 +329,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSystemRAM(void); * \returns the alignment in bytes needed for available, known SIMD * instructions. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_aligned_alloc diff --git a/include/SDL3/SDL_error.h b/include/SDL3/SDL_error.h index 9f166292b1..3f0c804b10 100644 --- a/include/SDL3/SDL_error.h +++ b/include/SDL3/SDL_error.h @@ -78,6 +78,8 @@ extern "C" { * any. * \returns false. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_ClearError @@ -95,6 +97,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const cha * \param ap a variable argument list. * \returns false. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.1.4. * * \sa SDL_ClearError @@ -110,6 +114,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetErrorV(SDL_PRINTF_FORMAT_STRING const ch * * \returns false. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern SDL_DECLSPEC bool SDLCALL SDL_OutOfMemory(void); @@ -142,6 +148,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_OutOfMemory(void); * or an empty string if there hasn't been an error message set since * the last call to SDL_ClearError(). * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_ClearError @@ -156,6 +164,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetError(void); * * \since This function is available since SDL 3.0.0. * + * \threadsafety It is safe to call this function from any thread. + * * \sa SDL_GetError * \sa SDL_SetError */ diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h index d67035a7dd..1b64d8cb3d 100644 --- a/include/SDL3/SDL_stdinc.h +++ b/include/SDL3/SDL_stdinc.h @@ -1261,6 +1261,8 @@ typedef int (SDLCALL *SDL_CompareCallback)(const void *a, const void *b); * \param size the size of the elements in the array. * \param compare a function used to compare elements in the array. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_bsearch @@ -1309,6 +1311,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_qsort(void *base, size_t nmemb, size_t size * \returns a pointer to the matching element in the array, or NULL if not * found. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_bsearch_r @@ -1377,6 +1381,8 @@ typedef int (SDLCALL *SDL_CompareCallback_r)(void *userdata, const void *a, cons * \param compare a function used to compare elements in the array. * \param userdata a pointer to pass to the compare function. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_bsearch_r @@ -1433,6 +1439,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_qsort_r(void *base, size_t nmemb, size_t si * \returns a pointer to the matching element in the array, or NULL if not * found. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_bsearch diff --git a/include/SDL3/SDL_timer.h b/include/SDL3/SDL_timer.h index 5b6508aa86..0f1d943f79 100644 --- a/include/SDL3/SDL_timer.h +++ b/include/SDL3/SDL_timer.h @@ -56,6 +56,8 @@ extern "C" { * \returns an unsigned 64-bit value representing the number of milliseconds * since the SDL library initialized. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicks(void); @@ -66,6 +68,8 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicks(void); * \returns an unsigned 64-bit value representing the number of nanoseconds * since the SDL library initialized. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicksNS(void); @@ -81,6 +85,8 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicksNS(void); * * \returns the current counter value. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetPerformanceFrequency @@ -92,6 +98,8 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceCounter(void); * * \returns a platform-specific count per second. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. * * \sa SDL_GetPerformanceCounter @@ -107,6 +115,8 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void); * * \param ms the number of milliseconds to delay. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); @@ -120,6 +130,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); * * \param ns the number of nanoseconds to delay. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.0.0. */ extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns); @@ -133,6 +145,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns); * * \param ns the number of nanoseconds to delay. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.1.4. */ extern SDL_DECLSPEC void SDLCALL SDL_DelayPrecise(Uint64 ns); @@ -275,6 +289,8 @@ extern SDL_DECLSPEC SDL_TimerID SDLCALL SDL_AddTimerNS(Uint64 interval, SDL_NSTi * \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.0.0. * * \sa SDL_AddTimer