System.IO.ByteBuffer

A ByteBuffer is a simple buffer for bytes. It supports two operations: refilling with the contents of a ByteString, and consuming a fixed number of bytes.

It is implemented as a pointer, together with counters that keep track of the offset and the number of bytes in the buffer. Note that the counters are simple IORefs, so ByteBuffers are not thread-safe!

A ByteBuffer is constructed by new with a given starting length, and will grow (by repeatedly multiplying its size by 1.5) whenever it is being fed a ByteString that is too large.

Documentation

type ByteBuffer = IORef (Either ByteBufferException BBRef)

Allocation and Deallocation

new

Arguments

:: MonadIO m

=> Maybe Int

Size of buffer to allocate. If Nothing, use the default value of 4MB

-> m ByteBuffer

The byte buffer.

Allocates a new ByteBuffer with a given buffer size filling from the given FillBuffer.

Note that ByteBuffers created with new have to be deallocated explicitly using free. For automatic deallocation, consider using with instead.

free :: MonadIO m => ByteBuffer -> m ()

Free a byte buffer.

with

Arguments

:: (MonadIO m, MonadBaseControl IO m)

=> Maybe Int

Initial length of the ByteBuffer. If Nothing, use the default value of 4MB.

-> (ByteBuffer -> m a)

-> m a

Perform some action with a bytebuffer, with automatic allocation and deallocation.

Query for number of available bytes

totalSize :: MonadIO m => ByteBuffer -> m Int

isEmpty :: MonadIO m => ByteBuffer -> m Bool

availableBytes :: MonadIO m => ByteBuffer -> m Int

Number of available bytes in a ByteBuffer (that is, bytes that have been copied to, but not yet read from the ByteBuffer.

Feeding new input

copyByteString :: MonadIO m => ByteBuffer -> ByteString -> m ()

Copy the contents of a ByteString to a ByteBuffer.

If necessary, the ByteBuffer is enlarged and/or already consumed bytes are dropped.

fillFromFd :: (MonadIO m, MonadFail m) => ByteBuffer -> Fd -> Int -> m Int

Will read at most n bytes from the given Fd, in a non-blocking fashion. This function is intended to be used with non-blocking Sockets, such the ones created by the network package.

Returns how many bytes could be read non-blockingly.

Consuming bytes from the buffer

consume :: MonadIO m => ByteBuffer -> Int -> m (Either Int ByteString)

As unsafeConsume, but instead of returning a Ptr into the contents of the ByteBuffer, it returns a ByteString containing the next n bytes in the buffer. This involves allocating a new ByteString and copying the n bytes to it.

unsafeConsume

Arguments

:: MonadIO m

=> ByteBuffer

-> Int

n

-> m (Either Int (Ptr Word8))

Will be Left missing when there are only n-missing bytes left in the ByteBuffer.

Try to get a pointer to n bytes from the ByteBuffer.

Note that the pointer should be used before any other actions are performed on the ByteBuffer. It points to some address within the buffer, so operations such as enlarging the buffer or feeding it new data will change the data the pointer points to. This is why this function is called unsafe.

Exceptions

data ByteBufferException

Exception that is thrown when an invalid ByteBuffer is being used that is no longer valid.

A ByteBuffer is considered to be invalid if

• it has explicitly been freed
• an Exception has occured during an operation that modified it

Constructors

ByteBufferException

Fields

• _bbeLocation :: !String

  function name that caused the exception

• _bbeException :: !String

  printed representation of the exception

Instances

Eq ByteBufferException

Defined in System.IO.ByteBuffer

Methods

(==) :: ByteBufferException -> ByteBufferException -> Bool

(/=) :: ByteBufferException -> ByteBufferException -> Bool

Show ByteBufferException

Defined in System.IO.ByteBuffer

Methods

showsPrec :: Int -> ByteBufferException -> ShowS

show :: ByteBufferException -> String

showList :: [ByteBufferException] -> ShowS

Exception ByteBufferException

Defined in System.IO.ByteBuffer

Methods

toException :: ByteBufferException -> SomeException

fromException :: SomeException -> Maybe ByteBufferException

displayException :: ByteBufferException -> String