streaming-commons-0.1.13: Common lower-level functions needed by various streaming data libraries

Safe HaskellNone
LanguageHaskell98

Data.Streaming.ByteString.Builder.Buffer

Contents

Description

Buffers for Builders. This is a partial copy of blaze-builder-0.3.3.4's Blaze.ByteString.Builder.Internal.Buffer module, which was removed in blaze-builder-0.4.

If you are using blaze-builder 0.3.*, this module just re-exports from Blaze.ByteString.Builder.Internal.Buffer.

Since 0.1.10.0

Synopsis

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.

Since 0.1.10.0

Constructors

Buffer !(ForeignPtr Word8) !(Ptr Word8) !(Ptr Word8) !(Ptr Word8) 

Status information

freeSize :: Buffer -> Int Source

The size of the free space of the buffer.

Since 0.1.10.0

sliceSize :: Buffer -> Int Source

The size of the written slice in the buffer.

Since 0.1.10.0

bufferSize :: Buffer -> Int Source

The size of the whole byte array underlying the buffer.

Since 0.1.10.0

Creation and modification

allocBuffer :: Int -> IO Buffer Source

allocBuffer size allocates a new buffer of size size.

Since 0.1.10.0

reuseBuffer :: Buffer -> Buffer Source

Resets the beginning of the next slice and the next free byte such that the whole buffer can be filled again.

Since 0.1.10.0

nextSlice :: Int -> Buffer -> Maybe Buffer Source

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.

Since 0.1.10.0

updateEndOfSlice :: Buffer -> Ptr Word8 -> Buffer Source

Update the end of slice pointer.

Since 0.1.10.0

Conversion to bytestings

unsafeFreezeBuffer :: Buffer -> ByteString Source

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.

Since 0.1.10.0

unsafeFreezeNonEmptyBuffer :: Buffer -> Maybe ByteString Source

Convert a buffer to a non-empty bytestring. See unsafeFreezeBuffer for the explanation of why this operation may be unsafe.

Since 0.1.10.0

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.

Since 0.1.10.0

allNewBuffersStrategy :: Int -> BufferAllocStrategy Source

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.

Since 0.1.10.0

reuseBufferStrategy :: IO Buffer -> BufferAllocStrategy Source

An unsafe, but possibly more efficient buffer allocation strategy: reuse the buffer, if it is big enough for the next build step to execute.

Since 0.1.10.0