gitea/SDL3_fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add \threadsafety to some low-hanging fruit across a few headers.

Browse Source 
Reference Issue #7140.
This commit is contained in:
Ryan C. Gordon
2024-10-22 13:47:28 -04:00
parent eed11ad6d6
commit 2318961b6f
4 changed files with 70 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
include/SDL3/SDL_cpuinfo.h
View File

@@ -60,6 +60,8 @@ extern "C" {
* technologies such as hyperthreading, the number of logical cores * technologies such as hyperthreading, the number of logical cores
* may be more than the number of physical 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. * \since This function is available since SDL 3.0.0.
*/ */
extern SDL_DECLSPEC int SDLCALL SDL_GetNumLogicalCPUCores(void); 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. * \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. * \since This function is available since SDL 3.0.0.
*/ */
extern SDL_DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void); 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. * \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. * \since This function is available since SDL 3.0.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_HasAltiVec(void); 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. * \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. * \since This function is available since SDL 3.0.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_HasMMX(void); 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. * \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. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_HasSSE2 * \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. * \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. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_HasSSE * \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. * \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. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_HasSSE * \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. * \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. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_HasSSE * \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. * \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. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_HasSSE * \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. * \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. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_HasAVX2 * \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. * \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. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_HasAVX * \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. * \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. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_HasAVX * \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. * \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. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_HasNEON * \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. * \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. * \since This function is available since SDL 3.0.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_HasNEON(void); 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. * \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. * \since This function is available since SDL 3.0.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_HasLSX(void); 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. * \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. * \since This function is available since SDL 3.0.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_HasLASX(void); 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. * \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. * \since This function is available since SDL 3.0.0.
*/ */
extern SDL_DECLSPEC int SDLCALL SDL_GetSystemRAM(void); 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 * \returns the alignment in bytes needed for available, known SIMD
* instructions. * instructions.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_aligned_alloc * \sa SDL_aligned_alloc

10
include/SDL3/SDL_error.h
View File

@@ -78,6 +78,8 @@ extern "C" {
* any. * any.
* \returns false. * \returns false.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_ClearError * \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. * \param ap a variable argument list.
* \returns false. * \returns false.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.1.4. * \since This function is available since SDL 3.1.4.
* *
* \sa SDL_ClearError * \sa SDL_ClearError
@@ -110,6 +114,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetErrorV(SDL_PRINTF_FORMAT_STRING const ch
* *
* \returns false. * \returns false.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
*/ */
extern SDL_DECLSPEC bool SDLCALL SDL_OutOfMemory(void); 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 * or an empty string if there hasn't been an error message set since
* the last call to SDL_ClearError(). * 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. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_ClearError * \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. * \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_GetError
* \sa SDL_SetError * \sa SDL_SetError
*/ */

8
include/SDL3/SDL_stdinc.h
View File

@@ -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 size the size of the elements in the array.
* \param compare a function used to compare 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. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_bsearch * \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 * \returns a pointer to the matching element in the array, or NULL if not
* found. * found.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_bsearch_r * \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 compare a function used to compare elements in the array.
* \param userdata a pointer to pass to the compare function. * \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. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_bsearch_r * \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 * \returns a pointer to the matching element in the array, or NULL if not
* found. * found.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_bsearch * \sa SDL_bsearch

16
include/SDL3/SDL_timer.h
View File

@@ -56,6 +56,8 @@ extern "C" {
* \returns an unsigned 64-bit value representing the number of milliseconds * \returns an unsigned 64-bit value representing the number of milliseconds
* since the SDL library initialized. * 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. * \since This function is available since SDL 3.0.0.
*/ */
extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicks(void); 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 * \returns an unsigned 64-bit value representing the number of nanoseconds
* since the SDL library initialized. * 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. * \since This function is available since SDL 3.0.0.
*/ */
extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetTicksNS(void); 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. * \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. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_GetPerformanceFrequency * \sa SDL_GetPerformanceFrequency
@@ -92,6 +98,8 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceCounter(void);
* *
* \returns a platform-specific count per second. * \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. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_GetPerformanceCounter * \sa SDL_GetPerformanceCounter
@@ -107,6 +115,8 @@ extern SDL_DECLSPEC Uint64 SDLCALL SDL_GetPerformanceFrequency(void);
* *
* \param ms the number of milliseconds to delay. * \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. * \since This function is available since SDL 3.0.0.
*/ */
extern SDL_DECLSPEC void SDLCALL SDL_Delay(Uint32 ms); 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. * \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. * \since This function is available since SDL 3.0.0.
*/ */
extern SDL_DECLSPEC void SDLCALL SDL_DelayNS(Uint64 ns); 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. * \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. * \since This function is available since SDL 3.1.4.
*/ */
extern SDL_DECLSPEC void SDLCALL SDL_DelayPrecise(Uint64 ns); 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 * \returns true on success or false on failure; call SDL_GetError() for more
* information. * information.
* *
* \threadsafety It is safe to call this function from any thread.
*
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
* \sa SDL_AddTimer * \sa SDL_AddTimer