PythonMonkey   v1.1.1 (dev)
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
JobQueue Class Reference

Implement the ECMAScript Job Queue: https://www.ecma-international.org/ecma-262/9.0/index.html#sec-jobs-and-job-queues. More...

#include <JobQueue.hh>

Inheritance diagram for JobQueue:
[legend]
Collaboration diagram for JobQueue:
[legend]

Public Member Functions

 JobQueue (JSContext *cx)
 
 ~JobQueue ()=default
 
bool init (JSContext *cx)
 Initialize PythonMonkey's event-loop job queue.
 
bool getHostDefinedData (JSContext *cx, JS::MutableHandle< JSObject * > data) const override
 Ask the embedding for the host defined data.
 
bool enqueuePromiseJob (JSContext *cx, JS::HandleObject promise, JS::HandleObject job, JS::HandleObject allocationSite, JS::HandleObject incumbentGlobal) override
 Enqueue a reaction job job for promise, which was allocated at allocationSite. Provide incumbentGlobal as the incumbent global for the reaction job's execution.
 
void runJobs (JSContext *cx) override
 Run all jobs in the queue. Running one job may enqueue others; continue to run jobs until the queue is empty.
 
bool empty () const override
 
bool isDrainingStopped () const override
 
void queueFinalizationRegistryCallback (JSFunction *callback)
 Appends a callback to the queue of FinalizationRegistry callbacks.
 
bool runFinalizationRegistryCallbacks (JSContext *cx)
 Runs the accumulated queue of FinalizationRegistry callbacks.
 

Detailed Description

Constructor & Destructor Documentation

◆ JobQueue()

JobQueue::JobQueue ( JSContext *  cx)
explicit

◆ ~JobQueue()

JobQueue::~JobQueue ( )
default

Member Function Documentation

◆ empty()

bool JobQueue::empty ( ) const
override
Returns
true if the job queue is empty, false otherwise.

◆ enqueuePromiseJob()

bool JobQueue::enqueuePromiseJob ( JSContext *  cx,
JS::HandleObject  promise,
JS::HandleObject  job,
JS::HandleObject  allocationSite,
JS::HandleObject  incumbentGlobal 
)
override

Enqueue a reaction job job for promise, which was allocated at allocationSite. Provide incumbentGlobal as the incumbent global for the reaction job's execution.

promise can be null if the promise is optimized out. promise is guaranteed not to be optimized out if the promise has non-default user-interaction flag.

◆ getHostDefinedData()

bool JobQueue::getHostDefinedData ( JSContext *  cx,
JS::MutableHandle< JSObject * >  data 
) const
override

Ask the embedding for the host defined data.

SpiderMonkey doesn't itself have a notion of host defined data as defined by the HTML spec, so we need the embedding to provide this. See dom/script/ScriptSettings.h for details.

If the embedding has the host defined data, this method should return the host defined data via the data out parameter and return true. The object in the data out parameter can belong to any compartment. If the embedding doesn't need the host defined data, this method should set the data out parameter to nullptr and return true. If any error happens while generating the host defined data, this method should set a pending exception to cx and return false.

◆ init()

bool JobQueue::init ( JSContext *  cx)

Initialize PythonMonkey's event-loop job queue.

Parameters
cx- javascript context pointer
Returns
success

◆ isDrainingStopped()

bool JobQueue::isDrainingStopped ( ) const
override
Returns
true if the job queue stopped draining, which results in empty() being false after runJobs().

◆ queueFinalizationRegistryCallback()

void JobQueue::queueFinalizationRegistryCallback ( JSFunction *  callback)

Appends a callback to the queue of FinalizationRegistry callbacks.

Parameters
callback- the callback to be queue'd

◆ runFinalizationRegistryCallbacks()

bool JobQueue::runFinalizationRegistryCallbacks ( JSContext *  cx)

Runs the accumulated queue of FinalizationRegistry callbacks.

Parameters
cx- Pointer to the JSContext
Returns
true - at least 1 callback was called
false - no callbacks were called

◆ runJobs()

void JobQueue::runJobs ( JSContext *  cx)
override

Run all jobs in the queue. Running one job may enqueue others; continue to run jobs until the queue is empty.

Calling this method at the wrong time can break the web. The HTML spec indicates exactly when the job queue should be drained (in HTML jargon, when it should "perform a microtask checkpoint"), and doing so at other times can incompatibly change the semantics of programs that use promises or other microtask-based features.

This method is called only via AutoDebuggerJobQueueInterruption, used by the Debugger API implementation to ensure that the debuggee's job queue is protected from the debugger's own activity. See the comments on AutoDebuggerJobQueueInterruption.


The documentation for this class was generated from the following files: