ECMAScript® 2024 Language Specification

Draft ECMA-262 / February 15, 2024

9.4 Execution Contexts

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 Table 25.

Table 25: State Components for All Execution Contexts
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.

ECMAScript code execution contexts have the additional state components listed in Table 26.

Table 26: Additional State Components for ECMAScript Code Execution Contexts
Component Purpose
LexicalEnvironment Identifies the Environment Record used to resolve identifier references made by code within this execution context.
VariableEnvironment Identifies the Environment Record that holds bindings created by VariableStatements within this execution context.
PrivateEnvironment Identifies the PrivateEnvironment Record that holds Private Names created by ClassElements in the nearest containing class. null if there is no containing class.

The LexicalEnvironment and VariableEnvironment components of an execution context are always Environment Records.

Execution contexts representing the evaluation of Generators have the additional state components listed in Table 27.

Table 27: Additional State Components for Generator Execution Contexts
Component Purpose
Generator The Generator 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.

9.4.1 GetActiveScriptOrModule ( )

The abstract operation GetActiveScriptOrModule takes no arguments and returns a Script Record, a Module Record, or null. It is used to determine the running script or module, based on the running execution context. It performs the following steps when called:

  1. If the execution context stack is empty, return null.
  2. Let ec be the topmost execution context on the execution context stack whose ScriptOrModule component is not null.
  3. If no such execution context exists, return null. Otherwise, return ec's ScriptOrModule.

9.4.2 ResolveBinding ( name [ , env ] )

The abstract operation ResolveBinding takes argument name (a String) and optional argument env (an Environment Record or undefined) and returns either a normal completion containing a Reference Record or a throw completion. It is used to determine the binding of name. env can be used to explicitly provide the Environment Record that is to be searched for the binding. It performs the following steps when called:

  1. If env is not present or env is undefined, then
    1. Set env to the running execution context's LexicalEnvironment.
  2. Assert: env is an Environment Record.
  3. If the source text matched by the syntactic production that is being evaluated is contained in strict mode code, let strict be true; else let strict be false.
  4. Return ? GetIdentifierReference(env, name, strict).
 Note

The result of ResolveBinding is always a Reference Record whose [[ReferencedName]] field is name.

9.4.3 GetThisEnvironment ( )

The abstract operation GetThisEnvironment takes no arguments and returns an Environment Record. It finds the Environment Record that currently supplies the binding of the keyword this. It performs the following steps when called:

  1. Let env be the running execution context's LexicalEnvironment.
  2. Repeat,
    1. Let exists be env.HasThisBinding().
    2. If exists is true, return env.
    3. Let outer be env.[[OuterEnv]].
    4. Assert: outer is not null.
    5. Set env to outer.
 Note

The loop in step 2 will always terminate because the list of environments always ends with the global environment which has a this binding.

9.4.4 ResolveThisBinding ( )

The abstract operation ResolveThisBinding takes no arguments and returns either a normal completion containing an ECMAScript language value or a throw completion. It determines the binding of the keyword this using the LexicalEnvironment of the running execution context. It performs the following steps when called:

  1. Let envRec be GetThisEnvironment().
  2. Return ? envRec.GetThisBinding().

9.4.5 GetNewTarget ( )

The abstract operation GetNewTarget takes no arguments and returns an Object or undefined. It determines the NewTarget value using the LexicalEnvironment of the running execution context. It performs the following steps when called:

  1. Let envRec be GetThisEnvironment().
  2. Assert: envRec has a [[NewTarget]] field.
  3. Return envRec.[[NewTarget]].

9.4.6 GetGlobalObject ( )

The abstract operation GetGlobalObject takes no arguments and returns an Object. It returns the global object used by the currently running execution context. It performs the following steps when called:

  1. Let currentRealm be the current Realm Record.
  2. Return currentRealm.[[GlobalObject]].