blaze-builder-enumerator-0.2.0.3: Enumeratees for the incremental conversion of builders to bytestrings.Source codeContentsIndex
Blaze.ByteString.Builder.Enumerator
PortabilityTested on GHC only
StabilityExperimental
MaintainerSimon Meier <iridcode@gmail.com>
Contents
Buffers
Status information
Creation and modification
Conversion to bytestings
Buffer allocation strategies
Enumeratees from builders to bytestrings
Description

Infrastructure and enumeratees for the incremental execution of builders and passing on of the filled chunks as bytestrings to an inner iteratee.

Note that the Buffer code is likely to move/change in order to reconciliate it with the rest of the blaze-builder library.

Synopsis
data Buffer
freeSize :: Buffer -> Int
sliceSize :: Buffer -> Int
bufferSize :: Buffer -> Int
allocBuffer :: Int -> IO Buffer
reuseBuffer :: Buffer -> Buffer
nextSlice :: Int -> Buffer -> Maybe Buffer
unsafeFreezeBuffer :: Buffer -> ByteString
unsafeFreezeNonEmptyBuffer :: Buffer -> Maybe ByteString
type BufferAllocStrategy = (IO Buffer, Int -> Buffer -> IO (IO Buffer))
allNewBuffersStrategy :: Int -> BufferAllocStrategy
reuseBufferStrategy :: IO Buffer -> BufferAllocStrategy
builderToByteString :: MonadIO m => Enumeratee Builder ByteString m a
unsafeBuilderToByteString :: MonadIO m => IO Buffer -> Enumeratee Builder ByteString m a
builderToByteStringWith :: MonadIO m => BufferAllocStrategy -> Enumeratee Builder ByteString m a
Buffers
data Buffer Source
A buffer Buffer fpbuf p0 op ope describes a buffer with the underlying byte array fpbuf..ope, the currently written slice p0..op and the free space op..ope.
Status information
freeSize :: Buffer -> IntSource
The size of the free space of the buffer.
sliceSize :: Buffer -> IntSource
The size of the written slice in the buffer.
bufferSize :: Buffer -> IntSource
The size of the whole byte array underlying the buffer.
Creation and modification
allocBuffer :: Int -> IO BufferSource
allocBuffer size allocates a new buffer of size size.
reuseBuffer :: Buffer -> BufferSource
Resets the beginning of the next slice and the next free byte such that the whole buffer can be filled again.
nextSlice :: Int -> Buffer -> Maybe BufferSource
Move the beginning of the slice to the next free byte such that the remaining free space of the buffer can be filled further. This operation is safe and can be used to fill the remaining part of the buffer after a direct insertion of a bytestring or a flush.
Conversion to bytestings
unsafeFreezeBuffer :: Buffer -> ByteStringSource
Convert the buffer to a bytestring. This operation is unsafe in the sense that created bytestring shares the underlying byte array with the buffer. Hence, depending on the later use of this buffer (e.g., if it gets reset and filled again) referential transparency may be lost.
unsafeFreezeNonEmptyBuffer :: Buffer -> Maybe ByteStringSource
Convert a buffer to a non-empty bytestring. See unsafeFreezeBuffer for the explanation of why this operation may be unsafe.
Buffer allocation strategies
type BufferAllocStrategy = (IO Buffer, Int -> Buffer -> IO (IO Buffer))Source
A buffer allocation strategy (buf0, nextBuf) specifies the initial buffer to use and how to compute a new buffer nextBuf minSize buf with at least size minSize from a filled buffer buf. The double nesting of the IO monad helps to ensure that the reference to the filled buffer buf is lost as soon as possible, but the new buffer doesn't have to be allocated too early.
allNewBuffersStrategy :: Int -> BufferAllocStrategySource

The simplest buffer allocation strategy: whenever a buffer is requested, allocate a new one that is big enough for the next build step to execute.

NOTE that this allocation strategy may spill quite some memory upon direct insertion of a bytestring by the builder. Thats no problem for garbage collection, but it may lead to unreasonably high memory consumption in special circumstances.

reuseBufferStrategy :: IO Buffer -> BufferAllocStrategySource
An unsafe, but possibly more efficient buffer allocation strategy: reuse the buffer, if it is big enough for the next build step to execute.
Enumeratees from builders to bytestrings
builderToByteString :: MonadIO m => Enumeratee Builder ByteString m aSource
Incrementally execute builders and pass on the filled chunks as bytestrings.
unsafeBuilderToByteString :: MonadIO m => IO Buffer -> Enumeratee Builder ByteString m aSource

Incrementally execute builders on the given buffer and pass on the filled chunks as bytestrings. Note that, if the given buffer is too small for the execution of a build step, a larger one will be allocated.

WARNING: This enumeratee yields bytestrings that are NOT referentially transparent. Their content will be overwritten as soon as control is returned from the inner iteratee!

builderToByteStringWith :: MonadIO m => BufferAllocStrategy -> Enumeratee Builder ByteString m aSource

An enumeratee that incrementally executes builders and passes on the filled chunks as bytestrings to an inner iteratee.

INV: All bytestrings passed to the inner iteratee are non-empty.

Produced by Haddock version 2.6.1