capnp-rpc-lwt 0.1 · 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 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.

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)) or_error Lwt.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 or_error Lwt.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 or_error Lwt.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 -> 't 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 pp : 'a t Fmt.t

package capnp-rpc-lwt