lua: add API for registering idle handlers

This is only a functionality the Lua event dispatcher provides, rather
than the libmpv client API.

2 files changed, 17 insertions, 0 deletions

diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst
index 256f6bd9ed..f1d9945055 100644
--- a/DOCS/man/lua.rst
+++ b/DOCS/man/lua.rst
@@ -456,6 +456,13 @@ are useful only in special situations.
     ``mp.get_wakeup_pipe()`` if you're interested in properly working
     notification of new events and working timers.
 
+``mp.register_idle(fn)``
+    Register an event loop idle handler. Idle handlers are called before the
+    script goes to sleep after handling all new events. This can be used for
+    example to delay processing of property change events: if you're observing
+    multiple properties at once, you might not want to act on each property
+    change, but only when all change notifications have been received.
+
 ``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,
diff --git a/player/lua/defaults.lua b/player/lua/defaults.lua
index 2c38361994..c65fda7c9b 100644
--- a/player/lua/defaults.lua
+++ b/player/lua/defaults.lua
@@ -412,6 +412,13 @@ mp.register_event("shutdown", function() mp.keep_running = false end)
 mp.register_event("client-message", message_dispatch)
 mp.register_event("property-change", property_change)
 
+-- called before the event loop goes back to sleep
+local idle_handlers = {}
+
+function mp.register_idle(cb)
+    idle_handlers[#idle_handlers + 1] = cb
+end
+
 -- sent by "script-binding"
 mp.register_script_message("key-binding", dispatch_key_binding)
 
@@ -455,6 +462,9 @@ function mp.dispatch_events(allow_wait)
         if not more_events then
             wait = process_timers()
             if wait == nil then
+                for _, handler in ipairs(idle_handlers) do
+                    handler()
+                end
                 wait = 1e20 -- infinity for all practical purposes
             end
             -- Resume playloop - important especially if an error happened while