Skip to content

Commit

Permalink
Better guidance and sectioning
Browse files Browse the repository at this point in the history
  • Loading branch information
@Ms2ger
Ms2ger committed Nov 21, 2024
1 parent f896319 commit eff546f
Showing 1 changed file with 51 additions and 50 deletions.
101 changes: 51 additions & 50 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -89564,8 +89564,8 @@ dictionary <dfn dictionary>DragEventInit</dfn> : <span>MouseEventInit</span> {
<li><p>Let <var>value</var> be <var>originalDesc</var>.[[Value]].</p></li>

<li><p>If <span>IsCallable</span>(<var>value</var>) is true, then set <var>value</var> to
an anonymous built-in function, created in the <span>current principal realm</span>, that
performs the same steps as the IDL operation <var>P</var> on object <var>O</var>.</p></li>
an anonymous built-in function, created in the <span>current realm</span>, that performs
the same steps as the IDL operation <var>P</var> on object <var>O</var>.</p></li>

<li><p>Set <var>crossOriginDesc</var> to <span>PropertyDescriptor</span>{
[[Value]]: <var>value</var>,
Expand All @@ -89582,14 +89582,14 @@ dictionary <dfn dictionary>DragEventInit</dfn> : <span>MouseEventInit</span> {
<li><p>Let <var>crossOriginGet</var> be undefined.</p></li>

<li><p>If <var>e</var>.[[NeedsGet]] is true, then set <var>crossOriginGet</var> to an
anonymous built-in function, created in the <span>current principal realm</span>, that
performs the same steps as the getter of the IDL attribute <var>P</var> on object
anonymous built-in function, created in the <span>current realm</span>, that performs the
same steps as the getter of the IDL attribute <var>P</var> on object
<var>O</var>.</p></li>

<li><p>Let <var>crossOriginSet</var> be undefined.</p></li>

<li><p>If <var>e</var>.[[NeedsSet]] is true, then set <var>crossOriginSet</var> to an
anonymous built-in function, created in the <span>current principal realm</span>, that
anonymous built-in function, created in the <span>current realm</span>, that
performs the same steps as the setter of the IDL attribute <var>P</var> on object
<var>O</var>.</p></li>

Expand Down Expand Up @@ -106092,8 +106092,8 @@ new PaymentRequest(&hellip;); // Allowed to use
data-x="concept-relevant-realm">relevant realm</span>'s <span data-x="realm's
agent">agent</span>.</p>

<p class="note">The agent equivalent of the <span>current principal realm</span> is the
<span>surrounding agent</span>.</p>
<p class="note">The agent equivalent of the <span>current realm</span> or
<span>current principal realm</span> is the <span>surrounding agent</span>.</p>

</div>

Expand Down Expand Up @@ -106479,6 +106479,28 @@ new PaymentRequest(&hellip;); // Allowed to use
object</span>'s <span>relevant agent</span>'s <span data-x="concept-agent-event-loop">event
loop</span>.</p>

<h5 id="synthetic-realm-settings-objects">Synthetic realm settings objects</h5>

<p>Each <span>synthetic realm</span> has an associated <dfn>synthetic realm settings object</dfn>
with the following fields:</p>

<dl>
<dt><p>An <dfn data-x="synthetic-realm-settings-object-execution-context"
for="synthetic realm settings object">execution context</dfn></p></dt>

<dd><p>The <span>JavaScript execution context</span> for the scripts within this realm.</p></dd>

<dt><p>A <dfn data-x="synthetic-realm-settings-object-principal-realm"
for="synthetic realm settings object">principal realm</dfn></p></dt>

<dd><p>The <span>principal realm</span> which this synthetic realm exists within.</p></dd>

<dt><p>A <dfn data-x="synthetic-realm-settings-object-module-map" for="synthetic realm settings
object">module map</dfn></p></dt>

<dd><p>A <span>module map</span> that is used when importing JavaScript modules.</p></dd>
</dl>

<h5 id="realms-settings-objects-global-objects">Realms, settings objects, and global objects</h5>

<p>A <dfn export>global object</dfn> is a JavaScript object that is the [[GlobalObject]] field of
Expand Down Expand Up @@ -106608,32 +106630,7 @@ new PaymentRequest(&hellip;); // Allowed to use
<li><p>Return <var>realm execution context</var>.</p></li>
</ol>

<h5 id="synthetic-realm-settings-objects">Synthetic realm settings objects</h5>

<p>Each <span>synthetic realm</span> has an associated <dfn>synthetic realm settings object</dfn>
with the following fields:</p>

<dl>
<dt><p>An <dfn data-x="synthetic-realm-settings-object-execution-context"
for="synthetic realm settings object">execution context</dfn></p></dt>

<dd><p>The <span>JavaScript execution context</span> for the scripts within this realm.</p></dd>

<dt><p>A <dfn data-x="synthetic-realm-settings-object-principal-realm"
for="synthetic realm settings object">principal realm</dfn></p></dt>

<dd><p>The <span>principal realm</span> which this synthetic realm exists within.</p></dd>

<dt><p>A <dfn data-x="synthetic-realm-settings-object-module-map" for="synthetic realm settings
object">module map</dfn></p></dt>

<dd><p>A <span>module map</span> that is used when importing JavaScript modules.</p></dd>
</dl>

<p><span data-x="synthetic realm">Synthetic realms</span> are created with <span data-x="global
object">global objects</span> which are initialized by the JavaScript specification's
<span>SetDefaultGlobalBindings</span> algorithm. <span data-x="synthetic global object">Synthetic
global objects</span> implement only certain specifically exposed interfaces.</p>
<hr>

<p>Analogously, there is always a 1-to-1-to-1 mapping between <span data-x="synthetic
realm">synthetic realms</span>, <span data-x="synthetic global object">synthetic global
Expand Down Expand Up @@ -106726,9 +106723,9 @@ new PaymentRequest(&hellip;); // Allowed to use
<hr>

<p>When defining algorithm steps throughout this specification, it is often important to indicate
what <span>principal realm</span> is to be used—or, equivalently, what <span>principal global
object</span> or <span>environment settings object</span> is to be used. In general, there are at
least four possibilities:</p>
what <span>realm</span> is to be used—or, equivalently, what <span>global object</span> or
<span>environment settings object</span> (or <span>synthetic realm settings object</span>) is to
be used. In general, there are at least four possibilities:</p>

<dl>
<dt><dfn data-x="concept-entry-everything">Entry</dfn></dt>
Expand Down Expand Up @@ -106820,7 +106817,7 @@ new PaymentRequest(&hellip;); // Allowed to use
data-x="">a.html</code>.</p></li>
<li><p>The <span data-x="concept-incumbent-realm">incumbent realm</span> is that of <code
data-x="">b.html</code>.</p></li>
<li><p>The <span>current principal realm</span> is that of <code
<li><p>The <span>current realm</span> is that of <code
data-x="">c.html</code> (since it is the <code data-x="dom-print">print()</code> method from
<code data-x="">c.html</code> whose code is running).</p></li>
<li><p>The <span data-x="concept-relevant-realm">relevant realm</span> of the object on which
Expand Down Expand Up @@ -106868,13 +106865,13 @@ new PaymentRequest(&hellip;); // Allowed to use
&lt;/script></code></pre>

<p>If the algorithm for the <code data-x="dom-navigator-getBattery">getBattery()</code> method
had instead used the <span>current principal realm</span>, all the results would be reversed.
That is, after the first call to <code data-x="dom-navigator-getBattery">getBattery()</code> in
<code data-x="">outer.html</code>, the <code>Navigator</code> object in <code
had instead used the <span>current realm</span>, all the results would be reversed. That is,
after the first call to <code data-x="dom-navigator-getBattery">getBattery()</code> in <code
data-x="">outer.html</code>, the <code>Navigator</code> object in <code
data-x="">inner.html</code> would be permanently storing a <code data-x="">Promise</code> object
created in <code data-x="">outer.html</code>'s <span>realm</span>, and calls like that inside the
<code data-x="">hello()</code> function would thus return a promise from the "wrong" realm.
Since this is undesirable, the algorithm instead uses the <span
<code data-x="">hello()</code> function would thus return a promise from the "wrong" realm. Since
this is undesirable, the algorithm instead uses the <span
data-x="concept-relevant-realm">relevant realm</span>, giving the sensible results indicated in
the comments above.</p>
</div>
Expand Down Expand Up @@ -107183,19 +107180,23 @@ document.querySelector("button").addEventListener("click", bound);
data-x="concept-principal-realm-of-realm">principal realm</span> of the <span>current
realm</span>.</p>

<p class="warning">Note that the <span>current realm</span>, unlike the entry, incumbent and
relevant concepts, can refer to a <span>synthetic realm</span>. Almost all uses of the "current"
concept in this document and other Web specifications need to refer to the <span>current principal
realm</span> as well. One exception is JavaScript module processing, as <span data-x="synthetic
realm">synthetic realms</span> have a separate set of module instances (derived from a common
<span>module map</span> across the shared <span>environment settings object</span>).</p>

<p>Then, the <dfn export>current principal settings object</dfn> is the <span
data-x="concept-realm-settings-object">environment settings object</span> of the <span>current
principal realm</span>.</p>

<p>Similarly, the <dfn export>current principal global object</dfn> is the <span
data-x="concept-realm-global">global object</span> of the <span>current principal realm</span>.</p>
data-x="concept-realm-global">global object</span> of the
<span>current principal realm</span>.</p>

<p class="warning">Note that the current realm can refer to a <span>synthetic realm</span>.
Whether to use the "current" or "current principal" concept depends on the situation.
It appears to be the case that in most situations where a <em>realm</em> is needed,
the current realm is a better choice than the current principal realm,
while it is more likely that for a <em>settings object</em>, the current principal settings object
is to be used; notably the settings object for a <span>synthetic realm</span> contains much less
information.
Note that in the context of APIs that are not exposed in a <span>synthetic realm</span>, both
concepts coincide.</p>

<h6>Relevant</h6>

Expand Down

0 comments on commit eff546f

Please sign in to comment.