mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-24 14:30:43 -08:00
Code Issues Projects Releases Wiki Activity

Improve documentation of 'accept-process-output'

Browse source 
* doc/lispref/processes.texi (Accepting Output):
* src/process.c (Faccept_process_output): Document better the
meaning of the timeout of 'accept-process-output' a,d the fact
that it doesn't always return as soon as some output is available.
See https://lists.gnu.org/archive/html/emacs-devel/2025-08/msg00750.html
for more details.
This commit is contained in:
Eli Zaretskii 2025-09-20 12:32:21 +03:00
parent 65fb579896
commit 40adabe2ef
2 changed files with 19 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

12
doc/lispref/processes.texi
View file

@ -1989,7 +1989,8 @@ until output arrives from a process.
@defun accept-process-output &optional process seconds millisec just-this-one
This function allows Emacs to read pending output from processes. The
output is given to their filter functions. If @var{process} is
output is given to the filter functions set up by the processes
(@pxref{Filter Functions}). If @var{process} is
non-@code{nil} then this function does not return until some output
has been received from @var{process} or @var{process} has closed the
connection.
@ -2020,6 +2021,15 @@ got output from @var{process}, or from any process if @var{process} is
corresponding connection contains buffered data. The function returns
@code{nil} if the timeout expired or the connection was closed before output
arrived.
Note that this function is not guaranteed to return as soon as some
output is available from a subprocess, because the main purpose of the
function is to let Emacs read output from subprocesses, not to wait as
little as possible. In particular, if @var{process} is @code{nil}, the
function should not be expected to return before the specified timeout
expires. Thus, if a Lisp program needs to minimize the wait for the
subprocess output, it should call this function with a non-@code{nil}
value of a specific @var{process}.
@end defun
If a connection from a process contains buffered data,

10
src/process.c
View file

@ -4865,7 +4865,7 @@ deactivate_process (Lisp_Object proc)
DEFUN ("accept-process-output", Faccept_process_output, Saccept_process_output,
0, 4, 0,
doc: /* Allow any pending output from subprocesses to be read by Emacs.
It is given to their filter functions.
The subprocess output is given to the respective process filter functions.
Optional argument PROCESS means to return only after output is
received from PROCESS or PROCESS closes the connection.
@ -4880,7 +4880,13 @@ from PROCESS only, suspending reading output from other processes.
If JUST-THIS-ONE is an integer, don't run any timers either.
Return non-nil if we received any output from PROCESS (or, if PROCESS
is nil, from any process) before the timeout expired or the
corresponding connection was closed. */)
corresponding connection was closed.
Note that it is not guaranteed that this function will return as
soon as some output is received. In particular, if PROCESS is nil,
the function should not be expected to return before the timeout
expires. The main purpose of this function is to allow process output
to be read by Emacs, not to return as soon as any output is read. */)
(Lisp_Object process, Lisp_Object seconds, Lisp_Object millisec,
Lisp_Object just_this_one)
{