From 1f4cc733a148782ae339c27cfd568ee609d151ed Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Fri, 2 Dec 2022 08:29:46 -0800
Subject: [PATCH] Removed the nanosecond versions of event and thread primitive
waits from the public API
It's not clear applications need this level of precision yet, so let's leave these private for now.
---
WhatsNew.txt | 3 --
include/SDL3/SDL_events.h | 33 ---------------
include/SDL3/SDL_mutex.h | 67 -------------------------------
src/SDL_internal.h | 17 ++++++++
src/dynapi/SDL_dynapi_overrides.h | 3 --
src/dynapi/SDL_dynapi_procs.h | 3 --
6 files changed, 17 insertions(+), 109 deletions(-)
diff --git a/WhatsNew.txt b/WhatsNew.txt
index c9b3bfb87456..de7b540a281a 100644
--- a/WhatsNew.txt
+++ b/WhatsNew.txt
@@ -35,7 +35,4 @@ General:
* SDL_GetTicks() now returns a 64-bit value and the tick values should be directly compared instead of using the SDL_TICKS_PASSED macro
* Added SDL_GetTicksNS() to return the number of nanoseconds since the SDL library initialized
* Added SDL_DelayNS() to specify a delay in nanoseconds, to the highest precision the system will support
-* Added SDL_WaitEventTimeoutNS() to wait for events with the highest possible precision
-* Added SDL_SemWaitTimeoutNS() to wait for a semaphore with the highest possible precision
-* Added SDL_CondWaitTimeoutNS() to wait for a condition variable the highest possible precision
* The timestamp member of the SDL_Event structure is now in nanoseconds, filled in with SDL_GetTicksNS()
diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h
index 00c111006ea2..2d4d712b9fff 100644
--- a/include/SDL3/SDL_events.h
+++ b/include/SDL3/SDL_events.h
@@ -879,7 +879,6 @@ extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
* \sa SDL_SetEventFilter
* \sa SDL_WaitEvent
* \sa SDL_WaitEventTimeout
- * \sa SDL_WaitEventTimeoutNS
*/
extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
@@ -902,7 +901,6 @@ extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
* \sa SDL_PollEvent
* \sa SDL_PumpEvents
* \sa SDL_WaitEventTimeout
- * \sa SDL_WaitEventTimeoutNS
*/
extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event *event);
@@ -932,40 +930,9 @@ extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event *event);
* \sa SDL_PollEvent
* \sa SDL_PumpEvents
* \sa SDL_WaitEvent
- * \sa SDL_WaitEventTimeoutNS
*/
extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event *event, Sint32 timeoutMS);
-/**
- * Wait until the specified timeout (in nanoseconds) for the next available
- * event.
- *
- * If `event` is not NULL, the next event is removed from the queue and stored
- * in the SDL_Event structure pointed to by `event`.
- *
- * As this function may implicitly call SDL_PumpEvents(), you can only call
- * this function in the thread that initialized the video subsystem.
- *
- * The timeout is not guaranteed, the actual wait time could be longer
- * due to system scheduling.
- *
- * \param event the SDL_Event structure to be filled in with the next event
- * from the queue, or NULL
- * \param timeoutNS the maximum number of nanoseconds to wait for the next
- * available event
- * \returns 1 on success or 0 if there was an error while waiting for events;
- * call SDL_GetError() for more information. This also returns 0 if
- * the timeout elapsed without an event arriving.
- *
- * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_PollEvent
- * \sa SDL_PumpEvents
- * \sa SDL_WaitEvent
- * \sa SDL_WaitEventTimeout
- */
-extern DECLSPEC int SDLCALL SDL_WaitEventTimeoutNS(SDL_Event *event, Sint64 timeoutNS);
-
/**
* Add an event to the event queue.
*
diff --git a/include/SDL3/SDL_mutex.h b/include/SDL3/SDL_mutex.h
index 7495ab4c13c8..de35462485bc 100644
--- a/include/SDL3/SDL_mutex.h
+++ b/include/SDL3/SDL_mutex.h
@@ -194,7 +194,6 @@ typedef struct SDL_semaphore SDL_sem;
* \sa SDL_SemValue
* \sa SDL_SemWait
* \sa SDL_SemWaitTimeout
- * \sa SDL_SemWaitTimeoutNS
*/
extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
@@ -214,7 +213,6 @@ extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
* \sa SDL_SemValue
* \sa SDL_SemWait
* \sa SDL_SemWaitTimeout
- * \sa SDL_SemWaitTimeoutNS
*/
extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem *sem);
@@ -242,7 +240,6 @@ extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem *sem);
* \sa SDL_SemValue
* \sa SDL_SemWait
* \sa SDL_SemWaitTimeout
- * \sa SDL_SemWaitTimeoutNS
*/
extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem *sem);
@@ -267,7 +264,6 @@ extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem *sem);
* \sa SDL_SemValue
* \sa SDL_SemWait
* \sa SDL_SemWaitTimeout
- * \sa SDL_SemWaitTimeoutNS
*/
extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem *sem);
@@ -293,36 +289,9 @@ extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem *sem);
* \sa SDL_SemTryWait
* \sa SDL_SemValue
* \sa SDL_SemWait
- * \sa SDL_SemWaitTimeoutNS
*/
extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Sint32 timeoutMS);
-/**
- * Wait until a semaphore has a positive value and then decrements it.
- *
- * This function suspends the calling thread until either the semaphore
- * pointed to by `sem` has a positive value, the call is interrupted by a
- * signal or error, or the specified time has elapsed. If the call is
- * successful it will atomically decrement the semaphore value.
- *
- * \param sem the semaphore to wait on
- * \param timeoutNS the length of the timeout, in nanoseconds
- * \returns 0 if the wait succeeds, `SDL_MUTEX_TIMEDOUT` if the wait does not
- * succeed in the allotted time, or a negative error code on failure;
- * call SDL_GetError() for more information.
- *
- * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_CreateSemaphore
- * \sa SDL_DestroySemaphore
- * \sa SDL_SemPost
- * \sa SDL_SemTryWait
- * \sa SDL_SemValue
- * \sa SDL_SemWait
- * \sa SDL_SemWaitTimeout
- */
-extern DECLSPEC int SDLCALL SDL_SemWaitTimeoutNS(SDL_sem *sem, Sint64 timeoutNS);
-
/**
* Atomically increment a semaphore's value and wake waiting threads.
*
@@ -377,7 +346,6 @@ typedef struct SDL_cond SDL_cond;
* \sa SDL_CondSignal
* \sa SDL_CondWait
* \sa SDL_CondWaitTimeout
- * \sa SDL_CondWaitTimeoutNS
* \sa SDL_DestroyCond
*/
extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
@@ -393,7 +361,6 @@ extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(void);
* \sa SDL_CondSignal
* \sa SDL_CondWait
* \sa SDL_CondWaitTimeout
- * \sa SDL_CondWaitTimeoutNS
* \sa SDL_CreateCond
*/
extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond *cond);
@@ -410,7 +377,6 @@ extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond *cond);
* \sa SDL_CondBroadcast
* \sa SDL_CondWait
* \sa SDL_CondWaitTimeout
- * \sa SDL_CondWaitTimeoutNS
* \sa SDL_CreateCond
* \sa SDL_DestroyCond
*/
@@ -428,7 +394,6 @@ extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond *cond);
* \sa SDL_CondSignal
* \sa SDL_CondWait
* \sa SDL_CondWaitTimeout
- * \sa SDL_CondWaitTimeoutNS
* \sa SDL_CreateCond
* \sa SDL_DestroyCond
*/
@@ -457,7 +422,6 @@ extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond *cond);
* \sa SDL_CondBroadcast
* \sa SDL_CondSignal
* \sa SDL_CondWaitTimeout
- * \sa SDL_CondWaitTimeoutNS
* \sa SDL_CreateCond
* \sa SDL_DestroyCond
*/
@@ -487,43 +451,12 @@ extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond *cond, SDL_mutex *mutex);
* \sa SDL_CondBroadcast
* \sa SDL_CondSignal
* \sa SDL_CondWait
- * \sa SDL_CondWaitTimeoutNS
* \sa SDL_CreateCond
* \sa SDL_DestroyCond
*/
extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond *cond,
SDL_mutex *mutex, Sint32 timeoutMS);
-/**
- * Wait until a condition variable is signaled or a certain time has passed.
- *
- * This function unlocks the specified `mutex` and waits for another thread to
- * call SDL_CondSignal() or SDL_CondBroadcast() on the condition variable
- * `cond`, or for the specified time to elapse. Once the condition variable is
- * signaled or the time elapsed, the mutex is re-locked and the function
- * returns.
- *
- * The mutex must be locked before calling this function.
- *
- * \param cond the condition variable to wait on
- * \param mutex the mutex used to coordinate thread access
- * \param timeoutNS the maximum time to wait, in nanoseconds, or `SDL_MUTEX_MAXWAIT` to wait indefinitely
- * \returns 0 if the condition variable is signaled, `SDL_MUTEX_TIMEDOUT` if
- * the condition is not signaled in the allotted time, or a negative
- * error code on failure; call SDL_GetError() for more information.
- *
- * \since This function is available since SDL 3.0.0.
- *
- * \sa SDL_CondBroadcast
- * \sa SDL_CondSignal
- * \sa SDL_CondWait
- * \sa SDL_CondWaitTimeout
- * \sa SDL_CreateCond
- * \sa SDL_DestroyCond
- */
-extern DECLSPEC int SDLCALL SDL_CondWaitTimeoutNS(SDL_cond *cond,
- SDL_mutex *mutex, Sint64 timeoutNS);
-
/* @} *//* Condition variable functions */
diff --git a/src/SDL_internal.h b/src/SDL_internal.h
index cee82f28b24c..11470af8dbe4 100644
--- a/src/SDL_internal.h
+++ b/src/SDL_internal.h
@@ -182,6 +182,23 @@
#include <SDL3/SDL.h>
+/* The internal implementations of these functions have up to nanosecond precision.
+ We can expose these functions as part of the API if we want to later.
+*/
+/* Set up for C function definitions, even when using C++ */
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+extern DECLSPEC int SDLCALL SDL_SemWaitTimeoutNS(SDL_sem *sem, Sint64 timeoutNS);
+extern DECLSPEC int SDLCALL SDL_CondWaitTimeoutNS(SDL_cond *cond, SDL_mutex *mutex, Sint64 timeoutNS);
+extern DECLSPEC int SDLCALL SDL_WaitEventTimeoutNS(SDL_Event *event, Sint64 timeoutNS);
+
+/* Ends C function definitions when using C++ */
+#ifdef __cplusplus
+}
+#endif
+
#endif /* SDL_internal_h_ */
/* vi: set ts=4 sw=4 expandtab: */
diff --git a/src/dynapi/SDL_dynapi_overrides.h b/src/dynapi/SDL_dynapi_overrides.h
index dc085600aaf8..a71417620cef 100644
--- a/src/dynapi/SDL_dynapi_overrides.h
+++ b/src/dynapi/SDL_dynapi_overrides.h
@@ -890,8 +890,5 @@
#define SDL_GDKSuspendComplete SDL_GDKSuspendComplete_REAL
#define SDL_GetWindowWMInfo SDL_GetWindowWMInfo_REAL
#define SDL_memset4 SDL_memset4_REAL
-#define SDL_WaitEventTimeoutNS SDL_WaitEventTimeoutNS_REAL
-#define SDL_SemWaitTimeoutNS SDL_SemWaitTimeoutNS_REAL
-#define SDL_CondWaitTimeoutNS SDL_CondWaitTimeoutNS_REAL
#define SDL_GetTicksNS SDL_GetTicksNS_REAL
#define SDL_DelayNS SDL_DelayNS_REAL
diff --git a/src/dynapi/SDL_dynapi_procs.h b/src/dynapi/SDL_dynapi_procs.h
index 2d4b97f13773..352488ff794e 100644
--- a/src/dynapi/SDL_dynapi_procs.h
+++ b/src/dynapi/SDL_dynapi_procs.h
@@ -966,8 +966,5 @@ SDL_DYNAPI_PROC(void,SDL_GDKSuspendComplete,(void),(),)
#endif
SDL_DYNAPI_PROC(int,SDL_GetWindowWMInfo,(SDL_Window *a, SDL_SysWMinfo *b, Uint32 c),(a,b,c),return)
SDL_DYNAPI_PROC(void*,SDL_memset4,(void *a, Uint32 b, size_t c),(a,b,c),return)
-SDL_DYNAPI_PROC(int,SDL_WaitEventTimeoutNS,(SDL_Event *a, Sint64 b),(a,b),return)
-SDL_DYNAPI_PROC(int,SDL_SemWaitTimeoutNS,(SDL_sem *a, Sint64 b),(a,b),return)
-SDL_DYNAPI_PROC(int,SDL_CondWaitTimeoutNS,(SDL_cond *a, SDL_mutex *b, Sint64 c),(a,b,c),return)
SDL_DYNAPI_PROC(Uint64,SDL_GetTicksNS,(void),(),return)
SDL_DYNAPI_PROC(void,SDL_DelayNS,(Uint64 a),(a),)