| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Data.Capnp
Contents
Description
This module re-exports the most commonly used functionality from the low-level API. See also Data.Capnp.Pure, which similarly re-exports functionality from the high-level API.
Users getting acquainted with the library are *strongly* encouraged to read the Data.Capnp.Tutorial module before anything else.
Synopsis
- class ListElem msg e where
- data List msg e
- class ListElem (MutMsg s) e => MutListElem s e where
- data Data msg
- dataBytes :: ReadCtx m msg => Data msg -> m ByteString
- data Text msg
- textBytes :: ReadCtx m msg => Text msg -> m ByteString
- data ConstMsg
- class Monad m => Message m msg where
- data Segment msg
- data MutMsg s
- newMessage :: WriteCtx m s => m (MutMsg s)
- decodeMessage :: MonadThrow m => ByteString -> m ConstMsg
- encodeMessage :: MonadThrow m => ConstMsg -> m Builder
- hPutMsg :: Handle -> ConstMsg -> IO ()
- putMsg :: ConstMsg -> IO ()
- hGetMsg :: Handle -> Int -> IO ConstMsg
- getMsg :: Int -> IO ConstMsg
- getRoot :: (FromStruct msg a, ReadCtx m msg) => msg -> m a
- newRoot :: (ToStruct (MutMsg s) a, Allocate s a, WriteCtx m s) => MutMsg s -> m a
- setRoot :: (ToStruct (MutMsg s) a, WriteCtx m s) => a -> m ()
- hGetValue :: FromStruct ConstMsg a => Handle -> Int -> IO a
- getValue :: FromStruct ConstMsg a => Int -> IO a
- type WriteCtx m s = (PrimMonad m, s ~ PrimState m, MonadThrow m)
- type ReadCtx m msg = (Message m msg, MonadThrow m, MonadLimit m)
- type RWCtx m s = (ReadCtx m (MutMsg s), WriteCtx m s)
- module Data.Capnp.TraversalLimit
- module Data.Mutable
- data PureBuilder s a
- createPure :: Thaw a => Int -> (forall s. PureBuilder s (Mutable s a)) -> Either SomeException a
Working with capnproto lists
class ListElem msg e where Source #
Types which may be stored as an element of a capnproto list.
Methods
length :: List msg e -> Int Source #
Get the length of a list.
index :: ReadCtx m msg => Int -> List msg e -> m e Source #
index i listith element of a list.
Instances
class ListElem (MutMsg s) e => MutListElem s e where Source #
Types which may be stored as an element of a *mutable* capnproto list.
Methods
setIndex :: RWCtx m s => e -> Int -> List (MutMsg s) e -> m () Source #
setIndex value i listith index in list to @value
newList :: WriteCtx m s => MutMsg s -> Int -> m (List (MutMsg s) e) Source #
newList msg sizesize inside msg.
Instances
Working with capnproto Text and Data values.
A blob of bytes (Data in capnproto's schema language). The argument
to the data constructor is a slice into the message, containing the raw
bytes.
dataBytes :: ReadCtx m msg => Data msg -> m ByteString Source #
Convert a Data to a ByteString.
A textual string (Text in capnproto's schema language). On the wire,
this is NUL-terminated. The encoding should be UTF-8, but the library
does not verify this; users of the library must do validation themselves, if
they care about this.
Rationale: validation would require doing an up-front pass over the data, which runs counter to the overall design of capnproto.
textBytes :: ReadCtx m msg => Text msg -> m ByteString Source #
Convert a Text to a ByteString, comprising the raw bytes of the text
(not counting the NUL terminator).
Working with messages
A read-only capnproto message.
ConstMsg is an instance of the generic Message type class. its
implementations of toByteString and fromByteString are O(1);
the underlying bytes are not copied.
Instances
class Monad m => Message m msg where Source #
A Message is a (possibly read-only) capnproto message. It is
parameterized over a monad in which operations are performed.
Minimal complete definition
numSegs, internalGetSeg, numWords, slice, read, fromByteString, toByteString
Methods
numSegs :: msg -> m Int Source #
numSegs gets the number of segments in a message.
internalGetSeg :: msg -> Int -> m (Segment msg) Source #
internalGetSeg message indexindex
in message. Most callers should use the getSegment wrapper, instead
of calling this directly.
numWords :: Segment msg -> m Int Source #
Get the length of the segment, in units of 64-bit words.
slice :: Int -> Int -> Segment msg -> m (Segment msg) Source #
slice start length segmentstart, of length length.
read :: Segment msg -> Int -> m Word64 Source #
read segment indexgetWord on the message, instead of
calling this directly.
fromByteString :: ByteString -> m (Segment msg) Source #
Convert a ByteString to a segment.
toByteString :: Segment msg -> m ByteString Source #
Convert a segment to a byte string.
Instances
| Monad m => Message m ConstMsg Source # | |
Defined in Data.Capnp.Message Methods numSegs :: ConstMsg -> m Int Source # internalGetSeg :: ConstMsg -> Int -> m (Segment ConstMsg) Source # numWords :: Segment ConstMsg -> m Int Source # slice :: Int -> Int -> Segment ConstMsg -> m (Segment ConstMsg) Source # read :: Segment ConstMsg -> Int -> m Word64 Source # fromByteString :: ByteString -> m (Segment ConstMsg) Source # toByteString :: Segment ConstMsg -> m ByteString Source # | |
| (PrimMonad m, s ~ PrimState m) => Message m (MutMsg s) Source # | |
Defined in Data.Capnp.Message Methods numSegs :: MutMsg s -> m Int Source # internalGetSeg :: MutMsg s -> Int -> m (Segment (MutMsg s)) Source # numWords :: Segment (MutMsg s) -> m Int Source # slice :: Int -> Int -> Segment (MutMsg s) -> m (Segment (MutMsg s)) Source # read :: Segment (MutMsg s) -> Int -> m Word64 Source # fromByteString :: ByteString -> m (Segment (MutMsg s)) Source # toByteString :: Segment (MutMsg s) -> m ByteString Source # | |
A MutMsg is a mutable capnproto message. The type parameter s is the
state token for the instance of PrimMonad in which the message may be
modified.
Due to mutabilty, the implementations of toByteString and fromByteString
must make full copies, and so are O(n) in the length of the segment.
Instances
newMessage :: WriteCtx m s => m (MutMsg s) Source #
Allocate a new empty message.
decodeMessage :: MonadThrow m => ByteString -> m ConstMsg Source #
Alias for decode
encodeMessage :: MonadThrow m => ConstMsg -> m Builder Source #
Alias for encode
Reading and writing messages
hGetMsg :: Handle -> Int -> IO ConstMsg Source #
hGetMsg handle limithandle that is at most
limit 64-bit words in length.
Manipulating the root object of a message
getRoot :: (FromStruct msg a, ReadCtx m msg) => msg -> m a Source #
getRoot returns the root object of a message.
newRoot :: (ToStruct (MutMsg s) a, Allocate s a, WriteCtx m s) => MutMsg s -> m a Source #
newRoot allocates and returns a new value inside the message, setting
it as the root object of the message.
setRoot :: (ToStruct (MutMsg s) a, WriteCtx m s) => a -> m () Source #
setRoot sets its argument to be the root object in its message.
Reading values
hGetValue :: FromStruct ConstMsg a => Handle -> Int -> IO a Source #
hGetValue limit handlehandle, returning its root object.
limit is used as both a cap on the size of a message which may be read and, for types
in the high-level API, the traversal limit when decoding the message.
It may throw a Error if there is a problem decoding the message,
or an IOError raised by the underlying IO libraries.
Type aliases for common contexts
type WriteCtx m s = (PrimMonad m, s ~ PrimState m, MonadThrow m) Source #
WriteCtx is the context needed for most write operations.
type ReadCtx m msg = (Message m msg, MonadThrow m, MonadLimit m) Source #
Type (constraint) synonym for the constraints needed for most read operations.
Managing resource limits
module Data.Capnp.TraversalLimit
Freezing and thawing values
module Data.Mutable
Building messages in pure code
data PureBuilder s a Source #
PureBuilder is a monad transformer stack with the instnaces needed
manipulate mutable messages. PureBuilder s a'LimitT (CatchT (ST s)) a
Instances
createPure :: Thaw a => Int -> (forall s. PureBuilder s (Mutable s a)) -> Either SomeException a Source #
createPure limit mm, then freezes it without copying. If m calls throwM then
createPure returns a Left with the exception.