Skip to content
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.

Sign up for GitHub

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

Closed
wants to merge 8 commits into from
+75 −30
Closed

Add entryType-specific parameters for observe() #104

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
9749677
Add entryType-specific parameters for observe()
npm1 Jul 24, 2018
b5be310
Refer to algorithm instead of closure
npm1 Jul 24, 2018
7076b35
Feedback
npm1 Jul 30, 2018
c86b62e
Update index.html
npm1 Aug 8, 2018
7c8a32f
Add supported entry types
npm1 Aug 10, 2018
6a8423d
supported -> observed
npm1 Aug 27, 2018
3adf11d
Feedback
npm1 Aug 28, 2018
c4f8432
Update index.html
npm1 Sep 7, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 75 additions & 30 deletions index.html
View file
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.
Copy link
Contributor

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?

Copy link
Contributor Author

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.

observer.observe({
entryTypes: ["resource", "mark", "measure"],
buffered: true
entryTypes: ["mark", "measure"],
resource : {buffered: true}
});
&lt;/script&gt;
&lt;/body&gt;
@@ -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>'
Copy link
Contributor

Choose a reason for hiding this comment

The 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.
e.g. "Let options be the input PerformanceObserverInit object" or something along those lines

Copy link
Contributor

Choose a reason for hiding this comment

The 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

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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>:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

options is a PerformanceObserverInit, right? Or is it PerformanceEntryObserverOptions?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, but buffered would be inside the PerformanceEntryObserverOptions corresponding to that entry type (if it exists), which is itself inside the PerformanceObserverInit options. I moved this flag so that it can be an entryType-specific parameter.

<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&lt;DOMString&gt; entryTypes;
Copy link
Contributor Author

Choose a reason for hiding this comment

The 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
Copy link
Member

Choose a reason for hiding this comment

The 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?

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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>
Copy link
Member

Choose a reason for hiding this comment

The 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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The 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.