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.2 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 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  = 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"]