-
Notifications
You must be signed in to change notification settings - Fork 27
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add entryType-specific parameters for observe() #104
Changes from all commits
9749677
b5be310
7076b35
c86b62e
7c8a32f
6a8423d
3adf11d
c4f8432
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -151,16 +151,18 @@ <h2>Introduction</h2> | |
}; | ||
return JSON.stringify(obj, null, 2); | ||
}) | ||
// Display them to the console | ||
// Display them to the console. | ||
.forEach(console.log); | ||
// maybe disconnect after processing the events. | ||
// Maybe disconnect after processing the events. | ||
observer.disconnect(); | ||
}); | ||
// retrieve buffered events and subscribe to new events | ||
// for Resource-Timing and User-Timing | ||
// Subscribe to new events for User-Timing (marks and measures) via the | ||
// |entryTypes| array. The entry-type specific flags are set to their | ||
// default values for these entry types. Also subscribe to and retrieve | ||
// buffered events from Resource-Timing. | ||
observer.observe({ | ||
entryTypes: ["resource", "mark", "measure"], | ||
buffered: true | ||
entryTypes: ["mark", "measure"], | ||
resource : {buffered: true} | ||
}); | ||
</script> | ||
</body> | ||
|
@@ -298,6 +300,9 @@ <h2>The <dfn>PerformanceObserver</dfn> interface</h2> | |
<li> A <a>PerformanceEntryList</a> object called the <dfn>observer | ||
buffer</dfn> that is initially empty. | ||
</li> | ||
<li>A sequence of strings called <dfn>observed entry types</dfn> that is | ||
initially empty. | ||
</li> | ||
</ul> | ||
<p>The `PerformanceObserver(callback)` constructor must create a new | ||
<a>PerformanceObserver</a> object with <a>PerformanceObserverCallback</a> | ||
|
@@ -323,29 +328,41 @@ <h2>The <dfn>PerformanceObserver</dfn> interface</h2> | |
but discouraged, as it will generate a significant volume of events.</p> | ||
<section> | ||
<h2><dfn>observe()</dfn> method</h2> | ||
<p>The <a>observe()</a> method instructs the user agent to | ||
<dfn>register the observer</dfn> and must run these steps:</p> | ||
<p>The <a>observe()</a> method receives a <a>PerformanceObserverInit</a> | ||
<var>options</var> dictionary. This method instructs the user agent to | ||
<dfn>register the observer</dfn> and must run these steps:</p> | ||
<ol data-link-for="PerformanceObserverInit"> | ||
<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, | ||
<li>Set <a>observed entry types</a> to a copy of <var>options</var>' | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think it'd be better to explicitly state what the options variable is a line above that. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Also, I think you meant "observed entry types" to be a var, not a link There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I've added what observer() receives. I really do mean a link to the associated concept of the PerformanceObserver, not a local var. So is correct in this context. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. *so <a> is correct |
||
<a>entryTypes</a> sequence. | ||
</li> | ||
<li>For each key <var>entryType</var> in the <var>options</var> dictionary that | ||
is not <a>entryTypes</a>, add the string <var>entryType</var> to | ||
<a>observed entry types</a>. | ||
</li> | ||
<li> For each string <var>entryType</var> in <a>observed entry types</a>, | ||
remove <var>entryType</var> from <a>observed entry types</a> if it is | ||
unsupported by the user agent. The user agent SHOULD notify developers if | ||
<a>observed entry types</a> is modified at this step. For example, a | ||
console warning listing removed types might be appropriate. | ||
</li> | ||
<li>If <a>observed entry types</a> 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> | ||
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>. | ||
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 <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 <var>options</var>' <a>buffered</a> flag is set, for each | ||
<var>entry type</var> in <var>entry types</var> sequence: | ||
<li>For each <var>entry type</var> in <a>observed entry types</a>, if the | ||
<a data-link-for="PerformanceEntryObserverOptions">buffered</a> flag is set | ||
in <var>options</var>' dictionary named <var>entry type</var>: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yes, but |
||
<ol> | ||
<li>Let <var>entries</var> be the <a>PerformanceEntryList</a> | ||
object returned by the | ||
|
@@ -366,14 +383,34 @@ <h2><dfn>PerformanceObserverInit</dfn> dictionary</h2> | |
<pre class="idl"> | ||
dictionary PerformanceObserverInit { | ||
required sequence<DOMString> entryTypes; | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I'm thinking we may want to remove the 'required' from |entryTypes| as well as you could specify what you want to observe using the other dictionaries. |
||
boolean buffered = false; | ||
PerformanceEntryObserverOptions fallback; | ||
}; | ||
</pre> | ||
<dl> | ||
<dt><dfn>entryTypes</dfn></dt> | ||
<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> | ||
<dt><dfn>fallback</dfn></dt> | ||
<dd>A dictionary containing the parameters to be applied to all entries | ||
observed. These parameters are overriden by entryType-specific dictionaries. | ||
That is, if a parameter is present in the `fallback` dictionary but also in | ||
the `mark` dictionary, then the value of the `mark` dictionary will be used | ||
for entries whose <a data-lt="PerformanceEntry.entryType">entryType</a> is `mark`.</dd> | ||
</dl> | ||
<p class="note">Whenever a new kind of <a>PerformanceEntry</a> is defined, | ||
the <a>PerformanceObserverInit</a> dictionary should be augmented to | ||
include a new optional <a>PerformanceEntryObserverOptions</a> dictionary | ||
whose key is the new <a data-lt="PerformanceEntry.entryType"> | ||
entryType</a>.</p> | ||
</section> | ||
<section data-dfn-for="PerformanceEntryObserverOptions" data-link-for= | ||
"PerformanceEntryObserverOptions"> | ||
<h2><dfn>PerformanceEntryObserverOptions</dfn> dictionary</h2> | ||
<pre class="idl"> | ||
dictionary PerformanceEntryObserverOptions { | ||
boolean buffered = false; | ||
}; | ||
</pre> | ||
<dl> | ||
<dt><dfn>buffered</dfn></dt> | ||
<dd>A flag to indicate whether buffered entries should be queued into | ||
|
@@ -436,30 +473,38 @@ <h2><dfn>disconnect()</dfn> method</h2> | |
<h2>Processing</h2> | ||
<section data-link-for="PerformanceObserver"> | ||
<h2>Queue a <code>PerformanceEntry</code></h2> | ||
<p><i>Specifications</i> of performance entries may define an algorithm | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I believe our plan was to have this on by default for all types prior to onload, and no buffering afterwards. If that's the case, I believe we wouldn't need this — correct? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This is about the queue algorithm, not about buffering. An example of where we need this is LongTasks thresholds: we need the spec to provide an algorithm to determine if an entry should be added to an observer (look at the entry's duration, compare with the observer's threshold). |
||
<var>should append to observer</var> which receives a <a>PerformanceEntry</a> and | ||
a <a>PerformanceObserver</a> as input and returns a boolean specifying whether the | ||
observer should be notified of the entry. | ||
<p>To <dfn>queue a PerformanceEntry</dfn> (<var>new entry</var>) with an | ||
optional <var>add to performance entry buffer</var> flag, which is unset | ||
by default, run these steps:</p> | ||
optional <var>add to performance entry buffer</var> flag, which is unset by | ||
default, run these steps:</p> | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This step should be with respect to before or after onload, not the passed in flag. For context, we ruled out the flag approach because it would, once again, require updating every upstream spec to have this on by default.. and I can't think of cases where we'd want this to be off by default for before-onload. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Sure, but I haven't added this flag, it's currently in the spec. How about we do a separate PR for this independent change? |
||
<ol> | ||
<li>Let <i>interested observers</i> be an initially empty set of | ||
<li>Let <var>interested observers</var> be an initially empty set of | ||
<a>PerformanceObserver</a> objects. | ||
</li> | ||
<li>For each <a>registered performance observer</a> (<i>observer</i>): | ||
<li>For each <a>registered performance observer</a> (<var>observer</var>), append | ||
<var>observer</var> to <var>interested observers</var> if all of the following | ||
conditions are met: | ||
<ol> | ||
<li>If <i>observer</i>'s <a>PerformanceObserverInit</a> <a data-lt= | ||
"PerformanceObserverInit.entryTypes">entryTypes</a> includes <i>new | ||
entry</i>’s <a data-lt="PerformanceEntry.entryType">entryType</a> | ||
value, append <i>observer</i> to <i>interested observers</i>. | ||
<li><var>new entry</var>’s <a data-lt="PerformanceEntry.entryType">entryType</a> | ||
value is in <var>observer</var>'s <a>observed entry types</a>. | ||
</li> | ||
<li><var>should append to observer</var>(<var>new entry</var>, | ||
<var>observer</var>) returns true, if defined by the <i>specification</i> of | ||
the corresponding <a data-lt="PerformanceEntry.entryType">entryType</a>. | ||
</li> | ||
</ol> | ||
</li> | ||
<li>For each <i>observer</i> in <i>interested observers</i>: | ||
<li>For each <var>observer</var> in <var>interested observers</var>: | ||
<ol> | ||
<li>Append <i>new entry</i> to <a>observer buffer</a>. | ||
<li>Append <var>new entry</var> to <var>observer</var>'s <a>observer buffer</a>. | ||
</li> | ||
</ol> | ||
</li> | ||
<li>If the <var>add to performance entry buffer</var> flag is set, add | ||
<i>new entry</i> to the <a>performance entry buffer</a>. | ||
<var>new entry</var> to the <a>performance entry buffer</a>. | ||
</li> | ||
<li>If the <a>performance observer task queued flag</a> is set, terminate | ||
these steps. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Where's the resource-timing part? It's no longer observed, is it?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You mean in the description, or in the code? In the description, we have at the end "Also subscribe to and retrieve buffered events from Resource-Timing." In the code, per this PR the existence of a dictionary 'resource' implies that this PerformanceObserver observes that entry type.