From 18c46ed2ddb27d4f18009e3d749f12b173a74754 Mon Sep 17 00:00:00 2001 From: Michael Albinus Date: Sat, 28 Jul 2018 17:30:26 +0200 Subject: [PATCH] Document visiting files asynchronously * doc/emacs/files.texi (Visiting): * doc/lispref/files.texi (Visiting Functions): Document visiting files asynchronously. * etc/NEWS: Rework entry about asynchronous file visiting. * lisp/files.el (find-file, find-file-other-window) (find-file-other-frame, find-file-existing) (find-alternate-file-other-window, find-alternate-file) (find-file-literally): Adapt docstring. --- doc/emacs/files.texi | 28 +++++++++++++++++++++++++++ doc/lispref/files.texi | 43 +++++++++++++++++++++++++++++------------- etc/NEWS | 13 +++++++------ lisp/files.el | 20 +++++++++++++------- 4 files changed, 78 insertions(+), 26 deletions(-) diff --git a/doc/emacs/files.texi b/doc/emacs/files.texi index f0a11fde555..46e64c2a270 100644 --- a/doc/emacs/files.texi +++ b/doc/emacs/files.texi @@ -228,6 +228,34 @@ File Names}, for information on how to visit a file whose name actually contains wildcard characters. You can disable the wildcard feature by customizing @code{find-file-wildcards}. +@cindex visiting files asynchronously +@vindex find-file-asynchronously + Sometimes, it is handy to visit a file asynchronously. This means, +while loading the file into its buffer Emacs keeps responsive, and you +can continue to edit other files, or call commands. This is +controlled by the user option @code{find-file-asynchronously}. If +this option is @code{nil} (the default), visiting a file is performed +synchronously. A regexp value let files, which name matches the +regexp, being visited asynchronously, and synchronously otherwise. +The value @code{t} forces asynchronous visiting of files +unconditionally. + +If you want to visit all remote files asynchronously, you should set + +@example +@group +(customize-set-variable + 'find-file-asynchronously tramp-file-name-regexp + "Visit remote files asynchronously") +@end group +@end example + + With a prefix argument @kbd{C-u}, the meaning of +@code{find-file-asynchronously} will be reverted. If this user option +is @code{nil}, visiting a file is performed asynchronously. Contrary, +if this user option is non-@code{nil}, visiting a file is performed +synchronously. + @kindex C-x C-v @findex find-alternate-file If you visit the wrong file unintentionally by typing its name diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 068cf054437..9faa47b4553 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -96,7 +96,7 @@ not alter it, the fastest way is to use @code{insert-file-contents} in a temporary buffer. Visiting the file is not necessary and takes longer. @xref{Reading from Files}. -@deffn Command find-file filename &optional wildcards +@deffn Command find-file filename &optional wildcards async This command selects a buffer visiting the file @var{filename}, using an existing buffer if there is one, and otherwise creating a new buffer and reading the file into it. It also returns that buffer. @@ -105,7 +105,8 @@ Aside from some technical details, the body of the @code{find-file} function is basically equivalent to: @smallexample -(switch-to-buffer (find-file-noselect filename nil nil wildcards)) +(switch-to-buffer + (find-file-noselect filename nil nil wildcards async)) @end smallexample @noindent @@ -115,21 +116,27 @@ If @var{wildcards} is non-@code{nil}, which is always true in an interactive call, then @code{find-file} expands wildcard characters in @var{filename} and visits all the matching files. +If @var{async} is non-@code{nil}, the file will be loaded into the +buffer asynchronously. Interactively, this is indicated by either +setting user option @code{find-file-asynchronously} to non-@code{nil}, +or by a prefix argument. + When @code{find-file} is called interactively, it prompts for @var{filename} in the minibuffer. @end deffn -@deffn Command find-file-literally filename +@deffn Command find-file-literally filename &optional async This command visits @var{filename}, like @code{find-file} does, but it does not perform any format conversions (@pxref{Format Conversion}), character code conversions (@pxref{Coding Systems}), or end-of-line conversions (@pxref{Coding System Basics, End of line conversion}). -The buffer visiting the file is made unibyte, and its major mode is -Fundamental mode, regardless of the file name. File local variable -specifications in the file (@pxref{File Local Variables}) are -ignored, and automatic decompression and adding a newline at the end -of the file due to @code{require-final-newline} (@pxref{Saving -Buffers, require-final-newline}) are also disabled. +If called interactively, the argument @var{async} is determined like +in @code{find-file}. The buffer visiting the file is made unibyte, +and its major mode is Fundamental mode, regardless of the file name. +File local variable specifications in the file (@pxref{File Local +Variables}) are ignored, and automatic decompression and adding a +newline at the end of the file due to @code{require-final-newline} +(@pxref{Saving Buffers, require-final-newline}) are also disabled. Note that if Emacs already has a buffer visiting the same file non-literally, it will not visit the same file literally, but instead @@ -139,7 +146,7 @@ buffer and then read the file contents into it using @code{insert-file-contents-literally} (@pxref{Reading from Files}). @end deffn -@defun find-file-noselect filename &optional nowarn rawfile wildcards +@defun find-file-noselect filename &optional nowarn rawfile wildcards async This function is the guts of all the file-visiting functions. It returns a buffer visiting the file @var{filename}. You may make the buffer current or display it in a window if you wish, but this @@ -157,7 +164,9 @@ Reading the file involves decoding the file's contents (@pxref{Coding Systems}), including end-of-line conversion, and format conversion (@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil}, then @code{find-file-noselect} expands wildcard characters in -@var{filename} and visits all the matching files. +@var{filename} and visits all the matching files. If @var{async} is +non-@code{nil} and there are several matching files due to expansion +of wildcard characters, every file will be loaded in an own thread. This function displays warning or advisory messages in various peculiar cases, unless the optional argument @var{nowarn} is non-@code{nil}. For @@ -191,7 +200,7 @@ various files. @end example @end defun -@deffn Command find-file-other-window filename &optional wildcards +@deffn Command find-file-other-window filename &optional wildcards async This command selects a buffer visiting the file @var{filename}, but does so in a window other than the selected window. It may use another existing window or split a window; see @ref{Switching @@ -201,7 +210,7 @@ When this command is called interactively, it prompts for @var{filename}. @end deffn -@deffn Command find-file-read-only filename &optional wildcards +@deffn Command find-file-read-only filename &optional wildcards async This command selects a buffer visiting the file @var{filename}, like @code{find-file}, but it marks the buffer as read-only. @xref{Read Only Buffers}, for related functions and variables. @@ -219,6 +228,14 @@ the @code{find-file} commands ignore their @var{wildcards} argument and never treat wildcard characters specially. @end defopt +@defopt find-file-asynchronously +If this variable is non-@code{nil}, a file will be visited +asynchronously when called interactively. If it is a regular +expression, it must match the file name to be visited. This behavior +is toggled by a prefix argument to the interactive call of the file +visiting command. +@end defopt + @defopt find-file-hook The value of this variable is a list of functions to be called after a file is visited. The file's local-variables specification (if any) will diff --git a/etc/NEWS b/etc/NEWS index 50d1b598680..8d18d3ea926 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -209,13 +209,14 @@ large files. Now it also offers a third alternative: to visit the file literally, as in 'find-file-literally', which speeds up navigation and editing of large files. ---- (Documentation to be added) ++++ ** Files can be visited asynchronously. -If the file visiting commands are prefixed like 'C-u C-x C-f ...', the -files are loaded asynchronously into the respective buffers. I.e., -Emacs is still responsive while loading the files, which is useful -especially for remote files. See the node "(emacs) Visiting" in the -user manual for the supported commands.. +If the new user option 'find-file-asynchronously' has a proper non-nil +value, interactive file visiting commands load the file asynchronously +into the respective buffer. I.e., Emacs is still responsive while +loading the files, which is useful especially for remote files. See +the node "(emacs) Visiting" in the user manual for the supported +commands. * Changes in Specialized Modes and Packages in Emacs 27.1 diff --git a/lisp/files.el b/lisp/files.el index 88c4752b463..128648ff316 100644 --- a/lisp/files.el +++ b/lisp/files.el @@ -1629,7 +1629,7 @@ suppress wildcard expansion by setting `find-file-wildcards' to nil. If ASYNC is non-nil, the file will be loaded into the buffer asynchronously. Interactively, this is indicated by either -setting `find-file-asynchronously' to nil, or by a prefix +setting `find-file-asynchronously' to non-nil, or by a prefix argument. To visit a file without any kind of conversion and without @@ -1665,7 +1665,8 @@ Interactively, or if WILDCARDS is non-nil in a call from Lisp, expand wildcards (if any) and visit multiple files. If ASYNC is non-nil, the file will be loaded into the buffer -asynchronously. Interactively, this is indicated by a prefix +asynchronously. Interactively, this is indicated by either +setting `find-file-asynchronously' to non-nil, or by a prefix argument." (interactive (find-file-read-args "Find file in other window: " @@ -1702,7 +1703,8 @@ Interactively, or if WILDCARDS is non-nil in a call from Lisp, expand wildcards (if any) and visit multiple files. If ASYNC is non-nil, the file will be loaded into the buffer -asynchronously. Interactively, this is indicated by a prefix +asynchronously. Interactively, this is indicated by either +setting `find-file-asynchronously' to non-nil, or by a prefix argument." (interactive (find-file-read-args "Find file in other frame: " @@ -1723,7 +1725,8 @@ Like \\[find-file], but only allow a file that exists, and do not allow file names with wildcards. If ASYNC is non-nil, the file will be loaded into the buffer -asynchronously. Interactively, this is indicated by a prefix +asynchronously. Interactively, this is indicated by either +setting `find-file-asynchronously' to non-nil, or by a prefix argument." (interactive (find-file-read-args "Find existing file: " t)) @@ -1781,7 +1784,8 @@ Interactively, or if WILDCARDS is non-nil in a call from Lisp, expand wildcards (if any) and replace the file with multiple files. If ASYNC is non-nil, the file will be loaded into the buffer -asynchronously. Interactively, this is indicated by a prefix +asynchronously. Interactively, this is indicated by either +setting `find-file-asynchronously' to non-nil, or by a prefix argument." (interactive (save-selected-window @@ -1823,7 +1827,8 @@ Interactively, or if WILDCARDS is non-nil in a call from Lisp, expand wildcards (if any) and replace the file with multiple files. If ASYNC is non-nil, the file will be loaded into the buffer -asynchronously. Interactively, this is indicated by a prefix +asynchronously. Interactively, this is indicated by either +setting `find-file-asynchronously' to non-nil, or by a prefix argument. If the current buffer is an indirect buffer, or the base buffer @@ -2493,7 +2498,8 @@ If Emacs already has a buffer which is visiting the file, this command asks you whether to visit it literally instead. If ASYNC is non-nil, the file will be loaded into the buffer -asynchronously. Interactively, this is indicated by a prefix +asynchronously. Interactively, this is indicated by either +setting `find-file-asynchronously' to non-nil, or by a prefix argument. In non-interactive use, the value is the buffer where the file is -- 2.39.5