lua: make it easier to integrate with foreign event loops

We provide some "official" utility functions for this.

DOCS/man/en/lua.rst

@@ -338,6 +338,26 @@ The ``mp`` module is preloaded, although it can be loaded manually with
     Calls ``mpv_get_wakeup_pipe()`` and returns the read end of the wakeup
     pipe. (See ``client.h`` for details.)
 
+``mp.get_next_timeout()``
+    Return the relative time in seconds when the next timer (``mp.add_timeout``
+    and similar) expires. If there is no timer, return ``nil``.
+
+``mp.dispatch_events([allow_wait])``
+    This can be used to run custom event loops. If you want to have direct
+    control what the Lua script does (instead of being called by the default
+    event loop), you can set the global variable ``mp_event_loop`` to your
+    own function running the event loop. From your event loop, you should call
+    ``mp.dispatch_events()`` to unqueue and dispatch mpv events.
+
+    If the ``allow_wait`` parameter is set to ``true``, the function will block
+    until the next event is received or the next timer expires. Otherwise (and
+    this is the default behavior), it returns as soon as the event loop is
+    emptied. It's strongly recommended to use ``mp.get_next_timeout()`` and
+    ``mp.get_wakeup_pipe()`` if you're interested in properly working
+    notification of new events and working timers.
+
+    This function calls ``mp.suspend()`` and ``mp.resume_all()`` on its own.
+
 ``mp.enable_messages(level)``
     Set the minimum log level of which mpv message output to receive. These
     messages are normally printed to the terminal. By calling this function,

player/lua/defaults.lua

@@ -201,6 +201,15 @@ local function get_next_timer()
     return best
 end
 
+function mp.get_next_timeout()
+    local timer = get_next_timer()
+    if not timer then
+        return
+    end
+    local now = mp.get_time()
+    return timer.next_deadline - now
+end
+
 -- Run timers that have met their deadline.
 -- Return: next absolute time a timer expires as number, or nil if no timers
 local function process_timers()
@@ -331,6 +340,19 @@ package.loaded["mp"] = mp
 package.loaded["mp.msg"] = mp.msg
 
 _G.mp_event_loop = function()
+    mp.dispatch_events(true)
+end
+
+local function call_event_handlers(e)
+    local handlers = event_handlers[e.event]
+    if handlers then
+        for _, handler in ipairs(handlers) do
+            handler(e)
+        end
+    end
+end
+
+function mp.dispatch_events(allow_wait)
     local more_events = true
     mp.suspend()
     while mp.keep_running do
@@ -345,6 +367,9 @@ _G.mp_event_loop = function()
         -- suspended, and the error was handled, but no resume was done.
         if wait > 0 then
             mp.resume_all()
+            if allow_wait ~= true then
+                return
+            end
         end
         local e = mp.wait_event(wait)
         -- Empty the event queue while suspended; otherwise, each
@@ -352,12 +377,7 @@ _G.mp_event_loop = function()
         mp.suspend()
         more_events = (e.event ~= "none")
         if more_events then
-            local handlers = event_handlers[e.event]
-            if handlers then
-                for _, handler in ipairs(handlers) do
-                    handler(e)
-                end
-            end
+            call_event_handlers(e)
         end
     end
 end