lua: add API for registering idle handlers

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

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,

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