Capnp.Message

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

Documentation

data family Message (mut :: Mutability)

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

Instances

MaybeMutable Message

Defined in Capnp.Message

Methods

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

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

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

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

Eq (Message 'Const)

Defined in Capnp.Message

Methods

(==) :: Message 'Const -> Message 'Const -> Bool

(/=) :: Message 'Const -> Message 'Const -> Bool

Eq (Message ('Mut s))

Defined in Capnp.Message

Methods

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

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

newtype Message 'Const

Defined in Capnp.Message

newtype Message 'Const = MsgConst ConstMsg

newtype Message ('Mut s)

Defined in Capnp.Message

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

data family Segment (mut :: Mutability)

A segment in a Cap'n Proto message.

Instances

MaybeMutable Segment

Defined in Capnp.Message

Methods

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

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

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

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

Eq (Segment 'Const)

Defined in Capnp.Message

Methods

(==) :: Segment 'Const -> Segment 'Const -> Bool

(/=) :: Segment 'Const -> Segment 'Const -> Bool

Eq (Segment ('Mut s))

Defined in Capnp.Message

Methods

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

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

newtype Segment 'Const

Defined in Capnp.Message

newtype Segment 'Const = SegConst ConstSegment

newtype Segment ('Mut s)

Defined in Capnp.Message

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

data Mutability

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 ()

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)

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

putMsg :: Message 'Const -> IO ()

Equivalent to hPutMsg stdout

getMsg :: WordCount -> IO (Message 'Const)

Equivalent to hGetMsg stdin

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

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 ()

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

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

maxSegments :: Int

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

maxCaps :: Int

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

Converting between messages and ByteStrings

encode :: Message 'Const -> Builder

encode encodes a message as a bytestring builder.

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

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

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

fromByteString :: ByteString -> Segment 'Const

Convert a ByteString to a segment. O(1)

Accessing underlying storage

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

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

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

singleSegment :: Segment 'Const -> Message 'Const

Create a message from a single segment.

Reading data from messages

class Monad m => MonadReadMessage mut m where

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

numSegs gets the number of segments in a message.

numWords :: Segment mut -> m WordCount

numWords gets the number of words in a segment.

numCaps :: Message mut -> m Int

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

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

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

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

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)

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

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

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

Monad m => MonadReadMessage 'Const m

Defined in Capnp.Message

Methods

numSegs :: Message 'Const -> m Int

numWords :: Segment 'Const -> m WordCount

numCaps :: Message 'Const -> m Int

getSegment :: Message 'Const -> Int -> m (Segment 'Const)

internalGetCap :: Message 'Const -> Int -> m Client

slice :: WordCount -> WordCount -> Segment 'Const -> m (Segment 'Const)

read :: Segment 'Const -> WordCount -> m Word64

(PrimMonad m, s ~ PrimState m) => MonadReadMessage ('Mut s) m

Defined in Capnp.Message

Methods

numSegs :: Message ('Mut s) -> m Int

numWords :: Segment ('Mut s) -> m WordCount

numCaps :: Message ('Mut s) -> m Int

getSegment :: Message ('Mut s) -> Int -> m (Segment ('Mut s))

internalGetCap :: Message ('Mut s) -> Int -> m Client

slice :: WordCount -> WordCount -> Segment ('Mut s) -> m (Segment ('Mut s))

read :: Segment ('Mut s) -> WordCount -> m Word64

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

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

getCapTable gets the capability table from a ConstMsg.

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

getWord gets the word referred to by the WordPtr

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

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))

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

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

• pMessage :: !(Message mut)
• pSegment :: !(Segment mut)
• pAddr :: !WordAddr

Instances

HasMessage WordPtr

Defined in Capnp.Untyped

Methods

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

TraverseMsg WordPtr

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)

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

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)))

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))

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 ()

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

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

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 ()

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

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)

WriteCtx is the context needed for most write operations.

data Client

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

Show Client

Defined in Internal.Rpc.Breaker

Methods

showsPrec :: Int -> Client -> ShowS

show :: Client -> String

showList :: [Client] -> ShowS

IsClient Client

Defined in Capnp.Rpc.Untyped

Methods

toClient :: Client -> Client

fromClient :: Client -> Client

Eq Client

Defined in Internal.Rpc.Breaker

Methods

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

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

Parse Capability Client

Defined in Capnp.Basics

Methods

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

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

nullClient :: Client

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

withCapTable replaces the capability table in the message.