make-pipe-stream

Arguments:

make-pipe-stream creates and returns (as multiple values) a pair of bidirectional streams. For the purpose of discussion we'll call the first stream A and the second stream B. Data written to stream A will be readable on stream B. Likewise, data written to stream B will be readable on stream A. Contrast this with pipe where one stream is specifically the input stream and one stream is specifically the output stream.

Note: When it is time to flush the buffer for the stream being used as the output stream, the process flushing the output buffer will block until the other end of the pipe is read by another process. Example 1 below shows how a separate process should be used to read the stream. Example 2 shows Lisp blocking if this is not done correctly.

Pipe streams are not particularly useful by themselves. They are provided as a building block for inter-process communication within the lisp.

See also: make-function-input-stream (which uses pipe streams), and with-function-input-stream.

Example 1

;;  We create the streams and then start a separate process to 
;;  read data written to one of the streams. 
cl-user(1): (multiple-value-setq (one two) (make-pipe-stream))
#<pipe-stream  @ #x10963301>

cl-user(2): (mp:process-run-function "reader"              
               (lambda (s) (format t "Reader got: ~a~%" (read-line s))) two)
#<multiprocessing:process reader(3) @ #x109704a1>
cl-user(3): (write-line "hello there" one)
"hello there"
cl-user(4): (finish-output one)
Reader got: hello there
nil

Example 2

;;  In this example (which shows the WRONG thing to do), we create
;;  the pipe streams and start writing to one without arranging 
;;  for the material to be read. Lisp then hangs because it is
;;  waiting for the material to be read, but there is nothing to
;;  read it.
;;
;;  We include this example because (in our experience) this is 
;;  a common mistake made by programmers when they first use 
;;  MAKE-PIPE-STREAM. In Example 1 above, we do arrange for
;;  reading what is written to a pipe stream
;;
cl-user(1): (multiple-value-setq (one two) (make-pipe-stream))
#<pipe-stream  @ #x10963301>

cl-user(2): (write-line "hello" one)
"hello"

cl-user(3): (finish-output one)

;;  The Lisp will now block until the data is read from stream TWO.
;;  In this case it will block forever because there is no process 
;;  ready to read. Interrupt Lisp (typically with Control-C's on
;;  Unix, and with the Pause/Break or with the Console Window on
;;  Windows) to gain back control.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.