Skip to content

Commit

Permalink
Deployed 1c002fa to next with MkDocs 1.6.0 and mike 2.1.1
Browse files Browse the repository at this point in the history
  • Loading branch information
uniffi-docs[bot] committed Dec 23, 2024
1 parent 2982237 commit 221f710
Showing 1 changed file with 6 additions and 9 deletions.
15 changes: 6 additions & 9 deletions next/internals/async.html
Original file line number Diff line number Diff line change
Expand Up @@ -1885,7 +1885,7 @@ <h2 id="rust-async-functions">Rust Async functions</h2>
<p>Rust async functions are implemplemented by wrapping the
<a href="https://doc.rust-lang.org/std/future/trait.Future.html">Future</a> into a <code>uniffi::RustFuture</code> struct
and providing scaffolding functions so that the foreign bindings can drive the future to completion.</p>
<div class="highlight"><pre><span></span><code>sequenceDiagram
<pre class="mermaid"><code>sequenceDiagram
participant User as User code
participant Foreign as Foreign Language Bindings
participant Rust as Rust Scaffolding
Expand All @@ -1902,8 +1902,7 @@ <h2 id="rust-async-functions">Rust Async functions</h2>
Foreign-&gt;&gt;+Rust: call RustFuture complete fn
Rust--&gt;&gt;-Foreign: return result
Foreign-&gt;&gt;Rust: call RustFuture free fn
Foreign--&gt;&gt;-User: return from async function
</code></pre></div>
Foreign--&gt;&gt;-User: return from async function</code></pre>
<p>For each async function, UniFFI generates 4 scaffolding functions:
* A scaffolding function that returns a <code>RustFuture</code> handle
* <code>rust_future_poll</code> to poll the future
Expand Down Expand Up @@ -1937,7 +1936,7 @@ <h3 id="why-not-have-rust_future_poll-return-a-boolean">Why not have <code>rust_
<h2 id="foreign-async-callback-methods">Foreign async callback methods</h2>
<p>Async callback/trait interface methods are the way that Rust makes async calls across the FFI.
These are implemented using a callback, which makes them quite a bit simpler than their counterparts.</p>
<div class="highlight"><pre><span></span><code>sequenceDiagram
<pre class="mermaid"><code>sequenceDiagram
participant User as User code
participant Rust as Rust Scaffolding
participant Foreign as Foreign Language Bindings
Expand All @@ -1947,8 +1946,7 @@ <h2 id="foreign-async-callback-methods">Foreign async callback methods</h2>
Rust--&gt;&gt;-User: return oneshot::Receiver

Foreign-&gt;&gt;Rust: invoke callback, pass back oneshot::Sender pointer
Note over Rust: send callback result to the oneshot::Sender
</code></pre></div>
Note over Rust: send callback result to the oneshot::Sender</code></pre>
<p>The UniFFI generated code for an async trait method performs these steps:</p>
<ul>
<li>Create a <code>oneshot::Channel</code> (see <a href="https://docs.rs/oneshot/latest/oneshot/">oneshot crate</a> for how these work, although we don't currently depend on that crate).</li>
Expand Down Expand Up @@ -1980,7 +1978,7 @@ <h2 id="can-you-really-just-piggyback-on-the-foreign-async-runtime">Can you real
Furthermore, let's stipulate that the deserialization/validation is slow enough to be considered blocking.
To manage this, the Rust library also depends on a (synchronous) callback interface that runs a task in a worker queue where blocking is allowed.
Here's how the async API call could be handled:</p>
<div class="highlight"><pre><span></span><code>sequenceDiagram
<pre class="mermaid"><code>sequenceDiagram
participant AsyncRust as Async Rust code
participant SyncRust as Sync Rust code
participant WorkerQueue as Work Queue Callback Interface
Expand All @@ -1995,8 +1993,7 @@ <h2 id="can-you-really-just-piggyback-on-the-foreign-async-runtime">Can you real
Note over AsyncRust: await oneshot channel
WorkerQueue-&gt;&gt;SyncRust: Run task (in background thread)
SyncRust--&gt;&gt;AsyncRust: Send deserialized response via oneshot channel
AsyncRust--&gt;&gt;-Foreign: Return API result
</code></pre></div>
AsyncRust--&gt;&gt;-Foreign: Return API result</code></pre>
<ul>
<li>Action in this sequence diagram represents calling an async Rust function or async callback interface method, see the above diagrams for details.</li>
<li>The dotted lines show how the data is passed around during the async call.</li>
Expand Down

0 comments on commit 221f710

Please sign in to comment.