From 4cc96e3506b6fa720ac397da49b9217be3daa886 Mon Sep 17 00:00:00 2001 From: "Ryan C. Gordon" Date: Wed, 18 Feb 2026 19:49:59 -0500 Subject: [PATCH] include: Added `\threadsafety` notes to about 60 more functions. Reference Issue #7140. (cherry picked from commit 28e42699159ece63b2b8fc8673fc0296488740a9) --- include/SDL3/SDL_asyncio.h | 4 ++++ include/SDL3/SDL_init.h | 10 +++++++++ include/SDL3/SDL_main.h | 10 +++++++++ include/SDL3/SDL_mutex.h | 42 +++++++++++++++++++++++++++++++++++ include/SDL3/SDL_platform.h | 2 ++ include/SDL3/SDL_properties.h | 2 ++ include/SDL3/SDL_rect.h | 18 +++++++++++++++ include/SDL3/SDL_system.h | 10 +++++++++ include/SDL3/SDL_thread.h | 23 +++++++++++++++++++ include/SDL3/SDL_time.h | 18 +++++++++++++++ include/SDL3/SDL_version.h | 14 ++++++++++++ src/time/SDL_time.c | 1 - 12 files changed, 153 insertions(+), 1 deletion(-) diff --git a/include/SDL3/SDL_asyncio.h b/include/SDL3/SDL_asyncio.h index 0d390f829d..3c894d6964 100644 --- a/include/SDL3/SDL_asyncio.h +++ b/include/SDL3/SDL_asyncio.h @@ -213,6 +213,8 @@ typedef struct SDL_AsyncIOQueue SDL_AsyncIOQueue; * \returns a pointer to the SDL_AsyncIO structure that is created or NULL 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. * * \sa SDL_CloseAsyncIO @@ -531,6 +533,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SignalAsyncIOQueue(SDL_AsyncIOQueue *queue) * \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. * * \sa SDL_LoadFile_IO diff --git a/include/SDL3/SDL_init.h b/include/SDL3/SDL_init.h index b296712ee5..d75ccc31d7 100644 --- a/include/SDL3/SDL_init.h +++ b/include/SDL3/SDL_init.h @@ -224,6 +224,8 @@ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate, SDL_AppResult result); * \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_SetAppMetadata @@ -244,6 +246,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_Init(SDL_InitFlags flags); * \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_Init @@ -260,6 +264,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags); * * \param flags any of the flags used by SDL_Init(); see SDL_Init for details. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_InitSubSystem @@ -274,6 +280,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_QuitSubSystem(SDL_InitFlags flags); * \returns a mask of all initialized subsystems if `flags` is 0, otherwise it * returns the initialization status of the specified subsystems. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_Init @@ -292,6 +300,8 @@ extern SDL_DECLSPEC SDL_InitFlags SDLCALL SDL_WasInit(SDL_InitFlags flags); * application is shutdown, but it is not wise to do this from a library or * other dynamically loaded code. * + * \threadsafety This function should only be called on the main thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_Init diff --git a/include/SDL3/SDL_main.h b/include/SDL3/SDL_main.h index cd9acecba7..ee4d9ca717 100644 --- a/include/SDL3/SDL_main.h +++ b/include/SDL3/SDL_main.h @@ -333,6 +333,8 @@ extern "C" { * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to * terminate with success, SDL_APP_CONTINUE to continue. * + * \threadsafety This function is called once by SDL, at startup, on a single thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_AppIterate @@ -537,6 +539,8 @@ extern SDLMAIN_DECLSPEC int SDLCALL SDL_main(int argc, char *argv[]); * will not be changed it is necessary to define SDL_MAIN_HANDLED before * including SDL.h. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_Init @@ -629,6 +633,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_EnterAppMainCallbacks(int argc, char *argv[] * \returns true on success or false 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 bool SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst); @@ -646,6 +652,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_RegisterApp(const char *name, Uint32 style, * deregistered when the registration counter in SDL_RegisterApp decrements to * zero through calls to this function. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_UnregisterApp(void); @@ -658,6 +666,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnregisterApp(void); * This function is only needed for Xbox GDK support; all other platforms will * do nothing and set an "unsupported" error message. * + * \threadsafety This function is not thread safe. + * * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void); diff --git a/include/SDL3/SDL_mutex.h b/include/SDL3/SDL_mutex.h index a112b5b9b1..e477e2d30d 100644 --- a/include/SDL3/SDL_mutex.h +++ b/include/SDL3/SDL_mutex.h @@ -308,6 +308,8 @@ typedef struct SDL_Mutex SDL_Mutex; * \returns the initialized and unlocked mutex or NULL 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. * * \sa SDL_DestroyMutex @@ -334,6 +336,8 @@ extern SDL_DECLSPEC SDL_Mutex * SDLCALL SDL_CreateMutex(void); * * \param mutex the mutex to lock. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_TryLockMutex @@ -355,6 +359,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockMutex(SDL_Mutex *mutex) SDL_ACQUIRE(mut * \param mutex the mutex to try to lock. * \returns true on success, false if the mutex would block. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_LockMutex @@ -374,6 +380,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_TryLockMutex(SDL_Mutex *mutex) SDL_TRY_ACQU * * \param mutex the mutex to unlock. * + * \threadsafety This call must be paired with a previous locking call on the same thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_LockMutex @@ -392,6 +400,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockMutex(SDL_Mutex *mutex) SDL_RELEASE(m * * \param mutex the mutex to destroy. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateMutex @@ -457,6 +467,8 @@ typedef struct SDL_RWLock SDL_RWLock; * \returns the initialized and unlocked read/write lock or NULL 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. * * \sa SDL_DestroyRWLock @@ -497,6 +509,8 @@ extern SDL_DECLSPEC SDL_RWLock * SDLCALL SDL_CreateRWLock(void); * * \param rwlock the read/write lock to lock. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForWriting @@ -528,6 +542,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForReading(SDL_RWLock *rwlock) SD * * \param rwlock the read/write lock to lock. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading @@ -553,6 +569,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_LockRWLockForWriting(SDL_RWLock *rwlock) SD * \param rwlock the rwlock to try to lock. * \returns true on success, false if the lock would block. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading @@ -583,6 +601,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_TryLockRWLockForReading(SDL_RWLock *rwlock) * \param rwlock the rwlock to try to lock. * \returns true on success, false if the lock would block. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForWriting @@ -607,6 +627,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_TryLockRWLockForWriting(SDL_RWLock *rwlock) * * \param rwlock the rwlock to unlock. * + * \threadsafety This call must be paired with a previous locking call on the same thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_LockRWLockForReading @@ -627,6 +649,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockRWLock(SDL_RWLock *rwlock) SDL_RELEAS * * \param rwlock the rwlock to destroy. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateRWLock @@ -670,6 +694,8 @@ typedef struct SDL_Semaphore SDL_Semaphore; * \returns a new semaphore or NULL 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. * * \sa SDL_DestroySemaphore @@ -689,6 +715,8 @@ extern SDL_DECLSPEC SDL_Semaphore * SDLCALL SDL_CreateSemaphore(Uint32 initial_v * * \param sem the semaphore to destroy. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSemaphore @@ -707,6 +735,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_Semaphore *sem); * * \param sem the semaphore wait on. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore @@ -726,6 +756,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitSemaphore(SDL_Semaphore *sem); * \param sem the semaphore to wait on. * \returns true if the wait succeeds, false if the wait would block. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore @@ -746,6 +778,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_TryWaitSemaphore(SDL_Semaphore *sem); * indefinitely. * \returns true if the wait succeeds or false if the wait times out. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_SignalSemaphore @@ -759,6 +793,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_WaitSemaphoreTimeout(SDL_Semaphore *sem, Si * * \param sem the semaphore to increment. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_TryWaitSemaphore @@ -773,6 +809,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_SignalSemaphore(SDL_Semaphore *sem); * \param sem the semaphore to query. * \returns the current value of the semaphore. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC Uint32 SDLCALL SDL_GetSemaphoreValue(SDL_Semaphore *sem); @@ -806,6 +844,8 @@ typedef struct SDL_Condition SDL_Condition; * \returns a new condition variable or NULL 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. * * \sa SDL_BroadcastCondition @@ -821,6 +861,8 @@ extern SDL_DECLSPEC SDL_Condition * SDLCALL SDL_CreateCondition(void); * * \param cond the condition variable to destroy. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateCondition diff --git a/include/SDL3/SDL_platform.h b/include/SDL3/SDL_platform.h index e2461610e8..9ad380bab0 100644 --- a/include/SDL3/SDL_platform.h +++ b/include/SDL3/SDL_platform.h @@ -51,6 +51,8 @@ extern "C" { * \returns the name of the platform. If the correct platform name is not * available, returns a string beginning with the text "Unknown". * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetPlatform(void); diff --git a/include/SDL3/SDL_properties.h b/include/SDL3/SDL_properties.h index 4d57c80c77..abd7b2aa50 100644 --- a/include/SDL3/SDL_properties.h +++ b/include/SDL3/SDL_properties.h @@ -111,6 +111,8 @@ typedef enum SDL_PropertyType * \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.2.0. */ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void); diff --git a/include/SDL3/SDL_rect.h b/include/SDL3/SDL_rect.h index 7bdf5b0943..883ca8d6c0 100644 --- a/include/SDL3/SDL_rect.h +++ b/include/SDL3/SDL_rect.h @@ -237,6 +237,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasRectIntersection(const SDL_Rect *A, cons * rectangles `A` and `B`. * \returns true if there is an intersection, false otherwise. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_HasRectIntersection @@ -253,6 +255,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRectIntersection(const SDL_Rect *A, cons * \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_GetRectUnion(const SDL_Rect *A, const SDL_Rect *B, SDL_Rect *result); @@ -272,6 +276,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRectUnion(const SDL_Rect *A, const SDL_R * \returns true if any points were enclosed or false if all the points were * outside of the clipping rectangle. * + * \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_GetRectEnclosingPoints(const SDL_Point *points, int count, const SDL_Rect *clip, SDL_Rect *result); @@ -292,6 +298,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRectEnclosingPoints(const SDL_Point *poi * \param Y2 a pointer to the ending Y-coordinate of the line. * \returns true if there is an intersection, false otherwise. * + * \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_GetRectAndLineIntersection(const SDL_Rect *rect, int *X1, int *Y1, int *X2, int *Y2); @@ -423,6 +431,8 @@ SDL_FORCE_INLINE bool SDL_RectsEqualFloat(const SDL_FRect *a, const SDL_FRect *b * \param B an SDL_FRect structure representing the second rectangle. * \returns true if there is an intersection, false otherwise. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRectIntersection @@ -440,6 +450,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_HasRectIntersectionFloat(const SDL_FRect *A * rectangles `A` and `B`. * \returns true if there is an intersection, false otherwise. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_HasRectIntersectionFloat @@ -456,6 +468,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRectIntersectionFloat(const SDL_FRect *A * \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_GetRectUnionFloat(const SDL_FRect *A, const SDL_FRect *B, SDL_FRect *result); @@ -476,6 +490,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRectUnionFloat(const SDL_FRect *A, const * \returns true if any points were enclosed or false if all the points were * outside of the clipping rectangle. * + * \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_GetRectEnclosingPointsFloat(const SDL_FPoint *points, int count, const SDL_FRect *clip, SDL_FRect *result); @@ -497,6 +513,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetRectEnclosingPointsFloat(const SDL_FPoin * \param Y2 a pointer to the ending Y-coordinate of the line. * \returns true if there is an intersection, false otherwise. * + * \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_GetRectAndLineIntersectionFloat(const SDL_FRect *rect, float *X1, float *Y1, float *X2, float *Y2); diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h index 62aee34c33..2d2be82a32 100644 --- a/include/SDL3/SDL_system.h +++ b/include/SDL3/SDL_system.h @@ -370,6 +370,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidActivity(void); * * \returns the Android API level. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void); @@ -379,6 +381,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAndroidSDKVersion(void); * * \returns true if this is a Chromebook, false otherwise. * + * \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_IsChromebook(void); @@ -388,6 +392,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_IsChromebook(void); * * \returns true if this is a DeX docking station, false otherwise. * + * \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_IsDeXMode(void); @@ -605,6 +611,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SendAndroidMessage(Uint32 command, int para * * \returns true if the device is a tablet, false otherwise. * + * \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_IsTablet(void); @@ -616,6 +624,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_IsTablet(void); * * \returns true if the device is a TV, false otherwise. * + * \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_IsTV(void); diff --git a/include/SDL3/SDL_thread.h b/include/SDL3/SDL_thread.h index 77d11ca169..f74317cc69 100644 --- a/include/SDL3/SDL_thread.h +++ b/include/SDL3/SDL_thread.h @@ -208,6 +208,8 @@ typedef int (SDLCALL *SDL_ThreadFunction) (void *data); * new thread could not be created; 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. * * \sa SDL_CreateThreadWithProperties @@ -274,6 +276,8 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThread(SDL_ThreadFunction fn, * new thread could not be created; 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. * * \sa SDL_CreateThread @@ -329,6 +333,8 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithProperties(SDL_Prop * new thread could not be created; 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 SDL_Thread * SDLCALL SDL_CreateThreadRuntime(SDL_ThreadFunction fn, const char *name, void *data, SDL_FunctionPointer pfnBeginThread, SDL_FunctionPointer pfnEndThread); @@ -343,6 +349,8 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadRuntime(SDL_ThreadFunct * new thread could not be created; 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 SDL_Thread * SDLCALL SDL_CreateThreadWithPropertiesRuntime(SDL_PropertiesID props, SDL_FunctionPointer pfnBeginThread, SDL_FunctionPointer pfnEndThread); @@ -363,6 +371,8 @@ extern SDL_DECLSPEC SDL_Thread * SDLCALL SDL_CreateThreadWithPropertiesRuntime(S * \returns a pointer to a UTF-8 string that names the specified thread, or * NULL if it doesn't have a name. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetThreadName(SDL_Thread *thread); @@ -379,6 +389,8 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetThreadName(SDL_Thread *thread); * * \returns the ID of the current thread. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_GetThreadID @@ -396,6 +408,8 @@ extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetCurrentThreadID(void); * \returns the ID of the specified thread, or the ID of the current thread if * `thread` is NULL. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCurrentThreadID @@ -413,6 +427,8 @@ extern SDL_DECLSPEC SDL_ThreadID SDLCALL SDL_GetThreadID(SDL_Thread *thread); * \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_SetCurrentThreadPriority(SDL_ThreadPriority priority); @@ -445,6 +461,9 @@ extern SDL_DECLSPEC bool SDLCALL SDL_SetCurrentThreadPriority(SDL_ThreadPriority * function by its 'return', or -1 if the thread has been * detached or isn't valid, may be NULL. * + * \threadsafety It is safe to call this function from any thread, but only + * a single thread can wait any specific thread to finish. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateThread @@ -459,6 +478,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread *thread, int *status) * \returns the current state of a thread, or SDL_THREAD_UNKNOWN if the thread * isn't valid. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_ThreadState @@ -491,6 +512,8 @@ extern SDL_DECLSPEC SDL_ThreadState SDLCALL SDL_GetThreadState(SDL_Thread *threa * * It is safe to pass NULL to this function; it is a no-op. * + * \threadsafety It is safe to call this function from any thread. + * * \param thread the SDL_Thread pointer that was returned from the * SDL_CreateThread() call that started this thread. * diff --git a/include/SDL3/SDL_time.h b/include/SDL3/SDL_time.h index 57bc4c19b9..2ae6022f97 100644 --- a/include/SDL3/SDL_time.h +++ b/include/SDL3/SDL_time.h @@ -106,6 +106,8 @@ typedef enum SDL_TimeFormat * \returns true on success or false 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 bool SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat *dateFormat, SDL_TimeFormat *timeFormat); @@ -118,6 +120,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat * \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_GetCurrentTime(SDL_Time *ticks); @@ -134,6 +138,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks); * \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_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, bool localTime); @@ -149,6 +155,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime * \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_DateTimeToTime(const SDL_DateTime *dt, SDL_Time *ticks); @@ -165,6 +173,8 @@ extern SDL_DECLSPEC bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_ * \param dwHighDateTime a pointer filled in with the high portion of the * Windows FILETIME value. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLowDateTime, Uint32 *dwHighDateTime); @@ -180,6 +190,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLow * \param dwHighDateTime the high portion of the Windows FILETIME value. * \returns the converted SDL time. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. */ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, Uint32 dwHighDateTime); @@ -192,6 +204,8 @@ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, U * \returns the number of days in the requested month 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.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month); @@ -205,6 +219,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month); * \returns the day of year [0-365] if the date is valid 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.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day); @@ -218,6 +234,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day); * \returns a value between 0 and 6 (0 being Sunday) if the date is valid 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.2.0. */ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfWeek(int year, int month, int day); diff --git a/include/SDL3/SDL_version.h b/include/SDL3/SDL_version.h index 7bfb48e61e..4b234d2515 100644 --- a/include/SDL3/SDL_version.h +++ b/include/SDL3/SDL_version.h @@ -85,6 +85,8 @@ extern "C" { * * \param version the version number. * + * \threadsafety It is safe to call this macro from any thread. + * * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MAJOR(version) ((version) / 1000000) @@ -96,6 +98,8 @@ extern "C" { * * \param version the version number. * + * \threadsafety It is safe to call this macro from any thread. + * * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MINOR(version) (((version) / 1000) % 1000) @@ -107,6 +111,8 @@ extern "C" { * * \param version the version number. * + * \threadsafety It is safe to call this macro from any thread. + * * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSIONNUM_MICRO(version) ((version) % 1000) @@ -114,6 +120,8 @@ extern "C" { /** * This is the version number macro for the current SDL version. * + * \threadsafety It is safe to call this macro from any thread. + * * \since This macro is available since SDL 3.2.0. * * \sa SDL_GetVersion @@ -124,6 +132,8 @@ extern "C" { /** * This macro will evaluate to true if compiled with SDL at least X.Y.Z. * + * \threadsafety It is safe to call this macro from any thread. + * * \since This macro is available since SDL 3.2.0. */ #define SDL_VERSION_ATLEAST(X, Y, Z) \ @@ -141,6 +151,8 @@ extern "C" { * * \returns the version of the linked library. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRevision @@ -168,6 +180,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetVersion(void); * \returns an arbitrary string, uniquely identifying the exact revision of * the SDL library in use. * + * \threadsafety It is safe to call this function from any thread. + * * \since This function is available since SDL 3.2.0. * * \sa SDL_GetVersion diff --git a/src/time/SDL_time.c b/src/time/SDL_time.c index 55d11e96d8..ba0a2cf7fa 100644 --- a/src/time/SDL_time.c +++ b/src/time/SDL_time.c @@ -32,7 +32,6 @@ */ Sint64 SDL_CivilToDays(int year, int month, int day, int *day_of_week, int *day_of_year) { - year -= month <= 2; const int era = (year >= 0 ? year : year - 399) / 400; const unsigned yoe = (unsigned)(year - era * 400); // [0, 399]