capnp-0.17.0.0: Cap'n Proto for Haskell
Safe HaskellSafe-Inferred
LanguageHaskell2010

Capnp.Message

Description

This module provides support for working directly with Cap'N Proto messages.

Synopsis

Documentation

data family Message (mut :: Mutability) Source #

A Cap'n Proto message, parametrized over its mutability.

Instances

Instances details
MaybeMutable Message Source # 
Instance details

Defined in Capnp.Message

Methods

thaw :: (PrimMonad m, PrimState m ~ s) => Message 'Const -> m (Message ('Mut s)) Source #

freeze :: (PrimMonad m, PrimState m ~ s) => Message ('Mut s) -> m (Message 'Const) Source #

unsafeThaw :: (PrimMonad m, PrimState m ~ s) => Message 'Const -> m (Message ('Mut s)) Source #

unsafeFreeze :: (PrimMonad m, PrimState m ~ s) => Message ('Mut s) -> m (Message 'Const) Source #

Eq (Message 'Const) Source # 
Instance details

Defined in Capnp.Message

Eq (Message ('Mut s)) Source # 
Instance details

Defined in Capnp.Message

Methods

(==) :: Message ('Mut s) -> Message ('Mut s) -> Bool #

(/=) :: Message ('Mut s) -> Message ('Mut s) -> Bool #

newtype Message 'Const Source # 
Instance details

Defined in Capnp.Message

newtype Message 'Const = MsgConst ConstMsg
newtype Message ('Mut s) Source # 
Instance details

Defined in Capnp.Message

newtype Message ('Mut s) = MsgMut (MutMsg s)

data family Segment (mut :: Mutability) Source #

A segment in a Cap'n Proto message.

Instances

Instances details
MaybeMutable Segment Source # 
Instance details

Defined in Capnp.Message

Methods

thaw :: (PrimMonad m, PrimState m ~ s) => Segment 'Const -> m (Segment ('Mut s)) Source #

freeze :: (PrimMonad m, PrimState m ~ s) => Segment ('Mut s) -> m (Segment 'Const) Source #

unsafeThaw :: (PrimMonad m, PrimState m ~ s) => Segment 'Const -> m (Segment ('Mut s)) Source #

unsafeFreeze :: (PrimMonad m, PrimState m ~ s) => Segment ('Mut s) -> m (Segment 'Const) Source #

Eq (Segment 'Const) Source # 
Instance details

Defined in Capnp.Message

Eq (Segment ('Mut s)) Source # 
Instance details

Defined in Capnp.Message

Methods

(==) :: Segment ('Mut s) -> Segment ('Mut s) -> Bool #

(/=) :: Segment ('Mut s) -> Segment ('Mut s) -> Bool #

newtype Segment 'Const Source # 
Instance details

Defined in Capnp.Message

newtype Segment 'Const = SegConst ConstSegment
newtype Segment ('Mut s) Source # 
Instance details

Defined in Capnp.Message

newtype Segment ('Mut s) = SegMut (MutSegment s)

data Mutability Source #

Mutability is used as a type parameter (with the DataKinds extension) to indicate the mutability of some values in this library; Const denotes an immutable value, while Mut s denotes a value that can be mutated in the scope of the state token s.

Constructors

Const 
Mut Type 

Reading and writing messages

hPutMsg :: Handle -> Message 'Const -> IO () Source #

hPutMsg handle msg writes msg to handle. If there is an exception, it will be an IOError raised by the underlying IO libraries.

hGetMsg :: Handle -> WordCount -> IO (Message 'Const) Source #

hGetMsg handle limit reads a message from handle that is at most limit 64-bit words in length.

putMsg :: Message 'Const -> IO () Source #

Equivalent to hPutMsg stdout

readMessage :: (MonadThrow m, MonadLimit m) => m Word32 -> (WordCount -> m (Segment 'Const)) -> m (Message 'Const) Source #

readMessage read32 readSegment reads in a message using the monadic context, which should manage the current read position, into a message. read32 should read a 32-bit little-endian integer, and readSegment n should read a blob of n 64-bit words. The size of the message (in 64-bit words) is deducted from the traversal, limit which can be used to set the maximum message size.

writeMessage :: MonadThrow m => Message 'Const -> (Word32 -> m ()) -> (Segment 'Const -> m ()) -> m () Source #

writeMesage write32 writeSegment writes out the message. write32 should write a 32-bit word in little-endian format to the output stream. writeSegment should write a blob.

Limits on message size

maxSegmentSize :: WordCount Source #

The maximum size of a segment supported by this libarary, in words.

maxSegments :: Int Source #

The maximum number of segments allowed in a message by this library.

maxCaps :: Int Source #

The maximum number of capabilities allowed in a message by this library.

Converting between messages and ByteStrings

encode :: Message 'Const -> Builder Source #

encode encodes a message as a bytestring builder.

decode :: MonadThrow m => ByteString -> m (Message 'Const) Source #

decode decodes a message from a bytestring.

The segments will not be copied; the resulting message will be a view into the original bytestring. Runs in O(number of segments in the message).

toByteString :: Segment 'Const -> ByteString Source #

Convert a segment to a byte string. O(1)

fromByteString :: ByteString -> Segment 'Const Source #

Convert a ByteString to a segment. O(1)

Accessing underlying storage

segToVecMut :: (PrimMonad m, PrimState m ~ s) => Segment ('Mut s) -> m (MVector s Word64) Source #

Return the underlying storage of a mutable segment, as a vector.

Note that the elements of the vector will be stored in little-endian form, regardless of CPU endianness. This is a low level function that you should probably not use.

Immutable messages

empty :: Message 'Const Source #

empty is an empty message, i.e. a minimal message with a null pointer as its root object.

singleSegment :: Segment 'Const -> Message 'Const Source #

Create a message from a single segment.

Reading data from messages

class Monad m => MonadReadMessage mut m where Source #

A Message is a (possibly read-only) capnproto message. It is parameterized over a monad in which operations are performed.

Methods

numSegs :: Message mut -> m Int Source #

numSegs gets the number of segments in a message.

numWords :: Segment mut -> m WordCount Source #

numWords gets the number of words in a segment.

numCaps :: Message mut -> m Int Source #

numCaps gets the number of capabilities in a message's capability table.

getSegment :: Message mut -> Int -> m (Segment mut) Source #

getSegment message index gets the segment at index index in message.

internalGetCap :: Message mut -> Int -> m Client Source #

internalGetCap cap index reads a capability from the message's capability table, returning the client. does not check bounds. Callers should use getCap instead.

slice :: WordCount -> WordCount -> Segment mut -> m (Segment mut) Source #

slice start length segment extracts a sub-section of the segment, starting at index start, of length length.

read :: Segment mut -> WordCount -> m Word64 Source #

read segment index reads a 64-bit word from the segement at the given index. Consider using getWord on the message, instead of calling this directly.

Instances

Instances details
Monad m => MonadReadMessage 'Const m Source # 
Instance details

Defined in Capnp.Message

(PrimMonad m, s ~ PrimState m) => MonadReadMessage ('Mut s) m Source # 
Instance details

Defined in Capnp.Message

getCap :: (MonadThrow m, MonadReadMessage mut m) => Message mut -> Int -> m Client Source #

getCap message index gets the capability with the given index from the message. throws BoundsError if the index is out of bounds.

getCapTable :: Message 'Const -> Vector Client Source #

getCapTable gets the capability table from a ConstMsg.

getWord :: MonadReadMessage mut m => WordPtr mut -> m Word64 Source #

getWord gets the word referred to by the WordPtr

totalNumWords :: MonadReadMessage mut m => Message mut -> m WordCount Source #

Return the total number of words in the message, i.e. the sum of the results of numWords on all segments.

Mutable Messages

newMessage :: WriteCtx m s => Maybe WordCount -> m (Message ('Mut s)) Source #

newMessage sizeHint allocates a new empty message, with a single segment having capacity sizeHint. If sizeHint is Nothing, defaults to a sensible value.

Allocating space in messages

data WordPtr mut Source #

A pointer to a location in a message. This encodes the same information as a WordAddr, but also includes direct references to the segment and message, which can improve performance in very low-level code.

Constructors

WordPtr 

Fields

Instances

Instances details
HasMessage WordPtr Source # 
Instance details

Defined in Capnp.Untyped

Methods

message :: forall (mut :: Mutability). Unwrapped (WordPtr mut) -> Message mut Source #

TraverseMsg WordPtr Source # 
Instance details

Defined in Capnp.Untyped

Methods

tMsg :: forall m (mutA :: Mutability) (mutB :: Mutability). TraverseMsgCtx m mutA mutB => (Message mutA -> m (Message mutB)) -> WordPtr mutA -> m (WordPtr mutB) Source #

alloc :: WriteCtx m s => Message ('Mut s) -> WordCount -> m (WordPtr ('Mut s)) Source #

alloc size allocates size words within a message. it returns the starting address of the allocated memory, as well as a direct reference to the segment. The latter is redundant information, but this is used in low-level code where this can improve performance.

allocInSeg :: WriteCtx m s => Message ('Mut s) -> Int -> WordCount -> m (Maybe (WordPtr ('Mut s))) Source #

Like alloc, but the second argument allows the caller to specify the index of the segment in which to allocate the data. Returns Nothing if there is insufficient space in that segment..

newSegment :: WriteCtx m s => Message ('Mut s) -> WordCount -> m (Int, Segment ('Mut s)) Source #

newSegment msg sizeHint allocates a new, initially empty segment in msg with a capacity of sizeHint words. It returns the a pair of the segment number and the segment itself. Amortized O(1).

Modifying messages

setSegment :: WriteCtx m s => Message ('Mut s) -> Int -> Segment ('Mut s) -> m () Source #

setSegment message index segment sets the segment at the given index in the message.

write :: WriteCtx m s => Segment ('Mut s) -> WordCount -> Word64 -> m () Source #

write segment index value writes a value to the 64-bit word at the provided index. Consider using setWord on the message, instead of calling this directly.

setCap :: WriteCtx m s => Message ('Mut s) -> Int -> Client -> m () Source #

setCap message index cap sets the sets the capability at index in the message's capability table to cap. If the index is out of bounds, a BoundsError will be thrown.

appendCap :: WriteCtx m s => Message ('Mut s) -> Client -> m Int Source #

appendCap appends a new capabilty to the end of a message's capability table, returning its index.

type WriteCtx m s = (PrimMonad m, s ~ PrimState m, MonadThrow m) Source #

WriteCtx is the context needed for most write operations.

data Client Source #

A reference to a capability, which may be live either in the current vat or elsewhere. Holding a client affords making method calls on a capability or modifying the local vat's reference count to it.

Instances

Instances details
Show Client Source # 
Instance details

Defined in Internal.Rpc.Breaker

IsClient Client Source # 
Instance details

Defined in Capnp.Rpc.Untyped

Eq Client Source # 
Instance details

Defined in Internal.Rpc.Breaker

Methods

(==) :: Client -> Client -> Bool #

(/=) :: Client -> Client -> Bool #

Parse Capability Client Source # 
Instance details

Defined in Capnp.Basics

Methods

parse :: ReadCtx m 'Const => Raw Capability 'Const -> m Client Source #

encode :: RWCtx m s => Message ('Mut s) -> Client -> m (Raw Capability ('Mut s)) Source #

nullClient :: Client Source #

A null client. This is the only client value that can be represented statically. Throws exceptions in response to all method calls.

withCapTable :: Vector Client -> Message 'Const -> Message 'Const Source #

withCapTable replaces the capability table in the message.