Struct neon::event::Channel

pub struct Channel { /* fields omitted */ }

This is supported on crate features napi-4 and channel-api only.

Channel for scheduling Rust closures to execute on the JavaScript main thread.

Cloning a Channel will create a new channel that shares a backing queue for events.

Example

The following example spawns a standard Rust thread to complete a computation and calls back to a JavaScript function asynchronously with the result.

fn async_fibonacci(mut cx: FunctionContext) -> JsResult<JsUndefined> {
    // These types (`f64`, `Root<JsFunction>`, `Channel`) may all be sent
    // across threads.
    let n = cx.argument::<JsNumber>(0)?.value(&mut cx);
    let callback = cx.argument::<JsFunction>(1)?.root(&mut cx);
    let channel = cx.channel();

    // Spawn a thread to complete the execution. This will _not_ block the
    // JavaScript event loop.
    std::thread::spawn(move || {
        let result = fibonacci(n);

        // Send a closure as a task to be executed by the JavaScript event
        // loop. This _will_ block the event loop while executing.
        channel.send(move |mut cx| {
            let callback = callback.into_inner(&mut cx);
            let this = cx.undefined();
            let null = cx.null();
            let args = vec![
                cx.null().upcast::<JsValue>(),
                cx.number(result).upcast(),
            ];

            callback.call(&mut cx, this, args)?;

            Ok(())
        });
    });

    Ok(cx.undefined())
}

Implementations

impl Channel

pub fn new<'a, C: Context<'a>>(cx: &mut C) -> Self

Creates an unbounded channel for scheduling closures on the JavaScript main thread

pub fn unref<'a, C: Context<'a>>(&mut self, cx: &mut C) -> &mut Self

Allow the Node event loop to exit while this Channel exists. Idempotent

pub fn reference<'a, C: Context<'a>>(&mut self, cx: &mut C) -> &mut Self

Prevent the Node event loop from exiting while this Channel exists. (Default) Idempotent

pub fn send<F>(&self, f: F) where
    F: FnOnce(TaskContext<'_>) -> NeonResult<()> + Send + 'static, 

Schedules a closure to execute on the JavaScript thread that created this Channel Panics if there is a libuv error

pub fn try_send<F>(&self, f: F) -> Result<(), SendError> where
    F: FnOnce(TaskContext<'_>) -> NeonResult<()> + Send + 'static, 

Schedules a closure to execute on the JavaScript thread that created this Channel Returns an Error if the task could not be scheduled.

See SendError for additional details on failure causes.

pub fn has_ref(&self) -> bool

Returns a boolean indicating if this Channel will prevent the Node event loop from exiting.

Trait Implementations

impl Clone for Channel

fn clone(&self) -> Self

Returns a clone of the Channel instance that shares the internal unbounded queue with the original channel. Scheduling callbacks on the same queue is faster than using separate channels, but might lead to starvation if one of the threads posts significantly more callbacks on the channel than the other one.

Cloned and referenced Channel instances might trigger additional event-loop tick when dropped. Channel can be wrapped into an Arc and shared between different threads/callers to avoid this.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Channel

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Channel

fn drop(&mut self)

Executes the destructor for this type.