Merge pull request #82 from neon-bindings/kv/tokio-example

Tokio example

Author: kjvalencik

Cargo.lock

@@ -4,6 +4,7 @@ members = [
 	"examples/cpu-count",
 	"examples/gzip-stream",
 	"examples/hello-world",
+	"examples/tokio-fetch",
 ]
 
 [profile.release]

Cargo.toml

@@ -18,11 +18,13 @@ All examples are for [`napi-backend`][napi-migration]. For examples using `legac
 | [`cpu-count`][cpu-count]       | Return the number of CPUs                  |
 | [`gzip-stream`][gzip-stream]   | Asynchronously compress a stream of data   |
 | [`hello-world`][hello-world]   | Return a JS String with a greeting message |
+| [`tokio-fetch`][tokio-fetch]   | Asynchronously fetch a node release date   |
 
 [async-sqlite]: examples/async-sqlite
 [cpu-count]: examples/cpu-count
 [gzip-stream]: examples/gzip-stream
 [hello-world]: examples/hello-world
+[tokio-fetch]: examples/tokio-fetch
 
 ## Contributing
 

README.md

@@ -13,6 +13,6 @@ crate-type = ["cdylib"]
 flate2 = "1"
 
 [dependencies.neon]
-version = "0.10.0-alpha.2"
+version = "0.10.0-alpha.3"
 default-features = false
 features = ["napi-6", "promise-api", "task-api"]

examples/gzip-stream/Cargo.toml

@@ -68,11 +68,11 @@ impl CompressStream {
     // in both `compress_chunk` and `compress_finish`. It grabs any written bytes
     // with `CompressStream::output` and puts the data into an `ArrayBuffer`, throwing
     // a JavaScript exception if any Rust error occurred.
-    fn and_buffer<'a>(
-        cx: &mut TaskContext<'a>,
+    fn and_buffer(
+        mut cx: TaskContext,
         // Return value from `cx.task(..)` closure
         result: Result<Self, CompressError>,
-    ) -> JsResult<'a, JsBuffer> {
+    ) -> JsResult<JsBuffer> {
         let output = result
             // An error may have occurred while compressing; conditionally grab the
             // written data
@@ -81,7 +81,7 @@ impl CompressStream {
             .or_else(|err| cx.throw_error(err.to_string()))?;
 
         // Create a `Buffer` backed by a `Vec<u8>` containing the written data
-        Ok(JsBuffer::external(cx, output))
+        Ok(JsBuffer::external(&mut cx, output))
     }
 }
 

examples/gzip-stream/src/lib.rs

@@ -0,0 +1,21 @@
+[package]
+name = "tokio-fetch"
+version = "0.1.0"
+description = "Neon Tokio and Rust Async Example"
+license = "MIT"
+edition = "2018"
+exclude = ["index.node"]
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+once_cell = "1"
+reqwest = { version = "0.11", features = ["json"] }
+tokio = { version = "1", features = ["rt-multi-thread"] }
+serde = { version = "1", features = ["derive"] }
+
+[dependencies.neon]
+version = "0.10.0-alpha.3"
+default-features = false
+features = ["channel-api", "napi-6", "promise-api"]

examples/tokio-fetch/Cargo.toml

@@ -0,0 +1,78 @@
+# `tokio-fetch`
+
+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();
+```
+
+A small helper is provided to lazily initialize the runtime and throw an exception on failure.
+
+```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())))
+}
+```
+
+### Spawning Tasks
+
+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
+
+    deferred.settle_with(&channel, move |mut cx| {
+        // Code here executes blocking on the JavaScript main thread
+
+        Ok(cx.undefined())
+    });
+});
+
+Ok(promise)
+```
+
+[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