pub struct Channel { /* private fields */ }
napi-4
only.Expand description
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
sourceimpl Channel
impl Channel
sourcepub fn new<'a, C: Context<'a>>(cx: &mut C) -> Self
pub fn new<'a, C: Context<'a>>(cx: &mut C) -> Self
Creates an unbounded channel for scheduling closures on the JavaScript main thread
sourcepub fn unref<'a, C: Context<'a>>(&mut self, cx: &mut C) -> &mut Self
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
sourcepub fn reference<'a, C: Context<'a>>(&mut self, cx: &mut C) -> &mut Self
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
sourcepub fn send<T, F>(&self, f: F) -> JoinHandle<T>ⓘNotable traits for JoinHandle<T>impl<T> Future for JoinHandle<T> type Output = Result<T, JoinError>;
where
T: Send + 'static,
F: FnOnce(TaskContext<'_>) -> NeonResult<T> + Send + 'static,
pub fn send<T, F>(&self, f: F) -> JoinHandle<T>ⓘNotable traits for JoinHandle<T>impl<T> Future for JoinHandle<T> type Output = Result<T, JoinError>;
where
T: Send + 'static,
F: FnOnce(TaskContext<'_>) -> NeonResult<T> + Send + 'static,
Schedules a closure to execute on the JavaScript thread that created this Channel Panics if there is a libuv error
sourcepub fn try_send<T, F>(&self, f: F) -> Result<JoinHandle<T>, SendError> where
T: Send + 'static,
F: FnOnce(TaskContext<'_>) -> NeonResult<T> + Send + 'static,
pub fn try_send<T, F>(&self, f: F) -> Result<JoinHandle<T>, SendError> where
T: Send + 'static,
F: FnOnce(TaskContext<'_>) -> NeonResult<T> + 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.
Trait Implementations
sourceimpl Clone for Channel
impl Clone for Channel
sourcefn clone(&self) -> Self
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.
1.0.0 · sourcefn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
Auto Trait Implementations
impl RefUnwindSafe for Channel
impl Send for Channel
impl Sync for Channel
impl Unpin for Channel
impl UnwindSafe for Channel
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more