Data.ByteString.Lazy.Builder.Extras

Extra functions for creating and executing Builders. They are intended for application-specific fine-tuning the performance of Builders.

Execution strategies

toLazyByteStringWith

Arguments

:: AllocationStrategy

Buffer allocation strategy to use

-> ByteString

Lazy ByteString to use as the tail of the generated lazy ByteString

-> Builder

Builder to execute

-> ByteString

Resulting lazy ByteString

Execute a Builder with custom execution parameters.

This function is forced to be inlined to allow fusing with the allocation strategy despite its rather heavy code-size. We therefore recommend that you introduce a top-level function once you have fixed your strategy. This avoids unnecessary code duplication. For example, the default Builder execution function toLazyByteString is defined as follows.

{--}
toLazyByteString =
  toLazyByteStringWith (safeStrategy smallChunkSize defaultChunkSize) empty

where empty is the zero-length lazy ByteString.

In most cases, the parameters used by toLazyByteString give good performance. A sub-performing case of toLazyByteString is executing short (<128 bytes) Builders. In this case, the allocation overhead for the first 4kb buffer and the trimming cost dominate the cost of executing the Builder. You can avoid this problem using

toLazyByteStringWith (safeStrategy 128 smallChunkSize) empty

This reduces the allocation and trimming overhead, as all generated ByteStrings fit into the first buffer and there is no trimming required, if more than 64 bytes are written.

data AllocationStrategy

A buffer allocation strategy for executing Builders.

safeStrategy

Arguments

:: Int

Size of first buffer

-> Int

Size of successive buffers

-> AllocationStrategy

An allocation strategy that guarantees that at least half of the allocated memory is used for live data

Use this strategy for generating lazy ByteStrings whose chunks are likely to survive one garbage collection. This strategy trims buffers that are filled less than half in order to avoid spilling too much memory.

untrimmedStrategy

Arguments

:: Int

Size of the first buffer

-> Int

Size of successive buffers

-> AllocationStrategy

An allocation strategy that does not trim any of the filled buffers before converting it to a chunk.

Use this strategy for generating lazy ByteStrings whose chunks are discarded right after they are generated. For example, if you just generate them to write them to a network socket.

smallChunkSize :: Int

The recommended chunk size. Currently set to 4k, less the memory management overhead

defaultChunkSize :: Int

The chunk size used for I/O. Currently set to 32k, less the memory management overhead

Controlling chunk boundaries

byteStringCopy :: ByteString -> Builder

Construct a Builder that copies the strict ByteString.

Use this function to create Builders from smallish (<= 4kb) ByteStrings or if you need to guarantee that the ByteString is not shared with the chunks generated by the Builder.

byteStringInsert :: ByteString -> Builder

Construct a Builder that always inserts the strict ByteString directly as a chunk.

This implies flushing the output buffer, even if it contains just a single byte. You should therefore use byteStringInsert only for large (> 8kb) ByteStrings. Otherwise, the generated chunks are too fragmented to be processed efficiently afterwards.

byteStringThreshold :: Int -> ByteString -> Builder

Construct a Builder that copies the strict ByteStrings, if it is smaller than the treshold, and inserts it directly otherwise.

For example, byteStringThreshold 1024 copies strict ByteStrings whose size is less or equal to 1kb, and inserts them directly otherwise. This implies that the average chunk-size of the generated lazy ByteString may be as low as 513 bytes, as there could always be just a single byte between the directly inserted 1025 byte, strict ByteStrings.

lazyByteStringCopy :: ByteString -> Builder

Construct a Builder that copies the lazy ByteString.

lazyByteStringInsert :: ByteString -> Builder

Construct a Builder that inserts all chunks of the lazy ByteString directly.

lazyByteStringThreshold :: Int -> ByteString -> Builder

Construct a Builder that uses the thresholding strategy of byteStringThreshold for each chunk of the lazy ByteString.

flush :: Builder

Flush the current buffer. This introduces a chunk boundary.

Host-specific binary encodings

intHost :: Int -> Builder

Encode a single native machine Int. The Int is encoded in host order, host endian form, for the machine you're on. On a 64 bit machine the Int is an 8 byte value, on a 32 bit machine, 4 bytes. Values encoded this way are not portable to different endian or int sized machines, without conversion.

int16Host :: Int16 -> Builder

Encode a Int16 in native host order and host endianness.

int32Host :: Int32 -> Builder

Encode a Int32 in native host order and host endianness.

int64Host :: Int64 -> Builder

Encode a Int64 in native host order and host endianness.

wordHost :: Word -> Builder

Encode a single native machine Word. The Word is encoded in host order, host endian form, for the machine you're on. On a 64 bit machine the Word is an 8 byte value, on a 32 bit machine, 4 bytes. Values encoded this way are not portable to different endian or word sized machines, without conversion.

word16Host :: Word16 -> Builder

Encode a Word16 in native host order and host endianness.

word32Host :: Word32 -> Builder

Encode a Word32 in native host order and host endianness.

word64Host :: Word64 -> Builder

Encode a Word64 in native host order and host endianness.

floatHost :: Float -> Builder

Encode a Float in native host order. Values encoded this way are not portable to different endian machines, without conversion.

doubleHost :: Double -> Builder

Encode a Double in native host order.