From: Thien-Thi Nguyen Date: Sun, 24 Jun 2012 09:30:35 +0000 (+0800) Subject: Lisp manual -- improve discussion of ptys vs pipes. X-Git-Tag: emacs-24.2.90~1199^2~372 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=6d41a41d81d60e8a351e85656ba71c99ab8f6bf5;p=emacs.git Lisp manual -- improve discussion of ptys vs pipes. * processes.texi (Asynchronous Processes): Make the pty vs pipe discussion more prominent. --- diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 154b4487d5e..782b6930a84 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,8 @@ +2012-06-24 Thien-Thi Nguyen + + * processes.texi (Asynchronous Processes): Make the pty vs pipe + discussion more prominent. + 2012-06-23 Eli Zaretskii * commands.texi (Misc Events): Document the language-change event. diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index d1bfa0e936d..fc166268e4e 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -541,16 +541,29 @@ is decoded in the same way as for @code{call-process}. @section Creating an Asynchronous Process @cindex asynchronous subprocess - After an @dfn{asynchronous process} is created, Emacs and the subprocess -both continue running immediately. The process thereafter runs -in parallel with Emacs, and the two can communicate with each other -using the functions described in the following sections. However, + In this section, we describe how to create an @dfn{asynchronous +process}. After an asynchronous process is created, it runs in +parallel with Emacs, and Emacs can communicate with it using the +functions described in the following sections (@pxref{Input to +Processes}, and @pxref{Output from Processes}). Note that process communication is only partially asynchronous: Emacs sends data to the process only when certain functions are called, and Emacs accepts data -from the process only when Emacs is waiting for input or for a time -delay. - - Here we describe how to create an asynchronous process. +from the process only while waiting for input or for a time delay. + +@cindex pty +@cindex pipe + An asynchronous process is controlled either via a @dfn{pty} +(pseudo-terminal) or a @dfn{pipe}. The choice of pty or pipe is made +when creating the process, based on the value of the variable +@code{process-connection-type} (see below). Ptys are usually +preferable for processes visible to the user, as in Shell mode, +because they allow for job control (@kbd{C-c}, @kbd{C-z}, etc.) +between the process and its children, whereas pipes do not. For +subprocesses used for internal purposes by programs, it is often +better to use a pipe, because they are more efficient, and because +they are immune to stray character injections that ptys introduce for +large (around 500 byte) messages. Also, the total number of ptys is +limited on many systems and it is good not to waste them. @defun start-process name buffer-or-name program &rest args This function creates a new asynchronous subprocess and starts the @@ -652,20 +665,10 @@ can also be executed on remote hosts, depending on @code{default-directory}. @end defun @defvar process-connection-type -@cindex pipes -@cindex @acronym{PTY}s This variable controls the type of device used to communicate with asynchronous subprocesses. If it is non-@code{nil}, then @acronym{PTY}s are used, when available. Otherwise, pipes are used. -@acronym{PTY}s are usually preferable for processes visible to the user, as -in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z}, -etc.) to work between the process and its children, whereas pipes do -not. For subprocesses used for internal purposes by programs, it is -often better to use a pipe, because they are more efficient. In -addition, the total number of @acronym{PTY}s is limited on many systems and -it is good not to waste them. - The value of @code{process-connection-type} takes effect when @code{start-process} is called. So you can specify how to communicate with one subprocess by binding the variable around the call to