Skip to content

Commit

Permalink
Improve observe() logic and references (#96)
Browse files Browse the repository at this point in the history 
* clarify entryTypes logic in observe
  - closes #90
* s/name/type when referring to PerformanceObserverInit#entryTypes
  - closes #91
* define "list of registered performance observer objects"
  - closes #93
* s/current/relevant global object
  - closes #94
* define and use "relevant performance entry buffer"

Related discussions:
#96 (comment)
  • Loading branch information
@igrigorik
igrigorik committed Nov 5, 2017
1 parent 74a9181 commit 1aabb31
Showing 1 changed file with 39 additions and 40 deletions.
79 changes: 39 additions & 40 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -193,14 +193,13 @@ <h2>Introduction</h2>
<h2><dfn>Performance Timeline</dfn></h2>
<p>Each <a>ECMAScript global environment</a> has:</p>
<ul>
<li>a <dfn>performance observer task queued flag</dfn> and an associated
list of <a>registered performance observer</a> objects which is initially
empty.
</li>
<li>a <dfn>performance observer task queued flag</dfn></li>
<li>a <dfn>list of <a>registered performance observer</a> objects</dfn> that is initially empty</li>
<li>a <dfn>performance entry buffer</dfn> to store
<a>PerformanceEntry</a> objects. It is initially empty.
<a>PerformanceEntry</a> objects that is initially empty
</li>
</ul>
<p>The <dfn>relevant performance entry buffer</dfn> is the <a>performance entry buffer</a> associated with the <a>relevant global object</a>.</p>
<section data-dfn-for="Performance" data-link-for="Performance">
<h2>Extensions to the <a>Performance</a> interface</h2>
<p>This extends the <a>Performance</a> interface [[!HR-TIME-2]] and hosts
Expand All @@ -221,22 +220,22 @@ <h2>Extensions to the <a>Performance</a> interface</h2>
<h2><dfn>getEntries()</dfn> method</h2>
<p>Returns a <a>PerformanceEntryList</a> object returned by
<a href="#filter-buffer-by-name-and-type"></a> algorithm with
<var>buffer</var> set to <a>performance entry buffer</a>, and
<var>buffer</var> set to <a>relevant performance entry buffer</a>, and
<var>name</var> and <var>type</var> set to `null`.</p>
</section>
<section>
<h2><dfn>getEntriesByType()</dfn> method</h2>
<p>Returns a <a>PerformanceEntryList</a> object returned by
<a href="#filter-buffer-by-name-and-type"></a> algorithm with
<var>buffer</var> set to <a>performance entry buffer</a>,
<var>buffer</var> set to <a>relevant performance entry buffer</a>,
<var>name</var> set to `null`, and <var>type</var> set
to `type`.</p>
</section>
<section>
<h2><dfn>getEntriesByName()</dfn> method</h2>
<p>Returns a <a>PerformanceEntryList</a> object returned by
<a href="#filter-buffer-by-name-and-type"></a> algorithm with
<var>buffer</var> set to <a>performance entry buffer</a>,
<var>buffer</var> set to <a>relevant performance entry buffer</a>,
<var>name</var> set to `name`, and <var>type</var> set
to `null` if optional `entryType` is omitted, and <var>type</var> set
to `type` otherwise.</p>
Expand Down Expand Up @@ -303,9 +302,9 @@ <h2>The <dfn>PerformanceObserver</dfn> interface</h2>
<p>The `PerformanceObserver(callback)` constructor must create a new
<a>PerformanceObserver</a> object with <a>PerformanceObserverCallback</a>
set to <var>callback</var> and then return it.</p>
<p>A <dfn>registered performance observer</dfn> consists of an observer
(a <a>PerformanceObserver</a> object) and options (a
<a>PerformanceObserverInit</a> dictionary).</p>
<p>A <dfn>registered performance observer</dfn> is a <a>struct</a>
consisting of an <var>observer</var> (a <a>PerformanceObserver</a> object)
and <var>options</var> (a <a>PerformanceObserverInit</a> dictionary).</p>
<pre class="idl">
callback PerformanceObserverCallback = void (PerformanceObserverEntryList entries,
PerformanceObserver observer);
Expand All @@ -324,33 +323,33 @@ <h2>The <dfn>PerformanceObserver</dfn> interface</h2>
<p>The <dfn>observe()</dfn> method instructs the user agent to
<dfn>register the observer</dfn> and must run these steps:</p>
<ol data-link-for="PerformanceObserverInit">
<li>Remove all unsupported names from the entryTypes sequence.</li>
<li>If the resulting '<a>entryTypes</a>' sequence is an empty sequence, abort
these steps. The user agent SHOULD notify developers when the steps are
aborted. A console warning listing ignored unsupported names in `entryTypes`
might be appropriate, for example.
</li>
<li>If the list of <a>registered performance observer</a> objects
associated with the <a>ECMAScript global environment</a> of the
interface object's contains a <a>registered performance observer</a>
that is the <a>context object</a>, replace the <a>context object</a>'s
`options` with <var>options</var>.
<li>Let <var>entry types</var> be <var>options</var> <a>entryTypes</a>
sequence.</li>
<li>Remove all unsupported types from <var>entry types</var>. The user
agent SHOULD notify developers if <var>entry types</var> is modified.
For example, a console warning listing removed types might be appropriate.</li>
<li>If the resulting <var>entry types</var> sequence is an empty sequence,
abort these steps. The user agent SHOULD notify developers when the
steps are aborted to notify that registration has been aborted. For
example, a console warning might be appropriate.</li>
<li>If the <a>list of registered performance observer objects</a> of
<a>relevant global object</a> contains a <a>registered performance
observer</a> whose `observer` is the <a>context object</a>, replace its `options`, with <var>options</var>.
</li>
<li>Otherwise, append a new <a>registered performance observer</a>
object to the list of <a>registered performance observer</a> objects
associated with the <a>ECMAScript global environment</a> of the
interface object, with the <a>context object</a> as `observer` and
<var>options</var> as the `options`.
object to the <a>list of registered performance observer objects</a> of
<a>relevant global object</a>, with the <a>context object</a> as
`observer` and <var>options</var> as the `options`.
</li>
<li>If _options'_ <a for="PerformanceObserverInit">buffered</a> flag is
set, for each <dfn>entryType</dfn> of the `entryTypes` sequence:
<li>If <var>options</var>' <a>buffered</a> flag is set, for each
<var>entry type</var> in <var>entry types</var> sequence:
<ol>
<li>Let <dfn>entries</dfn> be the <a>PerformanceEntryList</a>
<li>Let <var>entries</var> be the <a>PerformanceEntryList</a>
object returned by the
<a href="#filter-buffer-by-name-and-type"></a> algorithm with
<var>buffer</var> set to <a>performance entry buffer</a>,
<var>buffer</var> set to <a>relevant performance entry buffer</a>,
<var>name</var> set to `null` and <var>type</var> set to
<var>entryType</var>.
<var>entry type</var>.
</li>
<li>Append <var>entries</var> to the <a>context object</a>'s
<a>observer buffer</a>.
Expand All @@ -361,9 +360,9 @@ <h2>The <dfn>PerformanceObserver</dfn> interface</h2>
<section>
<h2><dfn>disconnect()</dfn> method</h2>
<p>The <a>disconnect()</a> method must remove the <a>context object</a>
from the list of <a>PerformanceObserver</a> objects associated with the
<a>ECMAScript global environment</a> of the interface object, and also
empty <a>context object</a>'s <a>observer buffer</a>.</p>
from the <a>list of registered performance observer objects</a> of
<a>relevant global object</a>, and also empty <a>context object</a>'s
<a>observer buffer</a>.</p>
</section>
<section data-dfn-for="PerformanceObserverInit" data-link-for=
"PerformanceObserverInit">
Expand All @@ -376,7 +375,7 @@ <h2><dfn>PerformanceObserverInit</dfn> dictionary</h2>
</pre>
<dl>
<dt><dfn>entryTypes</dfn></dt>
<dd>A list of entry names to be observed. The list MUST NOT be empty
<dd>A list of entry types to be observed. The list MUST NOT be empty
and types not recognized by the user agent MUST be ignored.</dd>
</dl>
<dl>
Expand Down Expand Up @@ -462,11 +461,9 @@ <h2>Queue a <code>PerformanceEntry</code></h2>
The <a>task source</a> for the queued task is the <i>performance
timeline</i> task source.
<ol>
<li>Unset <a>performance observer task queued flag</a>.
</li>
<li>Let <i>notify list</i> be a copy of <a>ECMAScript global
environment</a>'s list of <a>registered performance observer</a>
objects.
<li>Unset <a>performance observer task queued flag</a> for the
<a>relevant global object</a>.</li>
<li>Let <i>notify list</i> be a copy of <a>relevant global object</a>'s <a>list of registered performance observer objects</a>.
</li>
<li>For each <a>PerformanceObserver</a> object <i>po</i> in <i>notify
list</i>, run these steps:
Expand Down Expand Up @@ -552,6 +549,8 @@ <h2>Dependencies</h2>
exception</dfn></li>
<li><dfn data-cite="!WHATWG-HTML#task-queue">task queue</dfn></li>
<li><dfn data-cite="!WHATWG-HTML#task-source">task source</dfn></li>
<li><dfn data-cite="!WHATWG-HTML#concept-relevant-global">relevant global object</dfn></li>
<li><dfn data-cite="!WHATWG-INFRA#struct">struct</dfn></li>
</ul>
</section>
<section id="privacy-security">
Expand Down

0 comments on commit 1aabb31

Please sign in to comment.