A Job is an abstract operation that initiates an ECMAScript computation when no other ECMAScript computation is currently in progress. A Job abstract operation may be defined to accept an arbitrary set of job parameters.
-Execution of a Job can be initiated only when there is no running execution context and the execution context stack is empty. A PendingJob is a request for the future execution of a Job. A PendingJob is an internal Record whose fields are specified in
| - Field Name - | -- Value - | -- Meaning - | -
|---|---|---|
| - [[Job]] - | -- The name of a Job abstract operation - | -- This is the abstract operation that is performed when execution of this PendingJob is initiated. - | -
| - [[Arguments]] - | -- A List - | -- The List of argument values that are to be passed to [[Job]] when it is activated. - | -
| - [[Realm]] - | -- A Realm Record - | -- The Realm Record for the initial execution context when this PendingJob is initiated. - | -
| - [[ScriptOrModule]] - | -- A Script Record or Module Record - | -- The script or module for the initial execution context when this PendingJob is initiated. - | -
| - [[HostDefined]] - | -- Any, default value is *undefined*. - | -- Field reserved for use by host environments that need to associate additional information with a pending Job. - | -
A Job Queue is a FIFO queue of PendingJob records. Each Job Queue has a name and the full set of available Job Queues are defined by an ECMAScript implementation. Every ECMAScript implementation has at least the Job Queues defined in
Each agent has its own set of named Job Queues. All references to a named job queue in this specification denote the named job queue of the surrounding agent.
-| - Name - | -- Purpose - | -
|---|---|
| - ScriptJobs - | -- Jobs that validate and evaluate ECMAScript |Script| and |Module| source text. See clauses 10 and 15. - | -
| - PromiseJobs - | -
- Jobs that are responses to the settlement of a Promise (see |
-
A request for the future execution of a Job is made by enqueueing, on a Job Queue, a PendingJob record that includes a Job abstract operation name and any necessary argument values. When there is no running execution context and the execution context stack is empty, the ECMAScript implementation removes the first PendingJob from a Job Queue and uses the information contained in it to create an execution context and starts execution of the associated Job abstract operation.
-The PendingJob records from a single Job Queue are always initiated in FIFO order. This specification does not define the order in which multiple Job Queues are serviced. An ECMAScript implementation may interweave the FIFO evaluation of the PendingJob records of a Job Queue with the evaluation of the PendingJob records of one or more other Job Queues. An implementation must define what occurs when there are no running execution context and all Job Queues are empty.
-Typically an ECMAScript implementation will have its Job Queues pre-initialized with at least one PendingJob and one of those Jobs will be the first to be executed. An implementation might choose to free all resources and terminate if the current Job completes and all Job Queues are empty. Alternatively, it might choose to wait for a some implementation specific agent or mechanism to enqueue new PendingJob requests.
-The following abstract operations are used to create and manage Jobs and Job Queues:
- -The EnqueueJob abstract operation requires three arguments: _queueName_, _job_, and _arguments_. It performs the following steps:
-A Job is an abstract operation that initiates an ECMAScript computation when no other ECMAScript computation is currently in progress. A Job abstract operation may be defined to accept an arbitrary set of job parameters.
+ +The exact normative requirements of evaluating Jobs are governed by the requirements on the HostEnqueueJob abstract operation. Here we explain the conceptual background and intuition in a non-normative fashion.
+ +A Job Queue is a FIFO queue of PendingJob records, denoted by a String passed as the first argument to HostEnqueueJob. (The FIFO nature of a Job Queue is enforced by the requirements on HostEnqueueJob.) Each Job Queue has such a String name, and the full set of available Job Queues are defined by an ECMAScript implementation.
+ +Every ECMAScript implementation has at least the Job Queue `"PromiseJobs"`, which are responses to the settlement of a Promise (see
A request for the future execution of a Job is made by performing HostEnqueueJob, giving a Job Queue name, a Job abstract operation, and any necessary argument values. At some time when there is no running execution context and the execution context stack is empty, the ECMAScript implementation will perform the given Job abstract operation and evaluate it with the given arguments.
+ +The Jobs enqueued on a single Job Queue are always required to be initiated in FIFO order. This specification does not impose requirements on the order in which multiple Job Queues are serviced. An ECMAScript implementation might interweave the FIFO evaluation of the Jobs on a Job Queue with the evaluation of Jobs on one or more other Job Queues. An implementation will define what occurs when there is no running execution context and all Job Queues are empty.
+ +HostEnqueueJob is an implementation defined abstract operation that schedules the abstract operation indicated by _job_ to be performed, with the arguments _arguments_, at some future time. The String _queueName_ is used to enforce certain ordering guarantees among enqueued Jobs.
+ +The implementation of HostEnqueueJob must conform to the following requirements, all of which are scoped to each agent:
+ +The abstract operation RunJobs performs the following steps:
-Unlike explicit var or function declarations, properties that are directly created on the global object result in global bindings that may be shadowed by let/const/class declarations.
The job ScriptEvaluationJob with parameters _sourceText_ and _hostDefined_ parses, validates, and evaluates _sourceText_ as a |Script|.
-A TopLevelModuleEvaluationJob with parameters _sourceText_ and _hostDefined_ is a job that parses, validates, and evaluates _sourceText_ as a |Module|.
-An implementation may parse a _sourceText_ as a |Module|, analyse it for Early Error conditions, and instantiate it prior to the execution of the TopLevelModuleEvaluationJob for that _sourceText_. An implementation may also resolve, pre-parse and pre-analyse, and pre-instantiate module dependencies of _sourceText_. However, the reporting of any errors detected by these actions must be deferred until the TopLevelModuleEvaluationJob is actually executed.
-An implementation may define behaviour other than throwing *RangeError* for `toFixed`, `toExponential`, and `toPrecision` when the _fractionDigits_ or _precision_ argument is outside the specified range.
-HostReportErrors is an implementation-defined abstract operation that allows host environments to report parsing errors, early errors, and runtime errors.
- -An implementation of HostReportErrors must complete normally in all cases. The default implementation of HostReportErrors is to unconditionally return an empty normal completion.
- -_errorList_ will be a List of ECMAScript language values. If the errors are parsing errors or early errors, these will always be *SyntaxError* or *ReferenceError* objects. Runtime errors, however, can be any ECMAScript value.
-The `length` property of a promise resolve function is 1.
@@ -36048,7 +35881,7 @@The abstract operation TriggerPromiseReactions takes a collection of PromiseReactionRecords and enqueues a new Job for each record. Each such Job processes the [[Type]] and [[Handler]] of the PromiseReactionRecord, and if the [[Handler]] is a function, calls it passing the given argument. If the [[Handler]] is *undefined*, the behaviour is determined by the [[Type]].
This informative annex gives implementations of all of the host-defined abstract operations in this specification, along with supporting infrastructure and an outline for how the environment would be initialized, in order to explain how a simple command-line ECMAScript implementation could work and conform to the various requirements on the host.
+ +This implementation uses a PendingJob Record type to track all enqueued jobs. Its fields are given here:
+ +| + Field Name + | ++ Value + | ++ Meaning + | +
|---|---|---|
| + [[Job]] + | ++ A Job abstract operation + | ++ The abstract operation that is performed when execution of this PendingJob is initiated. + | +
| + [[Arguments]] + | ++ A List + | ++ The List of argument values that are to be passed to [[Job]] when it is activated. + | +
| + [[Realm]] + | ++ A Realm Record + | ++ The Realm Record for the initial execution context when this PendingJob is initiated. + | +
| + [[ScriptOrModule]] + | ++ A Script Record or Module Record + | ++ The script or module for the initial execution context when this PendingJob is initiated. + | +
In addition to the `"PromiseJobs"` Job Queue, this implementation also has a `"ScriptJobs"` Job Queue for validating and evaluating ECMASCript |Script| and |Module| source text. In this implementation each Job Queue has an associated List of PendingJob records.
+ +This implementation's HostEnqueueJob abstract operation performs the following steps, given the arguments _queueName_, _job_, and _arguments_:
+Source text evaluation in this implementation is performed via ScriptEvaluationJob and TopLevelModuleEvaluationJob. Using Jobs to perform these evaluations is a simple way to ensure that the execution context stack is always empty when any promise jobs run, since any ScriptEvaluationJob or TopLevelModuleEvaluationJob will have run to completion.
+ +A ScriptEvaluationJob with parameter _sourceText_ parses, validates, and evaluates _sourceText_ as a |Script|.
+A TopLevelModuleEvaluationJob with parameters _sourceText_ and _filename_ is a job that parses, validates, and evaluates _sourceText_ as a |Module|.
+The implementation might parse a _sourceText_ as a |Module|, analyze it for Early Error conditions, and instantiate it prior to the execution of the TopLevelModuleEvaluationJob for that _sourceText_. It might also resolve, pre-parse and pre-analyze, and pre-instantiate module dependencies of _sourceText_. However, the reporting of any errors detected by these actions will be deferred until the TopLevelModuleEvaluationJob is actually executed.
+This implementation uses the [[HostDefined]] field of Source Text Module Records to store the filename from which a module was retrieved. It also maintains a List of ModuleMap Records, known as the module map. This helps enforce the idempotency requirements of HostResolveImportedModule. ModuleMap Records have the fields described here:
+ +| + Field Name + | ++ Value + | ++ Meaning + | +
|---|---|---|
| + [[Filename]] + | ++ A String + | ++ The filename from which this module was created. + | +
| + [[Module]] + | ++ A Source Text Module Record + | ++ The module record created for this module. + | +
This implementation's HostResolveImportedModule abstract operation performs the following steps, given the arguments _referencingModule_ and _specifier_:
+This implementation is initialized by being provided with a set of ECMAScript source texts for zero or more scripts, and zero or more modules; the modules must be provided alongside corresponding filenames. It then performs the following algorithm to evaluate those source texts in appropriate Jobs. If evaluation enqueues any further Jobs, such as promise-related Jobs, the call back to the implementation's HostEnqueueJob abstract operation will ensure those are executed after the ongoing evaluation of the script or module.
+ +Various algorithms for this implementation require reporting of errors. This is done by passing a list of errors to the ReportErrors abstract operation, which if possible, prints them to the console:
+ +_errorList_ will be a List of ECMAScript language values. If the errors are parsing errors or early errors, these will always be *SyntaxError* or *ReferenceError* objects. Runtime errors, however, can be any ECMAScript value.
+This implementation uses the default implementation of HostEnsureCanCompileStrings.
+ +This implementation's HostPromiseRejectionTracker abstract operation performs the following steps, given the arguments _promise_ and _operation_:
+ +