To focus the search input from anywhere on the page, press the 'S' key.
in-package search v0.1.0
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
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
wait_until_settled x resolves once
x is a "settled" (non-promise) reference. If
x 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
x until it returns (you must not
dec_ref it before then).
equal a b indicates whether
b designate the same settled service. Returns
Error `Unsettled if
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
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
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
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.
'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
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
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).