io-streams-1.5.2.2: Simple, composable, and easy-to-use stream I/O

Safe Haskell | None
Language | Haskell2010

System.IO.Streams.Builder

Contents

- Blaze builder conversion

Description

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  = map byteString l1 ++ [flush] ++ map byteString 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

- builderStream :: OutputStream ByteString -> IO (OutputStream Builder)
- builderStreamWithBufferSize :: Int -> OutputStream ByteString -> IO (OutputStream Builder)
- unsafeBuilderStream :: IO Buffer -> OutputStream ByteString -> IO (OutputStream Builder)

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

builderStreamWithBufferSize :: Int -> OutputStream ByteString -> IO (OutputStream Builder) #

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

Since: 1.3.0.0.

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 `newBuffer`.