| Portability | GHC | 
|---|---|
| Maintainer | Simon Meier <iridcode@gmail.com> | 
| Safe Haskell | None | 
Data.ByteString.Lazy.Builder.Extras
Description
- toLazyByteStringWith :: AllocationStrategy -> ByteString -> Builder -> ByteString
- data AllocationStrategy
- safeStrategy :: Int -> Int -> AllocationStrategy
- untrimmedStrategy :: Int -> Int -> AllocationStrategy
- smallChunkSize :: Int
- defaultChunkSize :: Int
- byteStringCopy :: ByteString -> Builder
- byteStringInsert :: ByteString -> Builder
- byteStringThreshold :: Int -> ByteString -> Builder
- lazyByteStringCopy :: ByteString -> Builder
- lazyByteStringInsert :: ByteString -> Builder
- lazyByteStringThreshold :: Int -> ByteString -> Builder
- flush :: Builder
- intHost :: Int -> Builder
- int16Host :: Int16 -> Builder
- int32Host :: Int32 -> Builder
- int64Host :: Int64 -> Builder
- wordHost :: Word -> Builder
- word16Host :: Word16 -> Builder
- word32Host :: Word32 -> Builder
- word64Host :: Word64 -> Builder
- floatHost :: Float -> Builder
- doubleHost :: Double -> Builder
Execution strategies
Arguments
| :: AllocationStrategy | Buffer allocation strategy to use | 
| -> ByteString | Lazy  | 
| -> Builder | Builder to execute | 
| -> ByteString | Resulting lazy  | 
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.
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.
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.
The recommended chunk size. Currently set to 4k, less the memory management overhead
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.
Host-specific binary encodings
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.
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.