capnp-rpc-lwt 0.9.0 · OCaml Package

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.

type +'a t

An 'a t is a capability reference to a service of type 'a.

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 wait_until_settled : 'a t -> unit Lwt.t

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

val equal : 'a t -> 'a t -> (bool, [ `Unsettled ]) result

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.

type 'a resolver

An 'a resolver can be used to resolve a promise for an 'a. It can only be used once.

val promise : unit -> 'a t * 'a resolver

promise () returns a fresh local promise and a resolver for it. Any calls made on the promise will be queued until it is resolved.

val resolve_ok : 'a resolver -> 'a t -> unit

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.

val with_ref : 'a t -> ('a t -> 'b Lwt.t) -> 'b Lwt.t

with_ref t fn runs fn t and then calls dec_ref t (whether fn succeeds or not).

val pp : 'a t Fmt.t

package capnp-rpc-lwt