Safe Haskell | None |
---|---|
Language | Haskell2010 |
Buffering for output streams based on bytestring builders.
Buffering an output stream can often improve throughput by reducing the
number of system calls made through the file descriptor. The bytestring
package provides an efficient monoidal datatype used for serializing values
directly to an output buffer, called a Builder
, originally implemented in
the blaze-builder
package by Simon Meier. When compiling with bytestring
versions older than 0.10.4, (i.e. GHC <= 7.6) users must depend on the
bytestring-builder
library to get the new builder implementation. Since we
try to maintain compatibility with the last three GHC versions, the
dependency on bytestring-builder
can be dropped after the release of GHC
7.12.
Using this module
Given an OutputStream
taking ByteString
:
someOutputStream :: OutputStream ByteString
You create a new output stream wrapping the original one that accepts
Builder
values:
do newStream <- Streams.builderStream
someOutputStream Streams.write
(Just
$byteString
"hello") newStream ....
You can flush the output buffer using flush
:
.... Streams.write
(Just
flush
) newStream ....
As a convention, builderStream
will write the empty string to the wrapped
OutputStream
upon a builder buffer flush. Output streams which receive
ByteString
should either ignore the empty string or interpret it as a
signal to flush their own buffers, as the handleToOutputStream
and
System.IO.Streams.Zlib functions do.
Example
example :: IO [ByteString] example = do let l1 =intersperse
" " ["the", "quick", "brown", "fox"] let l2 =intersperse
" " ["jumped", "over", "the"] let l = mapbyteString
l1 ++ [flush
] ++ mapbyteString
l2 is <- Streams.fromList
l (os0, grab) <- Streams.listOutputStream
os <- Streams.builderStream
os0 Streams.connect
is os >> grab ghci> example ["the quick brown fox","","jumped over the"]
Synopsis
Blaze builder conversion
builderStream :: OutputStream ByteString -> IO (OutputStream Builder) Source #
Converts a ByteString
sink into a Builder
sink.
Note that if the generated builder receives a
flush
, by convention it will send an empty string
to the supplied
to indicate that any output
buffers are to be flushed.OutputStream
ByteString
builderStreamWithBufferSize :: Int -> OutputStream ByteString -> IO (OutputStream Builder) Source #
Converts a ByteString
sink into a Builder
sink, using the supplied
buffer size.
Note that if the generated builder receives a
flush
, by convention it will send an empty string
to the supplied
to indicate that any output
buffers are to be flushed.OutputStream
ByteString
Since: 1.3.0.0.
unsafeBuilderStream :: IO Buffer -> OutputStream ByteString -> IO (OutputStream Builder) Source #
Unsafe variation on builderStream
that reuses an existing buffer for
efficiency.
NOTE: because the buffer is reused, subsequent ByteString
values written
to the wrapped OutputString
will cause previous yielded strings to change.
Do not retain references to these ByteString
values inside the
OutputStream
you pass to this function, or you will violate referential
transparency.
If you must retain copies of these values, then please use
copy
to ensure that you have a fresh copy of the
underlying string.
You can create a Buffer with newBuffer
.