Struct boa_engine::job::NativeJob

pub struct NativeJob { /* private fields */ }

An ECMAScript Job closure.

The specification allows scheduling any NativeJob closure by the host into the job queue. However, host-defined jobs must abide to a set of requirements.

Requirements

• At some future point in time, when there is no running execution context and the execution context stack is empty, the implementation must:
  • Perform any host-defined preparation steps.
  • Invoke the Job Abstract Closure.
  • Perform any host-defined cleanup steps, after which the execution context stack must be empty.
• Only one Job may be actively undergoing evaluation at any point in time.
• Once evaluation of a Job starts, it must run to completion before evaluation of any other Job starts.
• The Abstract Closure must return a normal completion, implementing its own handling of errors.

NativeJobs API differs slightly on the last requirement, since it allows closures returning JsResult, but it’s okay because NativeJobs are handled by the host anyways; a host could pass a closure returning Err and handle the error on JobQueue::run_jobs, making the closure effectively run as if it never returned Err.

Trace?

NativeJob doesn’t implement Trace because it doesn’t need to; all jobs can only be run once and putting a JobQueue on a garbage collected object is not allowed.

On the other hand, it seems like this type breaks all the safety checks of the NativeFunction API, since you can capture any Trace variable into the closure… but it doesn’t! The garbage collector doesn’t need to trace the captured variables because the closures are always stored on the JobQueue, which is always rooted, which means the captured variables are also rooted, allowing us to capture any variable in the closure for free!

Implementations

impl NativeJob

pub fn new<F>(f: F) -> Self

where F: FnOnce(&mut Context) -> JsResult<JsValue> + 'static,

Creates a new NativeJob from a closure.

pub fn with_realm<F>(f: F, realm: Realm, _context: &mut Context) -> Self

where F: FnOnce(&mut Context) -> JsResult<JsValue> + 'static,

Creates a new NativeJob from a closure and an execution realm.

pub const fn realm(&self) -> Option<&Realm>

Gets a reference to the execution realm of the job.

pub fn call(self, context: &mut Context) -> JsResult<JsValue>

Calls the native job with the specified Context.

Note

If the native job has an execution realm defined, this sets the running execution context to the realm’s before calling the inner closure, and resets it after execution.

Trait Implementations

impl Debug for NativeJob

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

Formats the value using the given formatter.