WIP: Non-blocking Rust futures running on local thread

[alshdavid]

This PR introduces Rust future execution concurrently on the local thread without blocking JavaScript execution.

It's still a work in progress, requesting comments for ways I can improve the implementation if it's a good candidate for contribution.

Examples

Async Function Declaration

Simple Async

Declare an async function that returns a promise and does not block the main thread.

import napi from './napi.node'
napi.foo().then(() => console.log('Hi'))

async fn foo<'a>(mut cx: AsyncFunctionContext) -> JsResult<'a, JsUndefined> {
  println!("Rust started");
  task::sleep(Duration::from_secs(1)).await;
  println!("Rust sleeped");
  Ok(cx.undefined())
}

#[neon::main]
fn main(mut cx: ModuleContext) -> NeonResult<()> {
  cx.export_function_async("foo", foo)?;
  Ok(())
}

Async MPSC Channel

async fn foo<'a>(mut cx: AsyncFunctionContext) -> JsResult<'a, JsUndefined> {
  let callback: Handle<JsFunction> = cx.argument(0)?;
  let (tx, rx) = unbounded::<u32>();

  thread::spawn(move || {
    thread::sleep(Duration::from_secs(1));
    tx.send_blocking(42).unwrap();
  });

  rx.recv().await.unwrap();
  callback.call_with(&cx).exec(&mut cx)?;
  Ok(cx.undefined())
}

Function Async Closure

fn foo(mut cx: FunctionContext) -> JsResult<JsUndefined> {
  let callback = cx.argument::<JsFunction>(0)?.to_static(&mut cx);

  cx.execute_async(|mut cx| async move {
    let callback = callback.from_static(&mut cx);
    task::sleep(Duration::from_secs(1)).await;
    callback.call_with(&cx).exec(&mut cx).unwrap();
  });
  
  Ok(cx.undefined())
}

#[neon::main]
fn main(mut cx: ModuleContext) -> NeonResult<()> {
  cx.export_function("foo", foo)?;
  Ok(())
}

How does this work? Tokio?

This works by essentially bolting a custom Rust futures executor onto Nodejs's event loop triggered via a thread safe function.

The futures executor yields back to JavaScript execution as soon as it hits a pending Future, later resuming when woken up by a future that has work to do.

This means that the Rust "event loop" will never block Nodejs's event loop and vice versa.

For channels, sleep, and other common async tasks, utilities from async-std can be used.

Tokio is not suitable for this use case as it's designed to be the only executor running and cannot be driven (or at least I cannot figure out how to drive it) from an external event loop.

TODO:
[] Tests
[] Error handing
[] Documentation
[] Missing functionality

[alshdavid]

I kept the runtime static because it's thread local (one executor per Nodejs thread) and I wasn't sure how best make it available to call.

Perhaps I could initialize it during the module initialization phase and propagate it through the contexts?

[alshdavid]

This essentially creates:

function(...args: Array<Root>): Promise<R>

I included this as a means to test the futures executor out so I can exclude it from the first PR. It is missing methods and other stuff so it's certainly not production ready.

[alshdavid]

I needed this to test out the feature. It creates a rooted JsObject and assigns properties to it using Symbols as keys.

Can be removed so the core executor can be introduced where these other bits get ironed out later