Files

33 lines
21 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>Capability (capnp-rpc.Capnp_rpc.Capability)</title><meta charset="utf-8"/><link rel="stylesheet" href="../../../odoc.support/odoc.css"/><meta name="generator" content="odoc 2.4.4"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="../../../odoc.support/highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="../index.html">Up</a> – <a href="../../index.html">capnp-rpc</a> &#x00BB; <a href="../index.html">Capnp_rpc</a> &#x00BB; Capability</nav><header class="odoc-preamble"><h1>Module <code><span>Capnp_rpc.Capability</span></code></h1><p>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.</p></header><div class="odoc-content"><div class="odoc-spec"><div class="spec type anchored" id="type-t"><a href="#type-t" class="anchor"></a><code><span><span class="keyword">type</span> <span>+'a t</span></span></code></div><div class="spec-doc"><p>An <code>'a t</code> is a capability reference to a service of type <code>'a</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-broken"><a href="#val-broken" class="anchor"></a><code><span><span class="keyword">val</span> broken : <span><a href="../../Capnp_rpc_proto/Exception/index.html#type-t">Exception.t</a> <span class="arrow">&#45;&gt;</span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span></span></code></div><div class="spec-doc"><p><code>broken ex</code> is a broken capability, with problem <code>ex</code>. Any attempt to call methods on it will fail with <code>ex</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-when_broken"><a href="#val-when_broken" class="anchor"></a><code><span><span class="keyword">val</span> when_broken : <span><span>(<span><a href="../../Capnp_rpc_proto/Exception/index.html#type-t">Exception.t</a> <span class="arrow">&#45;&gt;</span></span> unit)</span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div><div class="spec-doc"><p><code>when_broken fn x</code> calls <code>fn problem</code> when <code>x</code> becomes broken. If <code>x</code> is already broken, <code>fn</code> is called immediately. If <code>x</code> can never become broken (e.g. it is a near ref), this does nothing. If <code>x</code>'s ref-count reaches zero without <code>fn</code> being called, it will never be called.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-when_released"><a href="#val-when_released" class="anchor"></a><code><span><span class="keyword">val</span> when_released : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> <span><span>(<span>unit <span class="arrow">&#45;&gt;</span></span> unit)</span> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div><div class="spec-doc"><p><code>when_released t fn</code> will call <code>fn ()</code> when <code>t</code>'s ref-count drops to zero. This is used for caches, to remove entries when they become invalid. For promises, <code>fn</code> will be transferred to the resolution if resolved. For broken caps, this method does nothing (exceptions are never released).</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-problem"><a href="#val-problem" class="anchor"></a><code><span><span class="keyword">val</span> problem : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> <span><a href="../../Capnp_rpc_proto/Exception/index.html#type-t">Exception.t</a> option</span></span></code></div><div class="spec-doc"><p><code>problem t</code> is <code>Some ex</code> if <code>t</code> is broken, or <code>None</code> 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 <code>ex</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-await_settled"><a href="#val-await_settled" class="anchor"></a><code><span><span class="keyword">val</span> await_settled : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> <span><span>(unit, <a href="../../Capnp_rpc_proto/Exception/index.html#type-t">Exception.t</a>)</span> <span class="xref-unresolved">Stdlib</span>.result</span></span></code></div><div class="spec-doc"><p><code>await_settled t</code> resolves once <code>t</code> is a &quot;settled&quot; (non-promise) reference. If <code>t</code> 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. <code>wait_until_settled</code> takes ownership of <code>t</code> until it returns (you must not <code>dec_ref</code> it before then).</p><ul class="at-tags"><li class="returns"><span class="at-tag">returns</span> <p><code>Ok ()</code> on success, or <code>Error _</code> if <code>t</code> failed.</p></li></ul><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 1.2</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-await_settled_exn"><a href="#val-await_settled_exn" class="anchor"></a><code><span><span class="keyword">val</span> await_settled_exn : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div><div class="spec-doc"><p>Like <code>await_settled</code>, but raises an exception on error.</p><ul class="at-tags"><li class="since"><span class="at-tag">since</span> 1.2</li></ul></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-equal"><a href="#val-equal" class="anchor"></a><code><span><span class="keyword">val</span> equal : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> <span><span>(bool, <span>[ `Unsettled ]</span>)</span> <span class="xref-unresolved">Stdlib</span>.result</span></span></code></div><div class="spec-doc"><p><code>equal a b</code> indicates whether <code>a</code> and <code>b</code> designate the same settled service. Returns <code>Error `Unsettled</code> if <code>a</code> or <code>b</code> is still a promise (and they therefore may yet turn out to be equal when the promise resolves).</p></div></div><div class="odoc-spec"><div class="spec module anchored" id="module-Request"><a href="#module-Request" class="anchor"></a><code><span><span class="keyword">module</span> <a href="Request/index.html">Request</a></span><span> : <span class="keyword">sig</span> ... <span class="keyword">end</span></span></code></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-call"><a href="#val-call" class="anchor"></a><code><span><span class="keyword">val</span> call :
<span><span><span class="type-var">'t</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span>
<span><span><span>(<span class="type-var">'t</span>, <span class="type-var">'a</span>, <span><span class="type-var">'b</span> <a href="../StructStorage/index.html#type-reader_t">StructStorage.reader_t</a></span>)</span> <span class="xref-unresolved">Capnp</span>.RPC.MethodID.t</span> <span class="arrow">&#45;&gt;</span></span>
<span><span><span class="type-var">'a</span> <a href="Request/index.html#type-t">Request.t</a></span> <span class="arrow">&#45;&gt;</span></span>
<span><span class="type-var">'b</span> <a href="../StructRef/index.html#type-t">StructRef.t</a></span></span></code></div><div class="spec-doc"><p><code>call target m req</code> invokes <code>target#m req</code> 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 <code>StructRef.dec_ref</code> when finished with the result (consider using one of the <code>call_*</code> functions below instead for a simpler interface).</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-call_and_wait"><a href="#val-call_and_wait" class="anchor"></a><code><span><span class="keyword">val</span> call_and_wait :
<span><span><span class="type-var">'t</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span>
<span><span><span>(<span class="type-var">'t</span>, <span class="type-var">'a</span>, <span><span class="type-var">'b</span> <a href="../StructStorage/index.html#type-reader_t">StructStorage.reader_t</a></span>)</span> <span class="xref-unresolved">Capnp</span>.RPC.MethodID.t</span> <span class="arrow">&#45;&gt;</span></span>
<span><span><span class="type-var">'a</span> <a href="Request/index.html#type-t">Request.t</a></span> <span class="arrow">&#45;&gt;</span></span>
<span><span>(<span><span class="type-var">'b</span> <a href="../StructStorage/index.html#type-reader_t">StructStorage.reader_t</a></span> * <span>(<span>unit <span class="arrow">&#45;&gt;</span></span> unit)</span>, <span>[&gt; <span>`Capnp of <a href="../../Capnp_rpc_proto/Error/index.html#type-t">Error.t</a></span> ]</span>)</span>
<span class="xref-unresolved">Stdlib</span>.result</span></span></code></div><div class="spec-doc"><p><code>call_and_wait t m req</code> does <code>call t m req</code> and waits for the response. This is simpler than using <code>call</code>, 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 <code>Ok (response, release_response_caps)</code>. Call <code>release_response_caps</code> 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 <code>call_for_value</code> instead. Cancelling the fiber will send a cancel message to the target for remote calls.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-call_for_value"><a href="#val-call_for_value" class="anchor"></a><code><span><span class="keyword">val</span> call_for_value :
<span><span><span class="type-var">'t</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span>
<span><span><span>(<span class="type-var">'t</span>, <span class="type-var">'a</span>, <span><span class="type-var">'b</span> <a href="../StructStorage/index.html#type-reader_t">StructStorage.reader_t</a></span>)</span> <span class="xref-unresolved">Capnp</span>.RPC.MethodID.t</span> <span class="arrow">&#45;&gt;</span></span>
<span><span><span class="type-var">'a</span> <a href="Request/index.html#type-t">Request.t</a></span> <span class="arrow">&#45;&gt;</span></span>
<span><span>(<span><span class="type-var">'b</span> <a href="../StructStorage/index.html#type-reader_t">StructStorage.reader_t</a></span>, <span>[&gt; <span>`Capnp of <a href="../../Capnp_rpc_proto/Error/index.html#type-t">Error.t</a></span> ]</span>)</span> <span class="xref-unresolved">Stdlib</span>.result</span></span></code></div><div class="spec-doc"><p><code>call_for_value t m req</code> is similar to <code>call_and_wait</code>, but automatically releases any capabilities in the response before returning. Use this if you aren't expecting any capabilities in the response.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-call_for_value_exn"><a href="#val-call_for_value_exn" class="anchor"></a><code><span><span class="keyword">val</span> call_for_value_exn :
<span><span><span class="type-var">'t</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span>
<span><span><span>(<span class="type-var">'t</span>, <span class="type-var">'a</span>, <span><span class="type-var">'b</span> <a href="../StructStorage/index.html#type-reader_t">StructStorage.reader_t</a></span>)</span> <span class="xref-unresolved">Capnp</span>.RPC.MethodID.t</span> <span class="arrow">&#45;&gt;</span></span>
<span><span><span class="type-var">'a</span> <a href="Request/index.html#type-t">Request.t</a></span> <span class="arrow">&#45;&gt;</span></span>
<span><span class="type-var">'b</span> <a href="../StructStorage/index.html#type-reader_t">StructStorage.reader_t</a></span></span></code></div><div class="spec-doc"><p>Wrapper for <code>call_for_value</code> that turns errors into exceptions.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-call_for_unit"><a href="#val-call_for_unit" class="anchor"></a><code><span><span class="keyword">val</span> call_for_unit :
<span><span><span class="type-var">'t</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span>
<span><span><span>(<span class="type-var">'t</span>, <span class="type-var">'a</span>, <span><span class="type-var">'b</span> <a href="../StructStorage/index.html#type-reader_t">StructStorage.reader_t</a></span>)</span> <span class="xref-unresolved">Capnp</span>.RPC.MethodID.t</span> <span class="arrow">&#45;&gt;</span></span>
<span><span><span class="type-var">'a</span> <a href="Request/index.html#type-t">Request.t</a></span> <span class="arrow">&#45;&gt;</span></span>
<span><span>(unit, <span>[&gt; <span>`Capnp of <a href="../../Capnp_rpc_proto/Error/index.html#type-t">Error.t</a></span> ]</span>)</span> <span class="xref-unresolved">Stdlib</span>.result</span></span></code></div><div class="spec-doc"><p>Wrapper for <code>call_for_value</code> that ignores the result.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-call_for_unit_exn"><a href="#val-call_for_unit_exn" class="anchor"></a><code><span><span class="keyword">val</span> call_for_unit_exn :
<span><span><span class="type-var">'t</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span>
<span><span><span>(<span class="type-var">'t</span>, <span class="type-var">'a</span>, <span><span class="type-var">'b</span> <a href="../StructStorage/index.html#type-reader_t">StructStorage.reader_t</a></span>)</span> <span class="xref-unresolved">Capnp</span>.RPC.MethodID.t</span> <span class="arrow">&#45;&gt;</span></span>
<span><span><span class="type-var">'a</span> <a href="Request/index.html#type-t">Request.t</a></span> <span class="arrow">&#45;&gt;</span></span>
unit</span></code></div><div class="spec-doc"><p>Wrapper for <code>call_for_unit</code> that turns errors into exceptions.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-call_for_caps"><a href="#val-call_for_caps" class="anchor"></a><code><span><span class="keyword">val</span> call_for_caps :
<span><span><span class="type-var">'t</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span>
<span><span><span>(<span class="type-var">'t</span>, <span class="type-var">'a</span>, <span><span class="type-var">'b</span> <a href="../StructStorage/index.html#type-reader_t">StructStorage.reader_t</a></span>)</span> <span class="xref-unresolved">Capnp</span>.RPC.MethodID.t</span> <span class="arrow">&#45;&gt;</span></span>
<span><span><span class="type-var">'a</span> <a href="Request/index.html#type-t">Request.t</a></span> <span class="arrow">&#45;&gt;</span></span>
<span><span>(<span><span><span class="type-var">'b</span> <a href="../StructRef/index.html#type-t">StructRef.t</a></span> <span class="arrow">&#45;&gt;</span></span> <span class="type-var">'c</span>)</span> <span class="arrow">&#45;&gt;</span></span>
<span class="type-var">'c</span></span></code></div><div class="spec-doc"><p><code>call_for_caps target m req extract</code> is a wrapper for <code>call</code> that passes the results promise to <code>extract</code>, which should extract any required capability promises from it. In the common case where you want a single cap &quot;foo&quot; from the result, use <code>call_for_caps target m req Results.foo_get_pipelined</code>. When the remote call finally returns, the result will be released automatically.</p></div></div><div class="odoc-spec"><div class="spec type anchored" id="type-resolver"><a href="#type-resolver" class="anchor"></a><code><span><span class="keyword">type</span> <span>'a resolver</span></span></code></div><div class="spec-doc"><p>An <code>'a resolver</code> can be used to resolve a promise for an <code>'a</code>. It can only be used once.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-promise"><a href="#val-promise" class="anchor"></a><code><span><span class="keyword">val</span> promise : <span>unit <span class="arrow">&#45;&gt;</span></span> <span><span class="type-var">'a</span> <a href="#type-t">t</a></span> * <span><span class="type-var">'a</span> <a href="#type-resolver">resolver</a></span></span></code></div><div class="spec-doc"><p><code>promise ()</code> returns a fresh local promise and a resolver for it. Any calls made on the promise will be queued until it is resolved.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-resolve_ok"><a href="#val-resolve_ok" class="anchor"></a><code><span><span class="keyword">val</span> resolve_ok : <span><span><span class="type-var">'a</span> <a href="#type-resolver">resolver</a></span> <span class="arrow">&#45;&gt;</span></span> <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div><div class="spec-doc"><p><code>resolve_ok r x</code> resolves <code>r</code>'s promise to <code>x</code>. <code>r</code> takes ownership of <code>x</code> (the caller must use <code>inc_ref</code> first if they want to continue using it).</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-resolve_exn"><a href="#val-resolve_exn" class="anchor"></a><code><span><span class="keyword">val</span> resolve_exn : <span><span><span class="type-var">'a</span> <a href="#type-resolver">resolver</a></span> <span class="arrow">&#45;&gt;</span></span> <span><a href="../../Capnp_rpc_proto/Exception/index.html#type-t">Exception.t</a> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div><div class="spec-doc"><p><code>resolve_exn r x</code> breaks <code>r</code>'s promise with exception <code>x</code>.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-inc_ref"><a href="#val-inc_ref" class="anchor"></a><code><span><span class="keyword">val</span> inc_ref : <span><span><span class="type-var">_</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div><div class="spec-doc"><p><code>inc_ref t</code> increases the ref-count on <code>t</code> by one.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-dec_ref"><a href="#val-dec_ref" class="anchor"></a><code><span><span class="keyword">val</span> dec_ref : <span><span><span class="type-var">_</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> unit</span></code></div><div class="spec-doc"><p><code>dec_ref t</code> decreases the ref-count on <code>t</code> 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 <code>dec_ref</code> on it.</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-with_ref"><a href="#val-with_ref" class="anchor"></a><code><span><span class="keyword">val</span> with_ref : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> <span><span>(<span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="arrow">&#45;&gt;</span></span> <span class="type-var">'b</span>)</span> <span class="arrow">&#45;&gt;</span></span> <span class="type-var">'b</span></span></code></div><div class="spec-doc"><p><code>with_ref t fn</code> runs <code>fn t</code> and then calls <code>dec_ref t</code> (whether <code>fn</code> succeeds or not).</p></div></div><div class="odoc-spec"><div class="spec value anchored" id="val-pp"><a href="#val-pp" class="anchor"></a><code><span><span class="keyword">val</span> pp : <span><span><span class="type-var">'a</span> <a href="#type-t">t</a></span> <span class="xref-unresolved">Fmt</span>.t</span></span></code></div></div></div></body></html>