Update tokio fetch

Author: kjvalencik

examples/tokio-fetch/README.md

@@ -2,77 +2,27 @@
 
 Example of spawning a Rust async task on the [tokio][tokio] thread pool and resolving a JavaScript [Promise][promise] after it completes.
 
-_**Note:** This example uses a pre-release version of Neon._
-
 [tokio]: https://tokio.rs
 [promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
 
 ## Methods
 
-#### `function nodeReleaseDate(): Promise<string>`
-
-Asynchronously fetch the release date for the currently running Node process from nodejs.org.
-
-## Design
-
-### Executor
-
-For optimum task scheduling, it is best to have a single Rust task executor (e.g., tokio runtime). To make the runtime singleton available to Neon functions, it is stored in a global using `OnceCell`.
-
-```rust
-use once_cell::sync::OnceCell;
-use tokio::runtime::Runtime;
-
-static RUNTIME: OnceCell<Runtime> = OnceCell::new();
-```
+### `function nodeReleaseDate(version: string): Promise<string>`
 
-A small helper is provided to lazily initialize the runtime and throw an exception on failure.
+Asynchronously fetch the release date for a given Node release from nodejs.org.
 
-```rust
-fn runtime<'a, C: Context<'a>>(cx: &mut C) -> NeonResult<&'static Runtime> {
-    RUNTIME.get_or_try_init(|| Runtime::new().or_else(|err| cx.throw_error(err.to_string())))
-}
-```
+`nodeReleaseDate` is a Rust `async fn`. The argument uses [`TryFromJs`][tryfromjs] and return value uses [`TryIntoJs`][tryintojs] for ergonomic conversions.  
 
-### Spawning Tasks
+### `function currentNodeReleaseDate(): Promise<string>`
 
-Tasks may be spawned on the tokio runtime by using the `RUNTIME` handle. Spawning a task does *not* block the current thread. Inside a task the `await` keyword may be used and typical async Rust patterns may be used.
-
-```rust
-let rt = runtime(&mut cx)?;
-
-rt.spawn(async move {
-    // Asynchronous Rust may used in here
-});
-```
-
-### Promises
-
-When a task is spawned on the tokio runtime, it will be executed at a later time. JavaScript needs to be notified when the task completes. 
-
-* Neon [`Channel`][channel] may be created for moving an operation from the tokio thread pool back to the JavaScript main thread.
-* [`cx.promise()`][cx-promise] creates a [`JsPromise`][js-promise] and [`Deferred`][deferred] for signaling JavaScript.
-* [`JsPromise`][js-promise] is synchronously returned and may be used with `await` in JavaScript
-* [`Deferred`][deferred] is used to settle the [`JsPromise`][js-promise] from the [`Channel`][channel] callback.
-
-```rust
-let channel = cx.channel();
-let (deferred, promise) = cx.promise();
-
-rt.spawn(async move {
-    // Code here executes non-blocking on the tokio thread pool
+Asynchronously fetch the release date for the currently running Node process from nodejs.org.
 
-    deferred.settle_with(&channel, move |mut cx| {
-        // Code here executes blocking on the JavaScript main thread
+`currentNodeReleaseDate` needs to access the JavaScript VM synchronously in order to get the current Node version before spawning an async tokio task.
 
-        Ok(cx.undefined())
-    });
-});
+Writing a _synchronous_ Rust `fn`, that returns a Rust future, allows synchronous setup code that uses [`Cx`][cx].
 
-Ok(promise)
-```
+**Note**: The returned future is still required to be `Send + 'static`.
 
-[channel]: https://docs.rs/neon/0.10.0-alpha.3/neon/event/struct.Channel.html
-[cx-promise]: https://docs.rs/neon/0.10.0-alpha.3/neon/context/trait.Context.html#method.promise
-[js-promise]: https://docs.rs/neon/0.10.0-alpha.3/neon/types/struct.JsPromise.html
-[deferred]: https://docs.rs/neon/0.10.0-alpha.3/neon/types/struct.Deferred.html
+[tryfromjs]: https://docs.rs/neon/latest/neon/types/extract/trait.TryFromJs.html
+[tryintojs]: https://docs.rs/neon/latest/neon/types/extract/trait.TryIntoJs.html
+[cx]: https://docs.rs/neon/latest/neon/context/struct.Cx.html

examples/tokio-fetch/src/lib.rs

@@ -31,17 +31,26 @@ fn node_version(cx: &mut Cx) -> NeonResult<String> {
     cx.global::<JsObject>("process")?.prop(cx, "version").get()
 }
 
+// Export an async JavaScript function where the body is executed on the tokio thread pool
+#[neon::export]
+async fn node_release_date(version: String) -> Result<String, Error> {
+    let release = fetch_node_release(&version)
+        .await?
+        .ok_or_else(|| format!("Could not find version: {version}"))?;
+
+    Ok(release.date)
+}
+
+// Similar to `node_release_date`, but includes some setup code synchronously executed
+// on the JavaScript main thread before return a task for tokio. Since this is not
+// an `async fn`, we need to explicitly tell the export macro that it returns a future.
 #[neon::export(async)]
-fn node_release_date(
+fn current_node_release_date(
     cx: &mut Cx,
 ) -> NeonResult<impl Future<Output = Result<String, Error>> + use<>> {
+    // Executes synchronously on the JavaScript main thread
     let version = node_version(cx)?;
 
-    Ok(async move {
-        let release = fetch_node_release(&version)
-            .await?
-            .ok_or_else(|| format!("Could not find version: {version}"))?;
-
-        Ok(release.date)
-    })
+    // This task is executed asynchronously on the tokio thread pool
+    Ok(node_release_date(version))
 }