path: root/DOCS
diff options
authorAvi Halachmi (:avih) <>2017-12-22 13:50:38 +0200
committerKevin Mitchell <>2018-04-07 16:02:19 -0700
commit9a47023c444df488ff51c8f86fbd1b1b93e99a9b (patch)
tree1ec4e64361565deb06836f4c76cd72ccc214aa71 /DOCS
parentb04f0cad43eb627fb4e970367062329e3331d9fe (diff)
js: implement mp.register_idle
Due to earlier misinterpretation of the Lua docs as if mp.register_idle registers a one-shot callback, the JS docs suggested to use setTimeout. But the behavior and Lua docs are such that it's a repeating callback which fires just before the script thread goes to sleep. Implement it for JS too.
Diffstat (limited to 'DOCS')
1 files changed, 16 insertions, 5 deletions
diff --git a/DOCS/man/javascript.rst b/DOCS/man/javascript.rst
index 5b446cea69..184c962a97 100644
--- a/DOCS/man/javascript.rst
+++ b/DOCS/man/javascript.rst
@@ -67,10 +67,6 @@ Unsupported Lua APIs and their JS alternatives
``mp.add_periodic_timer(seconds, fn)`` JS: ``id = setInterval(fn, ms)``
-``mp.register_idle(fn)`` JS: ``id = setTimeout(fn)``
-``mp.unregister_idle(fn)`` JS: ``clearTimeout(id)``
``utils.parse_json(str [, trail])`` JS: ``JSON.parse(str)``
``utils.format_json(v)`` JS: ``JSON.stringify(v)``
@@ -142,6 +138,10 @@ Otherwise, where the Lua APIs return ``nil`` on error, JS returns ``undefined``.
``mp.register_script_message(name, fn)``
@@ -267,7 +267,7 @@ event loop iteration or at a later event loop iteration. This is true also for
intervals - which also never call back twice at the same event loop iteration.
Additionally, timers are processed after the event queue is empty, so it's valid
-to use ``setTimeout(fn)`` instead of Lua's ``mp.register_idle(fn)``.
+to use ``setTimeout(fn)`` as a one-time idle observer.
CommonJS modules and ``require(id)``
@@ -320,6 +320,10 @@ also print every event which mpv sends to your script:
wait = 0;
} else {
wait = mp.process_timers() / 1000;
+ if (wait != 0) {
+ mp.notify_idle_observers();
+ wait = mp.peek_timers_wait() / 1000;
+ }
} while (mp.keep_running);
@@ -339,5 +343,12 @@ if there are such (event handlers, property observers, script messages, etc).
and returns the duration in ms till the next due timer (possibly 0), or -1 if
there are no pending timers. Must not be called recursively.
+``mp.notify_idle_observers()`` calls back the idle observers, which we do when
+we're about to sleep (wait != 0), but the observers may add timers or take
+non-negligible duration to complete, so we re-calculate ``wait`` afterwards.
+``mp.peek_timers_wait()`` returns the same values as ``mp.process_timers()``
+but without doing anything. Invalid result if called from a timer callback.
Note: ``exit()`` is also registered for the ``shutdown`` event, and its
implementation is a simple ``mp.keep_running = false``.