Trait boa_engine::job::JobQueue

source · 
pub trait JobQueue {
    // Required methods
    fn enqueue_promise_job(&self, job: NativeJob, context: &mut Context);
    fn run_jobs(&self, context: &mut Context);
    fn enqueue_future_job(&self, future: FutureJob, context: &mut Context);

    // Provided method
    fn run_jobs_async<'a, 'ctx, 'fut>(
        &'a self,
        context: &'ctx mut Context
    ) -> Pin<Box<dyn Future<Output = ()> + 'fut>>
       where 'a: 'fut,
             'ctx: 'fut { ... }
}
Expand description

A queue of ECMAscript Jobs.

This is the main API that allows creating custom event loops with custom job queues.

Required Methods§

source

fn enqueue_promise_job(&self, job: NativeJob, context: &mut Context)

HostEnqueuePromiseJob ( job, realm ).

Enqueues a NativeJob on the job queue.

§Requirements

Per the spec:

An implementation of HostEnqueuePromiseJob must conform to the requirements in 9.5 as well as the following:

  • If realm is not null, each time job is invoked the implementation must perform implementation-defined steps such that execution is prepared to evaluate ECMAScript code at the time of job’s invocation.
  • Let scriptOrModule be GetActiveScriptOrModule() at the time HostEnqueuePromiseJob is invoked. If realm is not null, each time job is invoked the implementation must perform implementation-defined steps such that scriptOrModule is the active script or module at the time of job’s invocation.
  • Jobs must run in the same order as the HostEnqueuePromiseJob invocations that scheduled them.

Of all the requirements, Boa guarantees the first two by its internal implementation of NativeJob, meaning the implementer must only guarantee that jobs are run in the same order as they’re enqueued.

source

fn run_jobs(&self, context: &mut Context)

Runs all jobs in the queue.

Running a job could enqueue more jobs in the queue. The implementor of the trait determines if the method should loop until there are no more queued jobs or if it should only run one iteration of the queue.

source

fn enqueue_future_job(&self, future: FutureJob, context: &mut Context)

Enqueues a new Future job on the job queue.

On completion, future returns a new NativeJob that needs to be enqueued into the job queue to update the state of the inner Promise, which is what ECMAScript sees. Failing to do this will leave the inner Promise in the pending state, which won’t call any then or catch handlers, even if future was already completed.

Provided Methods§

source

fn run_jobs_async<'a, 'ctx, 'fut>( &'a self, context: &'ctx mut Context ) -> Pin<Box<dyn Future<Output = ()> + 'fut>>
where 'a: 'fut, 'ctx: 'fut,

Asynchronously runs all jobs in the queue.

Running a job could enqueue more jobs in the queue. The implementor of the trait determines if the method should loop until there are no more queued jobs or if it should only run one iteration of the queue.

By default forwards to JobQueue::run_jobs. Implementors using async should override this with a proper algorithm to run jobs asynchronously.

Implementors§