From 514b0b45384d38b9e9aea99c7b4aec8d43658052 Mon Sep 17 00:00:00 2001
From: Michael Dyck <jmdyck@ibiblio.org>
Date: Mon, 21 Nov 2022 22:50:15 -0500
Subject: [PATCH] Execution Context section: Make the EC Stack subsection

Collect stuff about the execution context stack,
move it to a new subsection, and then rework it.

Note that there a couple of problems in the status quo:
"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."
That became false when generators were added.

"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."
No, it's always stack-like.
---
 spec.html | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/spec.html b/spec.html
index ad30c054f12..42ed91d457c 100644
--- a/spec.html
+++ b/spec.html
@@ -11561,7 +11561,6 @@ <h1>
   <emu-clause id="sec-execution-contexts">
     <h1>Execution Contexts</h1>
     <p>An <dfn variants="execution contexts">execution context</dfn> 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 <dfn id="running-execution-context" variants="running execution contexts">running execution context</dfn>. All references to the running execution context in this specification denote the running execution context of the surrounding agent.</p>
-    <p>The <dfn id="execution-context-stack" variants="execution context stacks">execution context stack</dfn> 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.</p>
     <p>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 <emu-xref href="#table-state-components-for-all-execution-contexts"></emu-xref>.</p>
     <emu-table id="table-state-components-for-all-execution-contexts" caption="State Components for All Execution Contexts" oldids="table-22">
       <table>
@@ -11607,7 +11606,6 @@ <h1>Execution Contexts</h1>
         </tr>
       </table>
     </emu-table>
-    <p>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.</p>
     <p>The value of the Realm component of the running execution context is also called <dfn id="current-realm">the current Realm Record</dfn>. The value of the Function component of the running execution context is also called the <dfn id="active-function-object">active function object</dfn>.</p>
     <p><dfn id="ecmascript-code-execution-context" variants="ECMAScript code execution context">ECMAScript code execution contexts</dfn> have the additional state components listed in <emu-xref href="#table-additional-state-components-for-ecmascript-code-execution-contexts"></emu-xref>.</p>
     <emu-table id="table-additional-state-components-for-ecmascript-code-execution-contexts" caption="Additional State Components for ECMAScript Code Execution Contexts" oldids="table-23">
@@ -11647,7 +11645,7 @@ <h1>Execution Contexts</h1>
       </table>
     </emu-table>
     <p>The LexicalEnvironment and VariableEnvironment components of an execution context are always Environment Records.</p>
-    <p>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.</p>
+    <p>In most situations only the running execution context 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.</p>
 
     <p>Execution contexts representing the evaluation of Generators have the additional state components listed in <emu-xref href="#table-additional-state-components-for-generator-execution-contexts"></emu-xref>.</p>
     <emu-table id="table-additional-state-components-for-generator-execution-contexts" caption="Additional State Components for Generator Execution Contexts" oldids="table-24">
@@ -11681,6 +11679,13 @@ <h1>Execution Contexts</h1>
 
     <p>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.</p>
 
+    <emu-clause id="sec-execution-context-stack">
+      <h1>Execution Context Stack</h1>
+      <p>An agent's <dfn id="execution-context-stack" variants="execution context stacks">execution context stack</dfn> is used to organize some or all of the agent's execution contexts. The running execution context is always the top element of this stack.</p>
+      <p>Adding and removing always happens at the “top” of the execution context stack. When an execution context is added, it becomes the topmost (i.e., the running execution context), and when it is later removed, the execution context “below” it becomes topmost again.</p>
+      <emu-note>In the absense of generators, every execution context that is pushed onto the stack is new, and when it's removed from the stack it can be discarded. With generators, some execution contexts outlive their time on the stack, exist for a while outside the stack, and then later are pushed onto the stack again.</emu-note>
+    </emu-clause>
+
     <emu-clause id="sec-getactivescriptormodule" type="abstract operation">
       <h1>GetActiveScriptOrModule ( ): a Script Record, a Module Record, or *null*</h1>
       <dl class="header">