defaults.lua: add an exit() function

Scripts can terminate execution by setting mp.keep_running = false. Add
an exit() function to wrap setting mp.keep_running and properly expose
this feature. It can be used e.g. by a thumbnail script to spawn workers
with load-script and then let them quit.

It is not added to the mp namespace as mp.exit because that would make
it look like it terminates mpv.

This mirrors the exit() function which already exists in js.

The note in javascript.rst about having to remove key bindings before
exit is not kept because they are actually removed automatically since
bf385e1 (though it was accurate when the JS backend was developed
before upstreaming it).

.luacheckrc

@@ -64,6 +64,7 @@ local mp_globals = {
             set_osd_ass = {},
         }
     },
+    exit = {},
     unpack = {},
 }
 

DOCS/man/javascript.rst

@@ -208,6 +208,8 @@ string/boolean/number)
 
 ``mp.input.set_log(log)``
 
+``exit()`` (global)
+
 Additional utilities
 --------------------
 
@@ -256,10 +258,6 @@ text content only.
 ``mp.get_script_file()``
     Returns the file name of the current script.
 
-``exit()`` (global)
-    Make the script exit at the end of the current event loop iteration.
-    Note: please remove added key bindings before calling ``exit()``.
-
 ``mp.utils.compile_js(fname, content_str)``
     Compiles the JS code ``content_str`` as file name ``fname`` (without loading
     anything from the filesystem), and returns it as a function. Very similar

DOCS/man/lua.rst

@@ -647,6 +647,20 @@ are useful only in special situations.
 
     May return invalid/nonsense values if OSD is not initialized yet.
 
+``exit()`` (global)
+    Make the script exit at the end of the current event loop iteration. This
+    does not terminate mpv itself or other scripts.
+
+    This can be polyfilled to support mpv versions older than 0.40 with:
+
+    ::
+
+        if not _G.exit then
+            function exit()
+                mp.keep_running = false
+            end
+        end
+
 mp.msg functions
 ----------------
 

player/lua/defaults.lua

@@ -416,6 +416,10 @@ end
 -- used by default event loop (mp_event_loop()) to decide when to quit
 mp.keep_running = true
 
+function _G.exit()
+    mp.keep_running = false
+end
+
 local event_handlers = {}
 
 function mp.register_event(name, cb)
@@ -455,7 +459,7 @@ function mp.unregister_event(cb)
 end
 
 -- default handlers
-mp.register_event("shutdown", function() mp.keep_running = false end)
+mp.register_event("shutdown", exit)
 mp.register_event("client-message", message_dispatch)
 mp.register_event("property-change", property_change)