fix(lua): disallow vim.wait() in fast contexts

`vim.wait()` cannot be called in a fast callback since the main loop
cannot be run in that context as it is not reentrant

Fixes #26122

4 files changed, 11 insertions, 6 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index a79b26dfb0..a35d70cae8 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1143,6 +1143,8 @@ vim.wait({time}, {callback}, {interval}, {fast_only})             *vim.wait()*
     milliseconds (default 200). Nvim still processes other events during this
     time.
 
+    Cannot be called while in an |api-fast| event.
+
     Examples: >lua
         ---
         -- Wait for 100 ms, allowing other events to process
@@ -1173,8 +1175,7 @@ vim.wait({time}, {callback}, {interval}, {fast_only})             *vim.wait()*
       • {interval}   (integer|nil) (Approximate) number of milliseconds to
                      wait between polls
       • {fast_only}  (boolean|nil) If true, only |api-fast| events will be
-                     processed. If called from while in an |api-fast| event,
-                     will automatically be set to `true`.
+                     processed.
 
     Return: ~
         boolean, nil|-1|-2
@@ -1828,7 +1829,8 @@ vim.system({cmd}, {opts}, {on_exit})                            *vim.system()*
         • pid (integer) Process ID
         • wait (fun(timeout: integer|nil): SystemCompleted) Wait for the
           process to complete. Upon timeout the process is sent the KILL
-          signal (9) and the exit code is set to 124.
+          signal (9) and the exit code is set to 124. Cannot be called in
+          |api-fast|.
           • SystemCompleted is an object with the fields:
             • code: (integer)
             • signal: (integer)
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index b5bef13325..825e5ba41f 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -325,6 +325,8 @@ The following changes to existing APIs or features add new behavior.
   NOTE: the regexp engine still has a hard-coded limit of considering
   6 composing chars only.
 
+• |vim.wait()| is no longer allowed to be called in |api-fast|.
+
 ==============================================================================
 REMOVED FEATURES                                                 *news-removed*
 
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 12b632075d..6cccbe8313 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -124,7 +124,8 @@ vim.log = {
 --- @return vim.SystemObj Object with the fields:
 ---   - pid (integer) Process ID
 ---   - wait (fun(timeout: integer|nil): SystemCompleted) Wait for the process to complete. Upon
----     timeout the process is sent the KILL signal (9) and the exit code is set to 124.
+---     timeout the process is sent the KILL signal (9) and the exit code is set to 124. Cannot
+---     be called in |api-fast|.
 ---     - SystemCompleted is an object with the fields:
 ---      - code: (integer)
 ---      - signal: (integer)
diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua
index 92c23f7764..eeba356672 100644
--- a/runtime/lua/vim/_meta/builtin.lua
+++ b/runtime/lua/vim/_meta/builtin.lua
@@ -205,6 +205,8 @@ function vim.schedule(fn) end
 --- milliseconds (default 200). Nvim still processes other events during
 --- this time.
 ---
+--- Cannot be called while in an |api-fast| event.
+---
 --- Examples:
 ---
 --- ```lua
@@ -235,8 +237,6 @@ function vim.schedule(fn) end
 --- @param callback? fun(): boolean Optional callback. Waits until {callback} returns true
 --- @param interval? integer (Approximate) number of milliseconds to wait between polls
 --- @param fast_only? boolean If true, only |api-fast| events will be processed.
----                           If called from while in an |api-fast| event, will
----                           automatically be set to `true`.
 --- @return boolean, nil|-1|-2
 ---     - If {callback} returns `true` during the {time}: `true, nil`
 ---     - If {callback} never returns `true` during the {time}: `false, -1`