From bb0b9f4cc8952889bd62b347023d912c8f6669b9 Mon Sep 17 00:00:00 2001
From: Guido Cella <guido@guidocella.xyz>
Date: Fri, 1 Nov 2024 16:15:36 +0100
Subject: [PATCH] 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
bf385e1140 (though it was accurate when the JS backend was developed
before upstreaming it).
---
 .luacheckrc             |  1 +
 DOCS/man/javascript.rst |  6 ++----
 DOCS/man/lua.rst        | 14 ++++++++++++++
 player/lua/defaults.lua |  6 +++++-
 4 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/.luacheckrc b/.luacheckrc
index 6f3c0bdb29640..56f348ea02509 100644
--- a/.luacheckrc
+++ b/.luacheckrc
@@ -64,6 +64,7 @@ local mp_globals = {
             set_osd_ass = {},
         }
     },
+    exit = {},
     unpack = {},
 }
 
diff --git a/DOCS/man/javascript.rst b/DOCS/man/javascript.rst
index 6dfae8b601286..cd7f48d263b78 100644
--- a/DOCS/man/javascript.rst
+++ b/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
diff --git a/DOCS/man/lua.rst b/DOCS/man/lua.rst
index 95234c37842d4..dc23d35353fd0 100644
--- a/DOCS/man/lua.rst
+++ b/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
 ----------------
 
diff --git a/player/lua/defaults.lua b/player/lua/defaults.lua
index 0dc6cc8624340..5cff86b1ba3c8 100644
--- a/player/lua/defaults.lua
+++ b/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)