package capnp-rpc-lwt

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

broken ex is a broken capability, with problem ex. Any attempt to call methods on it will fail with ex.

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.

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.

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

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

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.

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.

Wrapper for call_for_value that turns errors into Lwt failures.

Wrapper for call_for_value that ignores the result.

Wrapper for call_for_unit that turns errors into Lwt failures.

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

resolve_exn r x breaks r's promise with exception x.

inc_ref t increases the ref-count on t by one.

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