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.
2022-12-02 08:29:46 -08:00 · 2022-12-02 08:29:46 -08:00 · 1f4cc733a1
parent e2432bbd3b
commit 1f4cc733a1
6 changed files with 17 additions and 109 deletions
--- 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()
--- 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.
 *
--- 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 */


--- 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: */
--- 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
--- 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),)