docs: lua, UI events #34261

runtime/doc/develop.txt

@@ -666,6 +666,7 @@ External UIs are expected to implement these common features:
   the user).
 - Support the text decorations/attributes given by |ui-event-hl_attr_define|.
   The "url" attr should be presented as a clickable hyperlink.
+- Handle the "restart" UI event so that |:restart| works.
 
 
  vim:tw=78:ts=8:sw=4:et:ft=help:norl:

runtime/doc/gui.txt

@@ -64,18 +64,24 @@ Stop or detach the current UI
                 the channel to be closed, it may be (incorrectly) reported as
                 an error.
 
-                Note: Not supported on Windows, currently.
+                Note: Not supported on Windows yet.
 
 ------------------------------------------------------------------------------
-Restart the embedded Nvim server
+Restart Nvim
 
                                                 *:restart*
 :restart
-                Detaches the embedded server from the UI and then restarts
+                Restarts the Nvim server with the same startup arguments
-                it. This fails when changes have been made
+                |v:argv| and reattaches the current UI to the new server.
-                and Vim refuses to |abandon| the current buffer.
+                All other UIs will detach.
+
+                This fails when changes have been made and Vim refuses to
+                |abandon| the current buffer.
+
+                Note: This only works if the UI and server are on the same
+                system.
+                Note: Not supported on Windows yet.
 
-                Note: This only works if the UI started the server initially.
 :restart!
                 Force restarts the embedded server irrespective of unsaved
                 buffers.

runtime/doc/lua.txt

@@ -1814,9 +1814,11 @@ vim.system({cmd}, {opts}, {on_exit})                            *vim.system()*
         • cmd (string[]) Command name and args
         • pid (integer) Process ID
         • wait (fun(timeout: integer|nil): SystemCompleted) Wait for the
-          process to complete. Upon timeout the process is sent the KILL
+          process to complete, including any open handles for background
-          signal (9) and the exit code is set to 124. Cannot be called in
+          processes (e.g., `bash -c 'sleep 10 &'`). To avoid waiting for
-          |api-fast|.
+          handles, set stdout=false and stderr=false. Upon 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)

runtime/doc/news.txt

@@ -222,6 +222,7 @@ TUI
 
 UI
 
+• |:restart| restarts Nvim and reattaches the current UI.
 • |:checkhealth| shows a summary in the header for every healthcheck.
 • |ui-multigrid| provides composition information and absolute coordinates.
 • `vim._extui` provides an experimental commandline and message UI intended to
@@ -229,7 +230,6 @@ UI
 • Error messages are more concise:
   • "Error detected while processing:" changed to "Error in:".
   • "Error executing Lua:" changed to "Lua:".
-• |:restart| detaches the embedded server from the UI and then restarts it.
 
 VIMSCRIPT
 

runtime/doc/ui.txt

@@ -226,8 +226,7 @@ the editor.
 	sent from Nvim, like for |ui-cmdline|.
 
 ["chdir", path] ~
-	The |current-directory| of the embedded Nvim process changed to
+	The |current-directory| changed to `path`.
-	`path`.
 
 ["mode_change", mode, mode_idx] ~
 	Editor mode changed.  The `mode` parameter is a string representing
@@ -249,6 +248,11 @@ the editor.
 	Indicates to the UI that it must stop rendering the cursor. This event
 	is misnamed and does not actually have anything to do with busyness.
 
+["restart"] ~
+	|:restart| command was used. The UI should stop-and-restart the Nvim
+	server using the same startup arguments |v:argv|, and reattach to the
+	new server.
+
 ["suspend"] ~
 	|:suspend| command or |CTRL-Z| mapping is used. A terminal client (or
 	another client where it makes sense) could suspend itself.  Other

runtime/lua/vim/_editor.lua

@@ -130,9 +130,10 @@ local utfs = {
 --- @return vim.SystemObj Object with the fields:
 ---   - cmd (string[]) Command name and args
 ---   - pid (integer) Process ID
----   - wait (fun(timeout: integer|nil): SystemCompleted) Wait for the process to complete. Upon
+---   - wait (fun(timeout: integer|nil): SystemCompleted) Wait for the process to complete,
----     timeout the process is sent the KILL signal (9) and the exit code is set to 124. Cannot
+---     including any open handles for background processes (e.g., `bash -c 'sleep 10 &'`).
----     be called in |api-fast|.
+---     To avoid waiting for handles, set stdout=false and stderr=false. Upon 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)

src/nvim/api/ui_events.in.h

@@ -29,6 +29,8 @@ void visual_bell(void)
   FUNC_API_SINCE(3);
 void flush(void)
   FUNC_API_SINCE(3) FUNC_API_REMOTE_IMPL;
+void restart(void)
+  FUNC_API_SINCE(14) FUNC_API_REMOTE_ONLY FUNC_API_CLIENT_IMPL;
 void suspend(void)
   FUNC_API_SINCE(3);
 void set_title(String title)
@@ -177,5 +179,3 @@ void msg_history_clear(void)
 
 void error_exit(Integer status)
   FUNC_API_SINCE(12);
-void restart(void)
-  FUNC_API_SINCE(14) FUNC_API_REMOTE_ONLY FUNC_API_CLIENT_IMPL;