Data.Store.Streaming

For efficiency reasons, Store does not provide facilities for incrementally consuming input. In order to avoid partial input, this module introduces Messages that wrap values of instances of Store.

In addition to the serialisation of a value, the serialised message also contains the length of the serialisation. This way, instead of consuming input incrementally, more input can be demanded before serialisation is attempted in the first place.

Each message starts with a fixed magic number, in order to detect (randomly) invalid data.

Messages to stream data using Store for serialisation.

newtype Message a

If a is an instance of Store, Message a can be serialised and deserialised in a streaming fashion.

Constructors

Message

Fields

• fromMessage :: a

Instances

Eq a => Eq (Message a)

Methods

(==) :: Message a -> Message a -> Bool

(/=) :: Message a -> Message a -> Bool

Show a => Show (Message a)

Methods

showsPrec :: Int -> Message a -> ShowS

show :: Message a -> String

showList :: [Message a] -> ShowS

Encoding Messages

encodeMessage :: Store a => Message a -> ByteString

Encode a Message to a ByteString.

Decoding Messages

data PeekMessage m a

The result of peeking at the next message can either be a successfully deserialised Message, or a request for more input.

Constructors

Done (Message a)

NeedMoreInput (ByteString -> m (PeekMessage m a))

peekMessage :: (MonadIO m, Store a) => ByteBuffer -> m (PeekMessage m a)

Decode some Message from a ByteBuffer, by first reading its header, and then the actual Message.

decodeMessage :: (MonadIO m, Store a) => ByteBuffer -> m (Maybe ByteString) -> m (Maybe (Message a))

Decode a Message from a ByteBuffer and an action that can get additional ByteStrings to refill the buffer when necessary.

The only conditions under which this function will give Nothing, is when the ByteBuffer contains zero bytes, and refilling yields Nothing. If there is some data available, but not enough to decode the whole Message, a PeekException will be thrown.

Conduits for encoding and decoding

conduitEncode :: (Monad m, Store a) => Conduit (Message a) m ByteString

Conduit for encoding Messages to ByteStrings.

conduitDecode

Arguments

:: (MonadIO m, MonadResource m, Store a)

=> Maybe Int

Initial length of the ByteBuffer used for buffering the incoming ByteStrings. If Nothing, use the default value of 4MB.

-> Conduit ByteString m (Message a)

Conduit for decoding Messages from ByteStrings.