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§
sourcefn enqueue_promise_job(&self, job: NativeJob, context: &mut Context)
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 timejob
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
beGetActiveScriptOrModule()
at the timeHostEnqueuePromiseJob
is invoked. If realm is not null, each time job is invoked the implementation must perform implementation-defined steps such thatscriptOrModule
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.
sourcefn run_jobs(&self, context: &mut Context)
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.
sourcefn enqueue_future_job(&self, future: FutureJob, context: &mut Context)
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§
sourcefn run_jobs_async<'a, 'ctx, 'fut>(
&'a self,
context: &'ctx mut Context
) -> Pin<Box<dyn Future<Output = ()> + 'fut>>where
'a: 'fut,
'ctx: 'fut,
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.