A Lexical Environment is a specification type used to define the association of |Identifier|s to specific variables and functions based upon the lexical nesting structure of ECMAScript code. A Lexical Environment consists of an Environment Record and a possibly null reference to an outer Lexical Environment. Usually a Lexical Environment is associated with some specific syntactic structure of ECMAScript code such as a |FunctionDeclaration|, a |BlockStatement|, or a |Catch| clause of a |TryStatement| and a new Lexical Environment is created each time such code is evaluated.
+An Environment Record records the identifier bindings that are created within the scope of its associated Lexical Environment. It is referred to as the Lexical Environment's EnvironmentRecord
+The outer environment reference is used to model the logical nesting of Lexical Environment values. The outer reference of a (inner) Lexical Environment is a reference to the Lexical Environment that logically surrounds the inner Lexical Environment. An outer Lexical Environment may, of course, have its own outer Lexical Environment. A Lexical Environment may serve as the outer environment for multiple inner Lexical Environments. For example, if a |FunctionDeclaration| contains two nested |FunctionDeclaration|s then the Lexical Environments of each of the nested functions will have as their outer Lexical Environment the Lexical Environment of the current evaluation of the surrounding function.
+A global environment is a Lexical Environment which does not have an outer environment. The global environment's outer environment reference is *null*. A global environment's EnvironmentRecord may be prepopulated with identifier bindings and includes an associated global object whose properties provide some of the global environment's identifier bindings. As ECMAScript code is executed, additional properties may be added to the global object and the initial properties may be modified.
+A module environment is a Lexical Environment that contains the bindings for the top level declarations of a |Module|. It also contains the bindings that are explicitly imported by the |Module|. The outer environment of a module environment is a global environment.
+A function environment is a Lexical Environment that corresponds to the invocation of an ECMAScript function object. A function environment may establish a new `this` binding. A function environment also captures the state necessary to support `super` method invocations.
+Lexical Environments and Environment Record values are purely specification mechanisms and need not correspond to any specific artefact of an ECMAScript implementation. It is impossible for an ECMAScript program to directly access or manipulate such values.
+ + +There are two primary kinds of Environment Record values used in this specification: declarative Environment Records and object Environment Records. Declarative Environment Records are used to define the effect of ECMAScript language syntactic elements such as |FunctionDeclaration|s, |VariableDeclaration|s, and |Catch| clauses that directly associate identifier bindings with ECMAScript language values. Object Environment Records are used to define the effect of ECMAScript elements such as |WithStatement| that associate identifier bindings with the properties of some object. Global Environment Records and function Environment Records are specializations that are used for specifically for |Script| global declarations and for top-level declarations within functions.
+For specification purposes Environment Record values are values of the Record specification type and can be thought of as existing in a simple object-oriented hierarchy where Environment Record is an abstract class with three concrete subclasses, declarative Environment Record, object Environment Record, and global Environment Record. Function Environment Records and module Environment Records are subclasses of declarative Environment Record. The abstract class includes the abstract specification methods defined in
| + Method + | ++ Purpose + | +
|---|---|
| + HasBinding(N) + | ++ Determine if an Environment Record has a binding for the String value _N_. Return *true* if it does and *false* if it does not + | +
| + CreateMutableBinding(N, D) + | ++ Create a new but uninitialized mutable binding in an Environment Record. The String value _N_ is the text of the bound name. If the Boolean argument _D_ is *true* the binding may be subsequently deleted. + | +
| + CreateImmutableBinding(N, S) + | ++ Create a new but uninitialized immutable binding in an Environment Record. The String value _N_ is the text of the bound name. If _S_ is *true* then attempts to set it after it has been initialized will always throw an exception, regardless of the strict mode setting of operations that reference that binding. + | +
| + InitializeBinding(N, V) + | ++ Set the value of an already existing but uninitialized binding in an Environment Record. The String value _N_ is the text of the bound name. _V_ is the value for the binding and is a value of any ECMAScript language type. + | +
| + SetMutableBinding(N, V, S) + | ++ Set the value of an already existing mutable binding in an Environment Record. The String value _N_ is the text of the bound name. _V_ is the value for the binding and may be a value of any ECMAScript language type. _S_ is a Boolean flag. If _S_ is *true* and the binding cannot be set throw a *TypeError* exception. + | +
| + GetBindingValue(N, S) + | ++ Returns the value of an already existing binding from an Environment Record. The String value _N_ is the text of the bound name. _S_ is used to identify references originating in strict mode code or that otherwise require strict mode reference semantics. If _S_ is *true* and the binding does not exist throw a *ReferenceError* exception. If the binding exists but is uninitialized a *ReferenceError* is thrown, regardless of the value of _S_. + | +
| + DeleteBinding(N) + | ++ Delete a binding from an Environment Record. The String value _N_ is the text of the bound name. If a binding for _N_ exists, remove the binding and return *true*. If the binding exists but cannot be removed return *false*. If the binding does not exist return *true*. + | +
| + HasThisBinding() + | ++ Determine if an Environment Record establishes a `this` binding. Return *true* if it does and *false* if it does not. + | +
| + HasSuperBinding() + | ++ Determine if an Environment Record establishes a `super` method binding. Return *true* if it does and *false* if it does not. + | +
| + WithBaseObject() + | ++ If this Environment Record is associated with a `with` statement, return the with object. Otherwise, return *undefined*. + | +
Each declarative Environment Record is associated with an ECMAScript program scope containing variable, constant, let, class, module, import, and/or function declarations. A declarative Environment Record binds the set of identifiers defined by the declarations contained within its scope.
+The behaviour of the concrete specification methods for declarative Environment Records is defined by the following algorithms.
+ + +The concrete Environment Record method HasBinding for declarative Environment Records simply determines if the argument identifier is one of the identifiers bound by the record:
+The concrete Environment Record method CreateMutableBinding for declarative Environment Records creates a new mutable binding for the name _N_ that is uninitialized. A binding must not already exist in this Environment Record for _N_. If Boolean argument _D_ has the value *true* the new binding is marked as being subject to deletion.
+The concrete Environment Record method CreateImmutableBinding for declarative Environment Records creates a new immutable binding for the name _N_ that is uninitialized. A binding must not already exist in this Environment Record for _N_. If the Boolean argument _S_ has the value *true* the new binding is marked as a strict binding.
+The concrete Environment Record method InitializeBinding for declarative Environment Records is used to set the bound value of the current binding of the identifier whose name is the value of the argument _N_ to the value of argument _V_. An uninitialized binding for _N_ must already exist.
+The concrete Environment Record method SetMutableBinding for declarative Environment Records attempts to change the bound value of the current binding of the identifier whose name is the value of the argument _N_ to the value of argument _V_. A binding for _N_ normally already exists, but in rare cases it may not. If the binding is an immutable binding, a *TypeError* is thrown if _S_ is *true*.
+An example of ECMAScript code that results in a missing binding at step 2 is:
+function f(){eval("var x; x = (delete x, 0);")}The concrete Environment Record method GetBindingValue for declarative Environment Records simply returns the value of its bound identifier whose name is the value of the argument _N_. If the binding exists but is uninitialized a *ReferenceError* is thrown, regardless of the value of _S_.
+The concrete Environment Record method DeleteBinding for declarative Environment Records can only delete bindings that have been explicitly designated as being subject to deletion.
+Regular declarative Environment Records do not provide a `this` binding.
+Regular declarative Environment Records do not provide a `super` binding.
+Declarative Environment Records always return *undefined* as their WithBaseObject.
+Each object Environment Record is associated with an object called its binding object. An object Environment Record binds the set of string identifier names that directly correspond to the property names of its binding object. Property keys that are not strings in the form of an |IdentifierName| are not included in the set of bound identifiers. Both own and inherited properties are included in the set regardless of the setting of their [[Enumerable]] attribute. Because properties can be dynamically added and deleted from objects, the set of identifiers bound by an object Environment Record may potentially change as a side-effect of any operation that adds or deletes properties. Any bindings that are created as a result of such a side-effect are considered to be a mutable binding even if the Writable attribute of the corresponding property has the value *false*. Immutable bindings do not exist for object Environment Records.
+Object Environment Records created for `with` statements (
The behaviour of the concrete specification methods for object Environment Records is defined by the following algorithms.
+ + +The concrete Environment Record method HasBinding for object Environment Records determines if its associated binding object has a property whose name is the value of the argument _N_:
+The concrete Environment Record method CreateMutableBinding for object Environment Records creates in an Environment Record's associated binding object a property whose name is the String value and initializes it to the value *undefined*. If Boolean argument _D_ has the value *true* the new property's [[Configurable]] attribute is set to *true*; otherwise it is set to *false*.
+Normally _envRec_ will not have a binding for _N_ but if it does, the semantics of DefinePropertyOrThrow may result in an existing binding being replaced or shadowed or cause an abrupt completion to be returned.
+The concrete Environment Record method CreateImmutableBinding is never used within this specification in association with object Environment Records.
+The concrete Environment Record method InitializeBinding for object Environment Records is used to set the bound value of the current binding of the identifier whose name is the value of the argument _N_ to the value of argument _V_. An uninitialized binding for _N_ must already exist.
+In this specification, all uses of CreateMutableBinding for object Environment Records are immediately followed by a call to InitializeBinding for the same name. Hence, implementations do not need to explicitly track the initialization state of individual object Environment Record bindings.
+The concrete Environment Record method SetMutableBinding for object Environment Records attempts to set the value of the Environment Record's associated binding object's property whose name is the value of the argument _N_ to the value of argument _V_. A property named _N_ normally already exists but if it does not or is not currently writable, error handling is determined by the value of the Boolean argument _S_.
+The concrete Environment Record method GetBindingValue for object Environment Records returns the value of its associated binding object's property whose name is the String value of the argument identifier _N_. The property should already exist but if it does not the result depends upon the value of the _S_ argument:
+The concrete Environment Record method DeleteBinding for object Environment Records can only delete bindings that correspond to properties of the environment object whose [[Configurable]] attribute have the value *true*.
+Regular object Environment Records do not provide a `this` binding.
+Regular object Environment Records do not provide a `super` binding.
+Object Environment Records return *undefined* as their WithBaseObject unless their _withEnvironment_ flag is *true*.
+A function Environment Record is a declarative Environment Record that is used to represent the top-level scope of a function and, if the function is not an |ArrowFunction|, provides a `this` binding. If a function is not an |ArrowFunction| function and references `super`, its function Environment Record also contains the state that is used to perform `super` method invocations from within the function.
+Function Environment Records have the additional state fields listed in
| + Field Name + | ++ Value + | ++ Meaning + | +
|---|---|---|
| + [[ThisValue]] + | ++ Any + | ++ This is the *this* value used for this invocation of the function. + | +
| + [[ThisBindingStatus]] + | ++ `"lexical"` | `"initialized"` | `"uninitialized"` + | ++ If the value is `"lexical"`, this is an |ArrowFunction| and does not have a local this value. + | +
| + [[FunctionObject]] + | ++ Object + | ++ The function object whose invocation caused this Environment Record to be created. + | +
| + [[HomeObject]] + | ++ Object | *undefined* + | ++ If the associated function has `super` property accesses and is not an |ArrowFunction|, [[HomeObject]] is the object that the function is bound to as a method. The default value for [[HomeObject]] is *undefined*. + | +
| + [[NewTarget]] + | ++ Object | *undefined* + | ++ If this Environment Record was created by the [[Construct]] internal method, [[NewTarget]] is the value of the [[Construct]] _newTarget_ parameter. Otherwise, its value is *undefined*. + | +
Function Environment Records support all of the declarative Environment Record methods listed in
| + Method + | ++ Purpose + | +
|---|---|
| + BindThisValue(V) + | ++ Set the [[ThisValue]] and record that it has been initialized. + | +
| + GetThisBinding() + | ++ Return the value of this Environment Record's `this` binding. Throws a *ReferenceError* if the `this` binding has not been initialized. + | +
| + GetSuperBase() + | ++ Return the object that is the base for `super` property accesses bound in this Environment Record. The object is derived from this Environment Record's [[HomeObject]] field. The value *undefined* indicates that `super` property accesses will produce runtime errors. + | +
The behaviour of the additional concrete specification methods for function Environment Records is defined by the following algorithms:
+ + +A global Environment Record is used to represent the outer most scope that is shared by all of the ECMAScript |Script| elements that are processed in a common realm. A global Environment Record provides the bindings for built-in globals (clause
A global Environment Record is logically a single record but it is specified as a composite encapsulating an object Environment Record and a declarative Environment Record. The object Environment Record has as its base object the global object of the associated Realm Record. This global object is the value returned by the global Environment Record's GetThisBinding concrete method. The object Environment Record component of a global Environment Record contains the bindings for all built-in globals (clause
Properties may be created directly on a global object. Hence, the object Environment Record component of a global Environment Record may contain both bindings created explicitly by |FunctionDeclaration|, |GeneratorDeclaration|, |AsyncFunctionDeclaration|, or |VariableDeclaration| declarations and bindings created implicitly as properties of the global object. In order to identify which bindings were explicitly created using declarations, a global Environment Record maintains a list of the names bound using its CreateGlobalVarBinding and CreateGlobalFunctionBinding concrete methods.
+Global Environment Records have the additional fields listed in
| + Field Name + | ++ Value + | ++ Meaning + | +
|---|---|---|
| + [[ObjectRecord]] + | ++ Object Environment Record + | ++ Binding object is the global object. It contains global built-in bindings as well as |FunctionDeclaration|, |GeneratorDeclaration|, |AsyncFunctionDeclaration|, and |VariableDeclaration| bindings in global code for the associated realm. + | +
| + [[GlobalThisValue]] + | ++ Object + | ++ The value returned by `this` in global scope. Hosts may provide any ECMAScript Object value. + | +
| + [[DeclarativeRecord]] + | ++ Declarative Environment Record + | ++ Contains bindings for all declarations in global code for the associated realm code except for |FunctionDeclaration|, |GeneratorDeclaration|, |AsyncFunctionDeclaration|, and |VariableDeclaration| _bindings_. + | +
| + [[VarNames]] + | ++ List of String + | ++ The string names bound by |FunctionDeclaration|, |GeneratorDeclaration|, |AsyncFunctionDeclaration|, and |VariableDeclaration| declarations in global code for the associated realm. + | +
| + Method + | ++ Purpose + | +
|---|---|
| + GetThisBinding() + | ++ Return the value of this Environment Record's `this` binding. + | +
| + HasVarDeclaration (N) + | ++ Determines if the argument identifier has a binding in this Environment Record that was created using a |VariableDeclaration|, |FunctionDeclaration|, |GeneratorDeclaration|, or |AsyncFunctionDeclaration|. + | +
| + HasLexicalDeclaration (N) + | ++ Determines if the argument identifier has a binding in this Environment Record that was created using a lexical declaration such as a |LexicalDeclaration| or a |ClassDeclaration|. + | +
| + HasRestrictedGlobalProperty (N) + | ++ Determines if the argument is the name of a global object property that may not be shadowed by a global lexical binding. + | +
| + CanDeclareGlobalVar (N) + | ++ Determines if a corresponding CreateGlobalVarBinding call would succeed if called for the same argument _N_. + | +
| + CanDeclareGlobalFunction (N) + | ++ Determines if a corresponding CreateGlobalFunctionBinding call would succeed if called for the same argument _N_. + | +
| + CreateGlobalVarBinding(N, D) + | ++ Used to create and initialize to *undefined* a global `var` binding in the [[ObjectRecord]] component of a global Environment Record. The binding will be a mutable binding. The corresponding global object property will have attribute values appropriate for a `var`. The String value _N_ is the bound name. If _D_ is *true* the binding may be deleted. Logically equivalent to CreateMutableBinding followed by a SetMutableBinding but it allows var declarations to receive special treatment. + | +
| + CreateGlobalFunctionBinding(N, V, D) + | ++ Create and initialize a global `function` binding in the [[ObjectRecord]] component of a global Environment Record. The binding will be a mutable binding. The corresponding global object property will have attribute values appropriate for a `function`. The String value _N_ is the bound name. _V_ is the initialization value. If the Boolean argument _D_ is *true* the binding may be deleted. Logically equivalent to CreateMutableBinding followed by a SetMutableBinding but it allows function declarations to receive special treatment. + | +
The behaviour of the concrete specification methods for global Environment Records is defined by the following algorithms.
+ + +The concrete Environment Record method HasBinding for global Environment Records simply determines if the argument identifier is one of the identifiers bound by the record:
+The concrete Environment Record method CreateMutableBinding for global Environment Records creates a new mutable binding for the name _N_ that is uninitialized. The binding is created in the associated DeclarativeRecord. A binding for _N_ must not already exist in the DeclarativeRecord. If Boolean argument _D_ has the value *true* the new binding is marked as being subject to deletion.
+The concrete Environment Record method CreateImmutableBinding for global Environment Records creates a new immutable binding for the name _N_ that is uninitialized. A binding must not already exist in this Environment Record for _N_. If the Boolean argument _S_ has the value *true* the new binding is marked as a strict binding.
+The concrete Environment Record method InitializeBinding for global Environment Records is used to set the bound value of the current binding of the identifier whose name is the value of the argument _N_ to the value of argument _V_. An uninitialized binding for _N_ must already exist.
+The concrete Environment Record method SetMutableBinding for global Environment Records attempts to change the bound value of the current binding of the identifier whose name is the value of the argument _N_ to the value of argument _V_. If the binding is an immutable binding, a *TypeError* is thrown if _S_ is *true*. A property named _N_ normally already exists but if it does not or is not currently writable, error handling is determined by the value of the Boolean argument _S_.
+The concrete Environment Record method GetBindingValue for global Environment Records returns the value of its bound identifier whose name is the value of the argument _N_. If the binding is an uninitialized binding throw a *ReferenceError* exception. A property named _N_ normally already exists but if it does not or is not currently writable, error handling is determined by the value of the Boolean argument _S_.
+The concrete Environment Record method DeleteBinding for global Environment Records can only delete bindings that have been explicitly designated as being subject to deletion.
+Global Environment Records always return *undefined* as their WithBaseObject.
+The concrete Environment Record method HasVarDeclaration for global Environment Records determines if the argument identifier has a binding in this record that was created using a |VariableStatement| or a |FunctionDeclaration|:
+The concrete Environment Record method HasLexicalDeclaration for global Environment Records determines if the argument identifier has a binding in this record that was created using a lexical declaration such as a |LexicalDeclaration| or a |ClassDeclaration|:
+The concrete Environment Record method HasRestrictedGlobalProperty for global Environment Records determines if the argument identifier is the name of a property of the global object that must not be shadowed by a global lexical binding:
+Properties may exist upon a global object that were directly created rather than being declared using a var or function declaration. A global lexical binding may not be created that has the same name as a non-configurable property of the global object. The global property `undefined` is an example of such a property.
+The concrete Environment Record method CanDeclareGlobalVar for global Environment Records determines if a corresponding CreateGlobalVarBinding call would succeed if called for the same argument _N_. Redundant var declarations and var declarations for pre-existing global object properties are allowed.
+The concrete Environment Record method CanDeclareGlobalFunction for global Environment Records determines if a corresponding CreateGlobalFunctionBinding call would succeed if called for the same argument _N_.
+The concrete Environment Record method CreateGlobalVarBinding for global Environment Records creates and initializes a mutable binding in the associated object Environment Record and records the bound name in the associated [[VarNames]] List. If a binding already exists, it is reused and assumed to be initialized.
+The concrete Environment Record method CreateGlobalFunctionBinding for global Environment Records creates and initializes a mutable binding in the associated object Environment Record and records the bound name in the associated [[VarNames]] List. If a binding already exists, it is replaced.
+Global function declarations are always represented as own properties of the global object. If possible, an existing own property is reconfigured to have a standard set of attribute values. Steps 8-9 are equivalent to what calling the InitializeBinding concrete method would do and if _globalObject_ is a Proxy will produce the same sequence of Proxy trap calls.
+A module Environment Record is a declarative Environment Record that is used to represent the outer scope of an ECMAScript |Module|. In additional to normal mutable and immutable bindings, module Environment Records also provide immutable import bindings which are bindings that provide indirect access to a target binding that exists in another Environment Record.
+Module Environment Records support all of the declarative Environment Record methods listed in
| + Method + | ++ Purpose + | +
|---|---|
| + CreateImportBinding(N, M, N2) + | ++ Create an immutable indirect binding in a module Environment Record. The String value _N_ is the text of the bound name. _M_ is a Module Record, and _N2_ is a binding that exists in M's module Environment Record. + | +
| + GetThisBinding() + | ++ Return the value of this Environment Record's `this` binding. + | +
The behaviour of the additional concrete specification methods for module Environment Records are defined by the following algorithms:
+ + +The concrete Environment Record method GetBindingValue for module Environment Records returns the value of its bound identifier whose name is the value of the argument _N_. However, if the binding is an indirect binding the value of the target binding is returned. If the binding exists but is uninitialized a *ReferenceError* is thrown.
+_S_ will always be *true* because a |Module| is always strict mode code.
+The concrete Environment Record method DeleteBinding for module Environment Records refuses to delete bindings.
+Module Environment Records are only used within strict code and an early error rule prevents the delete operator, in strict code, from being applied to a Reference that would resolve to a module Environment Record binding. See
Module Environment Records provide a `this` binding.
+The concrete Environment Record method CreateImportBinding for module Environment Records creates a new initialized immutable indirect binding for the name _N_. A binding must not already exist in this Environment Record for _N_. _M_ is a Module Record, and _N2_ is the name of a binding that exists in M's module Environment Record. Accesses to the value of the new binding will indirectly access the bound value of the target binding.
+The following abstract operations are used in this specification to operate upon lexical environments:
+ + +The abstract operation GetIdentifierReference is called with a Lexical Environment _lex_, a String _name_, and a Boolean flag _strict_. The value of _lex_ may be *null*. When called, the following steps are performed:
+When the abstract operation NewDeclarativeEnvironment is called with a Lexical Environment as argument _E_ the following steps are performed:
+When the abstract operation NewObjectEnvironment is called with an Object _O_ and a Lexical Environment _E_ as arguments, the following steps are performed:
+When the abstract operation NewFunctionEnvironment is called with arguments _F_ and _newTarget_ the following steps are performed:
+When the abstract operation NewGlobalEnvironment is called with arguments _G_ and _thisValue_, the following steps are performed:
+When the abstract operation NewModuleEnvironment is called with a Lexical Environment argument _E_ the following steps are performed:
+Before it is evaluated, all ECMAScript code must be associated with a realm. Conceptually, a realm consists of a set of intrinsic objects, an ECMAScript global environment, all of the ECMAScript code that is loaded within the scope of that global environment, and other associated state and resources.
+A realm is represented in this specification as a Realm Record with the fields specified in
| + Field Name + | ++ Value + | ++ Meaning + | +
|---|---|---|
| + [[Intrinsics]] + | ++ Record whose field names are intrinsic keys and whose values are objects + | ++ The intrinsic values used by code associated with this realm + | +
| + [[GlobalObject]] + | ++ Object + | ++ The global object for this realm + | +
| + [[GlobalEnv]] + | ++ Lexical Environment + | ++ The global environment for this realm + | +
| + [[TemplateMap]] + | ++ A List of Record { [[Strings]]: List, [[Array]]: Object}. + | ++ Template objects are canonicalized separately for each realm using its Realm Record's [[TemplateMap]]. Each [[Strings]] value is a List containing, in source text order, the raw String values of a |TemplateLiteral| that has been evaluated. The associated [[Array]] value is the corresponding template object that is passed to a tag function. + | +
| + [[HostDefined]] + | ++ Any, default value is *undefined*. + | ++ Field reserved for use by host environments that need to associate additional information with a Realm Record. + | +
The abstract operation CreateRealm with no arguments performs the following steps:
+The abstract operation CreateIntrinsics with argument _realmRec_ performs the following steps:
+The abstract operation SetRealmGlobalObject with arguments _realmRec_, _globalObj_, and _thisValue_ performs the following steps:
+The abstract operation SetDefaultGlobalBindings with argument _realmRec_ performs the following steps:
+An execution context is a specification device that is used to track the runtime evaluation of code by an ECMAScript implementation. At any point in time, there is at most one execution context per agent that is actually executing code. This is known as the agent's running execution context. All references to the running execution context in this specification denote the running execution context of the surrounding agent.
+The execution context stack is used to track execution contexts. The running execution context is always the top element of this stack. A new execution context is created whenever control is transferred from the executable code associated with the currently running execution context to executable code that is not associated with that execution context. The newly created execution context is pushed onto the stack and becomes the running execution context.
+An execution context contains whatever implementation specific state is necessary to track the execution progress of its associated code. Each execution context has at least the state components listed in
| + Component + | ++ Purpose + | +
|---|---|
| + code evaluation state + | ++ Any state needed to perform, suspend, and resume evaluation of the code associated with this execution context. + | +
| + Function + | ++ If this execution context is evaluating the code of a function object, then the value of this component is that function object. If the context is evaluating the code of a |Script| or |Module|, the value is *null*. + | +
| + Realm + | ++ The Realm Record from which associated code accesses ECMAScript resources. + | +
| + ScriptOrModule + | ++ The Module Record or Script Record from which associated code originates. If there is no originating script or module, as is the case for the original execution context created in InitializeHostDefinedRealm, the value is *null*. + | +
Evaluation of code by the running execution context may be suspended at various points defined within this specification. Once the running execution context has been suspended a different execution context may become the running execution context and commence evaluating its code. At some later time a suspended execution context may again become the running execution context and continue evaluating its code at the point where it had previously been suspended. Transition of the running execution context status among execution contexts usually occurs in stack-like last-in/first-out manner. However, some ECMAScript features require non-LIFO transitions of the running execution context.
+The value of the Realm component of the running execution context is also called the current Realm Record. The value of the Function component of the running execution context is also called the active function object.
+Execution contexts for ECMAScript code have the additional state components listed in
| + Component + | ++ Purpose + | +
|---|---|
| + LexicalEnvironment + | ++ Identifies the Lexical Environment used to resolve identifier references made by code within this execution context. + | +
| + VariableEnvironment + | ++ Identifies the Lexical Environment whose EnvironmentRecord holds bindings created by |VariableStatement|s within this execution context. + | +
The LexicalEnvironment and VariableEnvironment components of an execution context are always Lexical Environments.
+Execution contexts representing the evaluation of generator objects have the additional state components listed in
| + Component + | ++ Purpose + | +
|---|---|
| + Generator + | ++ The GeneratorObject that this execution context is evaluating. + | +
In most situations only the running execution context (the top of the execution context stack) is directly manipulated by algorithms within this specification. Hence when the terms “LexicalEnvironment”, and “VariableEnvironment” are used without qualification they are in reference to those components of the running execution context.
+An execution context is purely a specification mechanism and need not correspond to any particular artefact of an ECMAScript implementation. It is impossible for ECMAScript code to directly access or observe an execution context.
+ +The GetActiveScriptOrModule abstract operation is used to determine the running script or module, based on the running execution context. GetActiveScriptOrModule performs the following steps:
+ +The ResolveBinding abstract operation is used to determine the binding of _name_ passed as a String value. The optional argument _env_ can be used to explicitly provide the Lexical Environment that is to be searched for the binding. During execution of ECMAScript code, ResolveBinding is performed using the following algorithm:
+The result of ResolveBinding is always a Reference value with its referenced name component equal to the _name_ argument.
+The abstract operation GetThisEnvironment finds the Environment Record that currently supplies the binding of the keyword `this`. GetThisEnvironment performs the following steps:
+The loop in step 2 will always terminate because the list of environments always ends with the global environment which has a `this` binding.
+The abstract operation ResolveThisBinding determines the binding of the keyword `this` using the LexicalEnvironment of the running execution context. ResolveThisBinding performs the following steps:
+The abstract operation GetNewTarget determines the NewTarget value using the LexicalEnvironment of the running execution context. GetNewTarget performs the following steps:
+The abstract operation GetGlobalObject returns the global object used by the currently running execution context. GetGlobalObject 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.
+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:
+The abstract operation InitializeHostDefinedRealm performs the following steps:
+ +The abstract operation RunJobs performs the following steps:
+An agent comprises a set of ECMAScript execution contexts, an execution context stack, a running execution context, a set of named job queues, an Agent Record, and an executing thread. Except for the executing thread, the constituents of an agent belong exclusively to that agent.
+An agent's executing thread executes the jobs in the agent's job queues on the agent's execution contexts independently of other agents, except that an executing thread may be used as the executing thread by multiple agents, provided none of the agents sharing the thread have an Agent Record whose [[CanBlock]] property is *true*.
+Some web browsers share a single executing thread across multiple unrelated tabs of a browser window, for example.
+While an agent's executing thread executes the jobs in the agent's job queues, the agent is the surrounding agent for the code in those jobs. The code uses the surrounding agent to access the specification level execution objects held within the agent: the running execution context, the execution context stack, the named job queues, and the Agent Record's fields.
+| Field Name | +Value | +Meaning | +
|---|---|---|
| [[LittleEndian]] | +Boolean | +The default value computed for the isLittleEndian parameter when it is needed by the algorithms GetValueFromBuffer and SetValueInBuffer. The choice is implementation-dependent and should be the alternative that is most efficient for the implementation. Once the value has been observed it cannot change. | +
| [[CanBlock]] | +Boolean | +Determines whether the agent can block or not. | +
| [[Signifier]] | +Any globally-unique value | +Uniquely identifies the agent within its agent cluster. | +
| [[IsLockFree1]] | +Boolean | +*true* if atomic operations on one-byte values are lock-free, *false* otherwise. | +
| [[IsLockFree2]] | +Boolean | +*true* if atomic operations on two-byte values are lock-free, *false* otherwise. | +
| [[CandidateExecution]] | +A candidate execution Record | +See the memory model. | +
Once the values of [[Signifier]], [[IsLockFree1]], and [[IsLockFree2]] have been observed by any agent in the agent cluster they cannot change.
+ +The values of [[IsLockFree1]] and [[IsLockFree2]] are not necessarily determined by the hardware, but may also reflect implementation choices that can vary over time and between ECMAScript implementations.
+ +There is no [[IsLockFree4]] property: 4-byte atomic operations are always lock-free.
+ +In practice, if an atomic operation is implemented with any type of lock the operation is not lock-free. Lock-free does not imply wait-free: there is no upper bound on how many machine steps may be required to complete a lock-free atomic operation.
+ +That an atomic access of size n is lock-free does not imply anything about the (perceived) atomicity of non-atomic accesses of size n, specifically, non-atomic accesses may still be performed as a sequence of several separate memory accesses. See ReadSharedMemory and WriteSharedMemory for details.
+An agent is a specification mechanism and need not correspond to any particular artefact of an ECMAScript implementation.
+The abstract operation AgentSignifier takes no arguments. It performs the following steps:
+The abstract operation AgentCanSuspend takes no arguments. It performs the following steps:
+In some environments it may not be reasonable for a given agent to suspend. For example, in a web browser environment, it may be reasonable to disallow suspending a document's main event handling thread, while still allowing workers' event handling threads to suspend.
+An agent cluster is a maximal set of agents that can communicate by operating on shared memory.
+ +Programs within different agents may share memory by unspecified means. At a minimum, the backing memory for SharedArrayBuffer objects can be shared among the agents in the cluster.
+ +There may be agents that can communicate by message passing that cannot share memory; they are never in the same agent cluster.
+Every agent belongs to exactly one agent cluster.
+ +The agents in a cluster need not all be alive at some particular point in time. If agent A creates another agent B, after which A terminates and B creates agent C, the three agents are in the same cluster if A could share some memory with B and B could share some memory with C.
+All agents within a cluster must have the same value for the [[LittleEndian]] property in their respective Agent Records.
+ +If different agents within an agent cluster have different values of [[LittleEndian]] it becomes hard to use shared memory for multi-byte data.
+All agents within a cluster must have the same values for the [[IsLockFree1]] property in their respective Agent Records; similarly for the [[IsLockFree2]] property.
+ +All agents within a cluster must have different values for the [[Signifier]] property in their respective Agent Records.
+ +An embedding may deactivate (stop forward progress) or activate (resume forward progress) an agent without the agent's knowledge or cooperation. If the embedding does so, it must not leave some agents in the cluster active while other agents in the cluster are deactivated indefinitely.
+ +The purpose of the preceding restriction is to avoid a situation where an agent deadlocks or starves because another agent has been deactivated. For example, if an HTML shared worker that has a lifetime independent of documents in any windows were allowed to share memory with the dedicated worker of such an independent document, and the document and its dedicated worker were to be deactivated while the dedicated worker holds a lock (say, the document is pushed into its window's history), and the shared worker then tries to acquire the lock, then the shared worker will be blocked until the dedicated worker is activated again, if ever. Meanwhile other workers trying to access the shared worker from other windows will starve.
+ +The implication of the restriction is that it will not be possible to share memory between agents that don't belong to the same suspend/wake collective within the embedding.
+An embedding may terminate an agent without any of the agent's cluster's other agents' prior knowledge or cooperation. If an agent is terminated not by programmatic action of its own or of another agent in the cluster but by forces external to the cluster, then the embedding must choose one of two strategies: Either terminate all the agents in the cluster, or provide reliable APIs that allow the agents in the cluster to coordinate so that at least one remaining member of the cluster will be able to detect the termination, with the termination data containing enough information to identify the agent that was terminated.
+ +Examples of that type of termination are: operating systems or users terminating agents that are running in separate processes; the embedding itself terminating an agent that is running in-process with the other agents when per-agent resource accounting indicates that the agent is runaway.
+Prior to any evaluation of any ECMAScript code by any agent in a cluster, the [[CandidateExecution]] field of the Agent Record for all agents in the cluster is set to the initial candidate execution. The initial candidate execution is an empty candidate execution whose [[EventLists]] field is a List containing, for each agent, an Agent Events Record whose [[AgentSignifier]] field is that agent's signifier and whose [[EventList]] field is an empty List.
+ +All agents in an agent cluster share the same candidate execution in its Agent Record's [[CandidateExecution]] field. The candidate execution is a specification mechanism used by the memory model.
+An agent cluster is a specification mechanism and need not correspond to any particular artefact of an ECMAScript implementation.
+For an agent to make forward progress is for it to perform an evaluation step according to this specification.
+An agent becomes blocked when its running execution context waits synchronously and indefinitely for an external event. Only agents whose Agent Record's [[CanBlock]] property is *true* can become blocked in this sense. An unblocked agent is one that is not blocked.
+ +Implementations must ensure that:
+This, along with the liveness guarantee in the memory model, ensures that all `"SeqCst"` writes eventually become observable to all agents.
+