Capnp_rpc_lwt.Capability
A capability is a reference to an object, or to a promise for an object. You can invoke methods on a capability even while it is still only a promise.
val broken : Capnp_rpc.Exception.t -> 'a t
broken ex
is a broken capability, with problem ex
. Any attempt to call methods on it will fail with ex
.
val when_broken : (Capnp_rpc.Exception.t -> unit) -> 'a t -> unit
when_broken fn x
calls fn problem
when x
becomes broken. If x
is already broken, fn
is called immediately. If x
can never become broken (e.g. it is a near ref), this does nothing. If x
's ref-count reaches zero without fn
being called, it will never be called.
val when_released : 'a t -> (unit -> unit) -> unit
when_released t fn
will call fn ()
when t
's ref-count drops to zero. This is used for caches, to remove entries when they become invalid. For promises, fn
will be transferred to the resolution if resolved. For broken caps, this method does nothing (exceptions are never released).
val problem : 'a t -> Capnp_rpc.Exception.t option
problem t
is Some ex
if t
is broken, or None
if it is still believed to be healthy. Once a capability is broken, it will never work again and any calls made on it will fail with exception ex
.
val await_settled : 'a t -> (unit, Capnp_rpc.Exception.t) Lwt_result.t
await_settled t
resolves once t
is a "settled" (non-promise) reference. If t
is a near, far or broken reference, this returns immediately. If it is currently a local or remote promise, it waits until it isn't. wait_until_settled
takes ownership of t
until it returns (you must not dec_ref
it before then).
val await_settled_exn : 'a t -> unit Lwt.t
Like await_settled
, but raises an exception on error.
val wait_until_settled : 'a t -> unit Lwt.t
equal a b
indicates whether a
and b
designate the same settled service. Returns Error `Unsettled
if a
or b
is still a promise (and they therefore may yet turn out to be equal when the promise resolves).
module Request : sig ... end
val call :
't t ->
('t, 'a, 'b) Capnp.RPC.MethodID.t ->
'a Request.t ->
'b StructRef.t
call target m req
invokes target#m req
and returns a promise for the result. Messages may be sent to the capabilities that will be in the result before the result arrives - they will be pipelined to the service responsible for resolving the promise. The caller must call StructRef.dec_ref
when finished with the result (consider using one of the call_*
functions below instead for a simpler interface).
val call_and_wait :
't t ->
('t, 'a, 'b StructStorage.reader_t) Capnp.RPC.MethodID.t ->
'a Request.t ->
('b StructStorage.reader_t * (unit -> unit),
[> `Capnp of Capnp_rpc.Error.t ])
Lwt_result.t
call_and_wait t m req
does call t m req
and waits for the response. This is simpler than using call
, but doesn't support pipelining (you can't use any capabilities in the response in another message until the response arrives). On success, it returns Ok (response, release_response_caps)
. Call release_response_caps
when done with the results, to release any capabilities it might contain that you didn't use (remembering that future versions of the protocol might add new optional capabilities you don't know about yet). If you don't need any capabilities from the result, consider using call_for_value
instead. Doing Lwt.cancel
on the result will send a cancel message to the target for remote calls.
val call_for_value :
't t ->
('t, 'a, 'b StructStorage.reader_t) Capnp.RPC.MethodID.t ->
'a Request.t ->
('b StructStorage.reader_t, [> `Capnp of Capnp_rpc.Error.t ]) Lwt_result.t
call_for_value t m req
is similar to call_and_wait
, but automatically releases any capabilities in the response before returning. Use this if you aren't expecting any capabilities in the response.
val call_for_value_exn :
't t ->
('t, 'a, 'b StructStorage.reader_t) Capnp.RPC.MethodID.t ->
'a Request.t ->
'b StructStorage.reader_t Lwt.t
Wrapper for call_for_value
that turns errors into Lwt failures.
val call_for_unit :
't t ->
('t, 'a, 'b StructStorage.reader_t) Capnp.RPC.MethodID.t ->
'a Request.t ->
(unit, [> `Capnp of Capnp_rpc.Error.t ]) Lwt_result.t
Wrapper for call_for_value
that ignores the result.
val call_for_unit_exn :
't t ->
('t, 'a, 'b StructStorage.reader_t) Capnp.RPC.MethodID.t ->
'a Request.t ->
unit Lwt.t
Wrapper for call_for_unit
that turns errors into Lwt failures.
val call_for_caps :
't t ->
('t, 'a, 'b StructStorage.reader_t) Capnp.RPC.MethodID.t ->
'a Request.t ->
('b StructRef.t -> 'c) ->
'c
call_for_caps target m req extract
is a wrapper for call
that passes the results promise to extract
, which should extract any required capability promises from it. In the common case where you want a single cap "foo" from the result, use call_for_caps target m req Results.foo_get_pipelined
. When the remote call finally returns, the result will be released automatically.
An 'a resolver
can be used to resolve a promise for an 'a
. It can only be used once.
promise ()
returns a fresh local promise and a resolver for it. Any calls made on the promise will be queued until it is resolved.
resolve_ok r x
resolves r
's promise to x
. r
takes ownership of x
(the caller must use inc_ref
first if they want to continue using it).
val resolve_exn : 'a resolver -> Capnp_rpc.Exception.t -> unit
resolve_exn r x
breaks r
's promise with exception x
.
val inc_ref : _ t -> unit
inc_ref t
increases the ref-count on t
by one.
val dec_ref : _ t -> unit
dec_ref t
decreases the ref-count on t
by one. When the count reaches zero, the capability is released. This may involve sending a notification to a remote peer. Any time you extract a capability from a struct or struct promise, it must eventually be freed by calling dec_ref
on it.
with_ref t fn
runs fn t
and then calls dec_ref t
(whether fn
succeeds or not).
val pp : 'a t Fmt.t