procyberian/emacs
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix process filter documentation (Bug#13400)

Browse source 
* doc/lispref/processes.texi (Asynchronous Processes): Note that input
may read when sending data as well.
(Output from Processes): Note that functions which send data may also
trigger reading from processes.
(Input to Processes, Filter Functions): Note that filter functions may
be called recursively.
This commit is contained in:
Noam Postavsky 2019-07-26 23:20:37 -04:00
parent beb1d22260
commit 615cff4258
1 changed files with 13 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

29
doc/lispref/processes.texi
View file

@ -588,9 +588,8 @@ process}. After an asynchronous process is created, it runs in
parallel with Emacs, and Emacs can communicate with it using the parallel with Emacs, and Emacs can communicate with it using the
functions described in the following sections (@pxref{Input to functions described in the following sections (@pxref{Input to
Processes}, and @pxref{Output from Processes}). Note that process Processes}, and @pxref{Output from Processes}). Note that process
communication is only partially asynchronous: Emacs sends data to the communication is only partially asynchronous: Emacs sends and receives
process only when certain functions are called, and Emacs accepts data data to and from a process only when those functions are called.
from the process only while waiting for input or for a time delay.
@cindex pty, when to use for subprocess communications @cindex pty, when to use for subprocess communications
@cindex pipe, when to use for subprocess communications @cindex pipe, when to use for subprocess communications
@ -1200,8 +1199,9 @@ the defaulting mechanism (@pxref{Default Coding Systems}).
because the input buffer is full. When this happens, the send functions because the input buffer is full. When this happens, the send functions
wait a short while, accepting output from subprocesses, and then try wait a short while, accepting output from subprocesses, and then try
again. This gives the subprocess a chance to read more of its pending again. This gives the subprocess a chance to read more of its pending
input and make space in the buffer. It also allows filters, sentinels input and make space in the buffer. It also allows filters (including
and timers to run---so take account of that in writing your code. the one currently running), sentinels and timers to run---so take
account of that in writing your code.
In these functions, the @var{process} argument can be a process or In these functions, the @var{process} argument can be a process or
the name of a process, or a buffer or buffer name (which stands the name of a process, or a buffer or buffer name (which stands
@ -1416,9 +1416,10 @@ output, Emacs won't receive that output.
Output from a subprocess can arrive only while Emacs is waiting: when Output from a subprocess can arrive only while Emacs is waiting: when
reading terminal input (see the function @code{waiting-for-user-input-p}), reading terminal input (see the function @code{waiting-for-user-input-p}),
in @code{sit-for} and @code{sleep-for} (@pxref{Waiting}), and in in @code{sit-for} and @code{sleep-for} (@pxref{Waiting}), in
@code{accept-process-output} (@pxref{Accepting Output}). This @code{accept-process-output} (@pxref{Accepting Output}), and in
minimizes the problem of timing errors that usually plague parallel functions which send data to processes (@pxref{Input to Processes}).
This minimizes the problem of timing errors that usually plague parallel
programming. For example, you can safely create a process and only programming. For example, you can safely create a process and only
then specify its buffer or filter function; no output can arrive then specify its buffer or filter function; no output can arrive
before you finish, if the code in between does not call any primitive before you finish, if the code in between does not call any primitive
@ -1594,14 +1595,10 @@ outputs directly to the process buffer.
By default, the error output from the process, if any, is also By default, the error output from the process, if any, is also
passed to the filter function, unless the destination for the standard passed to the filter function, unless the destination for the standard
error stream of the process was separated from the standard output error stream of the process was separated from the standard output
when the process was created (@pxref{Output from Processes}). when the process was created. Emacs will only call the filter
function during certain function calls. @xref{Output from Processes}.
The filter function can only be called when Emacs is waiting for Note that if any of those functions are called by the filter, the
something, because process output arrives only at such times. Emacs filter may be called recursively.
waits when reading terminal input (see the function
@code{waiting-for-user-input-p}), in @code{sit-for} and
@code{sleep-for} (@pxref{Waiting}), and in
@code{accept-process-output} (@pxref{Accepting Output}).
A filter function must accept two arguments: the associated process A filter function must accept two arguments: the associated process
and a string, which is output just received from it. The function is and a string, which is output just received from it. The function is