with-staged-output

Arguments: (staging-stream stream) &body body

If output to stream is synchronized (as per synchronized-output-stream-p), then bind staging-stream to a string output stream whose contents are written atomically to stream upon leaving body (even if by a non-local exit). Atomicity in this context means that stream is locked with with-locked-stream, thus output is safe even in face of concurrent use, provided that all threads use with-staged-output or lock the stream directly.

Currently almost all functions that write streams employ with-staged-output, so that the user only has to (setf (synchronized-output-stream-p stream) t and output to the stream will not be mixed, lost, etc. even if several threads write the stream at the same time.

print-unreadable-object, write, write-sequence, write-vector, write-string, write-line, pprint, pprint-fill, pprint-linear, and pprint-tabular all use with-staged-output. format does too except when creating a string (i.e. its first argument is nil).

Notable functions that do not use with-staged-output (because the overhead would be too high): write-char, write-byte, and terpri.

Notes:

1. The staging stream is a single channel output stream (buffer-output-simple-stream or a string-output-simple-stream). If the underlying stream is to be used for input (and output) then with-staged-output may not be the best idea. Input synchronization is not currently supported.
2. The dynamic context in which actual output is written is different, so one must be careful with - among other things - condition handlers.
3. Closing the underlying stream before the contents of the staging stream are written to it is not allowed.

Nested occurences of with-staged-output do the right thing by default: unless the staging stream is synchronized, the inner with-staged-output will simply bind staging-stream to stream.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.