System.IO.Streams.Builder

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 blaze-builder package provides an efficient set of primitives for serializing values directly to an output buffer.

(N.B.: most of the blaze-builder package has been moved into bytestring in versions >= 0.10; once two or three Haskell Platform editions have been released that contain bytestring 0.10 or higher, the dependency on blaze-builder will be dropped in favor of the native support for Builder contained in the bytestring package.)

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 $ fromByteString "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 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  = map fromByteString l1 ++ [flush] ++ map fromByteString 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"]

Blaze builder conversion

builderStream :: OutputStream ByteString -> IO (OutputStream Builder)

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 OutputStream ByteString to indicate that any output buffers are to be flushed.

unsafeBuilderStream :: IO Buffer -> OutputStream ByteString -> IO (OutputStream Builder)

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 allocBuffer.

builderStreamWith :: BufferAllocStrategy -> OutputStream ByteString -> IO (OutputStream Builder)

A customized version of builderStream, using the specified BufferAllocStrategy.