Improved SDL_PollEvent usage (#4794)

* Avoid unnecessary SDL_PumpEvents calls in SDL_WaitEventTimeout

* Add a sentinel event to avoid infinite poll loops

* Move SDL_POLLSENTINEL to new internal event category

* Tweak documentation to indicate SDL_PumpEvents isn't always called

* Avoid shadowing event variable

* Ignore poll sentinel if more (user) events have been added after

Co-authored-by: Sam Lantinga <slouken@libsdl.org>

include/SDL_events.h

@@ -160,6 +160,9 @@ typedef enum
     SDL_RENDER_TARGETS_RESET = 0x2000, /**< The render targets have been reset and their contents need to be updated */
     SDL_RENDER_DEVICE_RESET, /**< The device has been reset and all textures need to be recreated */
 
+    /* Internal events */
+    SDL_POLLSENTINEL = 0x7F00, /**< Signals the end of an event poll cycle */
+
     /** Events ::SDL_USEREVENT through ::SDL_LASTEVENT are for your use,
      *  and should be allocated with SDL_RegisterEvents()
      */
@@ -798,7 +801,7 @@ extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
  * If `event` is NULL, it simply returns 1 if there is an event in the queue,
  * but will not remove it from the queue.
  *
- * As this function implicitly calls SDL_PumpEvents(), you can only call this
+ * As this function may implicitly call SDL_PumpEvents(), you can only call this
  * function in the thread that set the video mode.
  *
  * SDL_PollEvent() is the favored way of receiving system events since it can
@@ -838,7 +841,7 @@ extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * 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 implicitly calls SDL_PumpEvents(), you can only call this
+ * As this function may implicitly call SDL_PumpEvents(), you can only call this
  * function in the thread that initialized the video subsystem.
  *
  * \param event the SDL_Event structure to be filled in with the next event
@@ -859,7 +862,7 @@ extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * 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 implicitly calls SDL_PumpEvents(), you can only call this
+ * As this function may implicitly call SDL_PumpEvents(), you can only call this
  * function in the thread that initialized the video subsystem.
  *
  * \param event the SDL_Event structure to be filled in with the next event

include/SDL_hints.h

@@ -958,6 +958,22 @@ extern "C" {
  */
 #define SDL_HINT_ORIENTATIONS "SDL_IOS_ORIENTATIONS"
 
+/**
+ *  \brief  A variable controlling the use of a sentinel event when polling the event queue
+ *
+ *  This variable can be set to the following values:
+ *    "0"       - Disable poll sentinels
+ *    "1"       - Enable poll sentinels
+ *
+ *  When polling for events, SDL_PumpEvents is used to gather new events from devices.
+ *  If a device keeps producing new events between calls to SDL_PumpEvents, a poll loop will
+ *  become stuck until the new events stop.
+ *  This is most noticable when moving a high frequency mouse.
+ *
+ *  By default, poll sentinels are enabled.
+ */
+#define SDL_HINT_POLL_SENTINEL "SDL_POLL_SENTINEL"
+
 /**
  *  \brief Override for SDL_GetPreferredLocales()
  *

src/events/SDL_events.c

@@ -26,6 +26,7 @@
 #include "SDL_events.h"
 #include "SDL_thread.h"
 #include "SDL_events_c.h"
+#include "../SDL_hints_c.h"
 #include "../timer/SDL_timer_c.h"
 #if !SDL_JOYSTICK_DISABLED
 #include "../joystick/SDL_joystick_c.h"
@@ -139,6 +140,11 @@ SDL_AutoUpdateSensorsChanged(void *userdata, const char *name, const char *oldVa
 
 #endif /* !SDL_SENSOR_DISABLED */
 
+static void SDLCALL
+SDL_PollSentinelChanged(void *userdata, const char *name, const char *oldValue, const char *hint)
+{
+    SDL_EventState(SDL_POLLSENTINEL, SDL_GetStringBoolean(hint, SDL_TRUE) ? SDL_ENABLE : SDL_DISABLE);
+}
 
 /* 0 (default) means no logging, 1 means logging, 2 means logging with mouse and finger motion */
 static int SDL_DoEventLogging = 0;
@@ -886,6 +892,21 @@ SDL_WaitEventTimeout(SDL_Event * event, int timeout)
 	Uint32 start = 0;
     Uint32 expiration = 0;
 
+    /* First check for existing events */
+    switch (SDL_PeepEvents(event, 1, SDL_GETEVENT, SDL_FIRSTEVENT, SDL_LASTEVENT)) {
+    case -1:
+        return 0;
+    case 0:
+        break;
+    default:
+        /* Check whether we have reached the end of the poll cycle, and no more events are left */
+        if (timeout == 0 && event && event->type == SDL_POLLSENTINEL) {
+            return SDL_PeepEvents(event, 1, SDL_GETEVENT, SDL_FIRSTEVENT, SDL_LASTEVENT) == 1;
+        }
+        /* Has existing events */
+        return 1;
+    }
+
     if (timeout > 0) {
 		start = SDL_GetTicks();
         expiration = start + timeout;
@@ -922,6 +943,13 @@ SDL_WaitEventTimeout(SDL_Event * event, int timeout)
             SDL_Delay(1);
             break;
         default:
+            if (timeout == 0 && SDL_GetEventState(SDL_POLLSENTINEL) == SDL_ENABLE) {
+                /* We are at the start of a poll cycle with at least one new event.
+                   Add a sentinel event to mark the end of the cycle. */
+                SDL_Event sentinel;
+                sentinel.type = SDL_POLLSENTINEL;
+                SDL_PushEvent(&sentinel);
+            }
             /* Has events */
             return 1;
         }
@@ -1216,6 +1244,7 @@ SDL_EventsInit(void)
     SDL_AddHintCallback(SDL_HINT_AUTO_UPDATE_SENSORS, SDL_AutoUpdateSensorsChanged, NULL);
 #endif
     SDL_AddHintCallback(SDL_HINT_EVENT_LOGGING, SDL_EventLoggingChanged, NULL);
+    SDL_AddHintCallback(SDL_HINT_POLL_SENTINEL, SDL_PollSentinelChanged, NULL);
     if (SDL_StartEventLoop() < 0) {
         SDL_DelHintCallback(SDL_HINT_EVENT_LOGGING, SDL_EventLoggingChanged, NULL);
         return -1;
@@ -1231,6 +1260,7 @@ SDL_EventsQuit(void)
 {
     SDL_QuitQuit();
     SDL_StopEventLoop();
+    SDL_DelHintCallback(SDL_HINT_POLL_SENTINEL, SDL_PollSentinelChanged, NULL);
     SDL_DelHintCallback(SDL_HINT_EVENT_LOGGING, SDL_EventLoggingChanged, NULL);
 #if !SDL_JOYSTICK_DISABLED
     SDL_DelHintCallback(SDL_HINT_AUTO_UPDATE_JOYSTICKS, SDL_AutoUpdateJoysticksChanged, NULL);