Capnp.Rpc.Untyped

This module does not deal with schema-level concepts; all capabilities, methods etc. as used here are untyped.

Connections to other vats

data ConnConfig

Configuration information for a connection.

Constructors

ConnConfig

Fields

• maxQuestions :: !Word32

  The maximum number of simultanious outstanding requests to the peer vat. Once this limit is reached, further questsions will block until some of the existing questions have been answered.

  Defaults to 128.

• maxExports :: !Word32

  The maximum number of objects which may be exported on this connection.

  Defaults to 8192.

• maxCallWords :: !WordCount

  The maximum total size of outstanding call messages that will be accepted; if this limit is reached, the implementation will not read more messages from the connection until some calls have completed and freed up enough space.

  Defaults to 32MiB in words.

• debugMode :: !Bool

  In debug mode, errors reported by the RPC system to its peers will contain extra information. This should not be used in production, as it is possible for these messages to contain sensitive information, but it can be useful for debugging.

  Defaults to False.

• getBootstrap :: Supervisor -> STM (Maybe Client)

  Get the bootstrap interface we should serve for this connection. the argument is a supervisor whose lifetime is bound to the connection. If $sel:getBootstrap:ConnConfig returns Nothing, we will respond to bootstrap messages with an exception.

  The default always returns Nothing.

  $sel:getBootstrap:ConnConfig MUST NOT block; the connection will not be serviced and $sel:withBootstrap:ConnConfig will not be run until this returns. If you need to supply the bootstrap interface later, use newPromiseClient.

• withBootstrap :: Maybe (Supervisor -> Client -> IO ())

  An action to perform with access to the remote vat's bootstrap interface. The supervisor argument is bound to the lifetime of the connection. If this is Nothing (the default), the bootstrap interface will not be requested.

Instances

Default ConnConfig

Defined in Capnp.Rpc.Untyped

Methods

def :: ConnConfig

handleConn :: Transport -> ConnConfig -> IO ()

Handle a connection to another vat. Returns when the connection is closed.

Clients for capabilities

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

call :: MonadSTM m => CallInfo -> Client -> m (Promise Pipeline)

Queue a call on a client.

nullClient :: Client

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

newPromiseClient :: (MonadSTM m, IsClient c) => m (c, Fulfiller c)

Create a new client based on a promise. The fulfiller can be used to supply the final client.

class IsClient a where

Types which may be converted to and from Clients. Typically these will be simple type wrappers for capabilities.

Methods

toClient :: a -> Client

Convert a value to a client.

fromClient :: Client -> a

Convert a client to a value.

Instances

IsClient Client

Defined in Capnp.Rpc.Untyped

Methods

toClient :: Client -> Client

fromClient :: Client -> Client

ReprFor a ~ 'Ptr ('Just 'Cap) => IsClient (Client a)

Defined in Capnp.Repr.Methods

Methods

toClient :: Client a -> Client0

fromClient :: Client0 -> Client a

Promise pipelining

data Pipeline

A Pipeline is a reference to a value within a message that has not yet arrived.

walkPipelinePtr :: Pipeline -> Word16 -> Pipeline

walkPipleinePtr follows a pointer starting from the object referred to by the Pipeline. The Pipeline must refer to a struct, and the pointer is referred to by its index into the struct's pointer section.

pipelineClient :: MonadSTM m => Pipeline -> m Client

Convert a Pipeline into a Client, which can be used to send messages to the referant of the Pipeline, using promise pipelining.

waitPipeline :: MonadSTM m => Pipeline -> m RawMPtr

Wait for the pipeline's target to resolve, and return the corresponding pointer.

Exporting local objects

export :: MonadSTM m => Supervisor -> ServerOps -> m Client

Spawn a local server with its lifetime bound to the supervisor, and return a client for it. When the client is garbage collected, the server will be stopped (if it is still running).

clientMethodHandler :: Word64 -> Word16 -> Client -> MethodHandler p r

Unwrapping local clients

unwrapServer :: (IsClient c, Typeable a) => c -> Maybe a

Attempt to unwrap a client, to get at an underlying value from the server. Returns Nothing on failure.

This shells out to the underlying server's implementation of unwrap. It will fail with Nothing if any of these are true:

• The client is a promise.
• The client points to an object in a remote vat.
• The underlying Server's unwrap method returns Nothing for type a.

Waiting for resolution

waitClient :: (IsClient c, MonadSTM m) => c -> m c

Wait for the client to be fully resolved, and then return a client pointing directly to the destination.

If the argument is null, a local client, or a (permanent) remote client, this returns the argument immediately. If the argument is a promise client, then this waits for the promise to resolve and returns the result of the resolution. If the promise resolves to *another* promise, then this waits for that promise to also resolve.

If the promise is rejected, then this throws the corresponding exception.

Errors

data RpcError

Errors which can be thrown by the rpc system.

Constructors

ReceivedAbort (Parsed Exception)

The remote vat sent us an abort message.

SentAbort (Parsed Exception)

We sent an abort to the remote vat.

Instances

Exception RpcError

Defined in Capnp.Rpc.Untyped

Methods

toException :: RpcError -> SomeException

fromException :: SomeException -> Maybe RpcError

displayException :: RpcError -> String

Generic RpcError

Defined in Capnp.Rpc.Untyped

Associated Types

type Rep RpcError :: Type -> Type

Methods

from :: RpcError -> Rep RpcError x

to :: Rep RpcError x -> RpcError

Show RpcError

Defined in Capnp.Rpc.Untyped

Methods

showsPrec :: Int -> RpcError -> ShowS

show :: RpcError -> String

showList :: [RpcError] -> ShowS

Eq RpcError

Defined in Capnp.Rpc.Untyped

Methods

(==) :: RpcError -> RpcError -> Bool

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

type Rep RpcError

Defined in Capnp.Rpc.Untyped

type Rep RpcError = D1 ('MetaData "RpcError" "Capnp.Rpc.Untyped" "capnp-0.17.0.0-KnW61yXmCDxBdeB4uIxK8L" 'False) (C1 ('MetaCons "ReceivedAbort" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Parsed Exception))) :+: C1 ('MetaCons "SentAbort" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Parsed Exception))))

Shutting down the connection