W3C

Smoothness Timing

This version:
http://www.w3.org/
Latest version:
http://www.w3.org/
Latest Editor's Draft:
https://dvcs.w3.org/
Previous version:
http://www.w3.org/
Editors:
Michael Blain, Google Inc.,
Nat Duca, Google Inc.,

Abstract

This specification defines an interface to help web developers measure the performance of their applications by giving them access to frame performance data to facilitate Smoothness (i.e. Frames per Second and Time to Frame) measurements.

Status of this document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This is a work in progress and may change without any notices.

Please send comments to public-web-perf@w3.org (archived) with [PerformanceTimeline] at the start of the subject line.

This document is produced by the Web Performance Working Group. The Web Performance Working Group is part of the Rich Web Clients Activity in the W3CInteraction Domain.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

  1. 1 Introduction
  2. 2 Conformance requirements
  3. 3 Terminology
  4. 4 Smoothness Timing
    1. 4.1 Introduction
    2. 4.2 Extensions to the Performance Interface
    3. 4.3 The PerformanceMainFrameTiming Interface
    4. 4.4 The PerformanceCompositeTiming Interface
  5. 5 Monotonic Clock
  6. 6 Privacy and Security
  7. Acknowledgements
  8. References

1 Introduction

This section is non-normative.

Web developers need the ability to assess and understand the performance characteristics of their applications. While JavaScript [ECMA262] provides a mechanism to approximate application Frames per Second (FPS) and Time to Frame (TTF) (by calling a nearly empty requestAnimationFrame in a loop), the precision of this method has a high variance. Some example situations where this returns misleading results are:

This document defines the PerformanceMainFrameTiming and PerformanceCompositeTiming interfaces, and extensions to the Performance interface, which expose frame performance data to be used for smoothness measurements.

2 Conformance requirements

All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in RFC2119. For readability, these words do not appear in all uppercase letters in this specification. [RFC2119]

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on user agents.

Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [Web IDL]

3 Terminology

The construction "a Foo object", where Foo is actually an interface, is sometimes used instead of the more accurate "an object implementing the interface Foo".

The term "JavaScript" is used to refer to ECMAScript [ECMA262], rather than the official term ECMAScript, since the term JavaScript is more widely known.

4 Smoothness Timing

4.1 Introduction

This section is non-normative

The PerformanceMainFrameTiming and PerformanceCompositeTiming interfaces and extensions to the Performance interface give web developers access to browser smoothness information so they can better measure the performance characteristics of their applications.

4.2 Extensions to the Performance Interface

  partial interface Performance {
    void clearSmoothnessTimings();
    void setSmoothnessTimingBufferSize(unsigned long maxSize);

    attribute Function onsmoothnesstimingbufferfull;
  };
    

clearSmoothnessTimings method

The method clearSmoothnessTimings clears the buffer used to store the current list of PerformanceMainFrameTiming resources.

No parameters

No return value

No additional exceptions

setSmoothnessTimingBufferSize method

The setSmoothnessTimingBufferSize method, when invoked, must set the maximum number of PerformanceMainFrameTiming resources that may be stored in the buffer to the value of the maxSize parameter.

If this method is not called, the user agent should store at least 150 PerformanceMainFrameTiming resources in the buffer, unless otherwise specified by the user agent.

if the maxSize parameter is less than the number of elements currently stored in the buffer, no elements in the buffer are to be removed. The maxSize parameter will apply only after the clearSmoothnessTimings method is called.

Parameters

in maxSize type of unsigned long

The maxSize parameter sets the maximum number of PerformanceMainFrameTiming resources that will be stored in the buffer.

No return value

No additional exceptions

onsmoothnesstimingbufferfull attribute

The callback onsmoothnesstimingbufferfull is triggered when the buffer used to store the list of PerformanceMainFrameTiming is full. The callback can be used to package existing PerformanceMainFrameTiming resources and clear the buffered PerformanceMainFrameTiming list. While executing the onsmoothnesstimingbufferfull callback, PerformanceMainFrameTiming will continue to be collected beyond the maximum limit of the resources allowed in the PerformanceMainFrameTiming interface until one of the following occurs:

  1. clearSmoothnessTimings is called - The PerformanceEntryList will begin with the n+1th item if it exists and the first n elements are released, where n is the maximum number of resources allowed in the PerformanceMainFrameTiming interface. If the n+1th item does not exist, the buffer is cleared. The max length of the PerformanceEntryList does not change unless otherwise specified by setSmoothnessTimingBufferSize.
  2. setSmoothnessTimingBufferSize is called - The PerformanceEntryList will extend and / or truncate to the buffer size specified.
  3. Neither clearSmoothnessTimings or setSmoothnessTimingBufferSize is called during the execution of the onsmoothnesstimingbufferfull callback - no updates are made to the PerformanceEntryList.

4.3 The PerformanceMainFrameTiming Interface

  interface PerformanceMainFrameTiming : PerformanceEntry {
    readonly attribute unsigned long sourceFrameNumber;
    readonly attribute double cpuTime;
  };
    

The PerformanceMainFrameTiming interface participates in the Performance Timeline and extends the following attributes of the PerformanceEntry interface:

The name attribute will return the name of the requesting document.

The entryType attribute will return the DOMString mainframe.

The startTime attribute will return a DOMHighResTimeStamp with current frame's beggining time value [High Resolution Time].

The duration attribute will return a DOMHighResTimeStamp with the duration of the frame, computed by subtracting the startTime of the next frame from startTime of the current frame.

sourceFrameNumber attribute

The sourceFrameNumber attribute must return the source frame number for the event. This is used to correlate PerformanceMainFrameTiming and PerformanceCompositeTiming events to measure time-to-frame delays. This may be null.

cpuTime attribute

The cpuTime attribute must return a [High Resolution Time] duration giving the total CPU time used to process this frame.

4.4 The PerformanceCompositeTiming Interface

  interface PerformanceCompositeTiming : PerformanceEntry {
    readonly attribute unsigned long sourceFrameNumber;
  };
    

The PerformanceCompositeTiming interface participates in the Performance Timeline and extends the following attributes of the PerformanceEntry interface:

The name attribute will return the name of the requesting document.

The entryType attribute will return the DOMString composite.

The startTime attribute will return a DOMHighResTimeStamp with event's time value [High Resolution Time].

The duration attribute will return a DOMHighResTimeStamp of value 0.

sourceFrameNumber attribute

The sourceFrameNumber attribute must return the last known source frame number for the event. This is used to correlate PerformanceMainFrameTiming and PerformanceCompositeTiming events to measure time-to-frame delays.

5 Monotonic Clock

The time values stored within the interface must monotonically increase to ensure they are not affected by adjustments to the system clock. The difference between any two chronologically recorded time values must never be negative. The user agent must record the system clock at the beginning of the navigation and define subsequent time values in terms of a monotonic clock measuring time elapsed from the beginning of the navigation.

6 Privacy and Security

This section is non-normative.

The interfaces defined in this specification expose potentially sensitive timing information on specific JavaScript activity of a page. However, unlike other interfaces defined in the Performance Timeline, the interfaces defined in this specification do not have any restrictions on sharing timing information through script. This is because the web platform has been designed with the invariant that any script included on a page has the same access as any other script included on that page regardless of the origin of the script.

Acknowledgements

Thanks to Enne Walker, Rick Byers and Chris Harrelson for their helpful comments.

References

[IETF RFC 2119]
Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner, Author. Internet Engineering Task Force, March 1997. Available at http://www.ietf.org/rfc/rfc2119.txt.
[ECMA-262]
ECMAScript Language Specification, 5.1 Edition. ECMA International, Standard ECMA-262, June 2011. This version of the ECMAScript Language is available from http://www.ecma-international.org/publications/standards/Ecma-262.htm.
[Navigation Timing]
Navigation Timing, Zhiheng Wang, Editor. World Wide Web Consortium, July 2012. This version of the Navigation Timing specification is available from http://www.w3.org/TR/2012/PR-navigation-timing-20120726/. The latest version of Navigation Timing is available at http://www.w3.org/TR/navigation-timing/.
[Performance Timeline]
Performance Timeline, Jatinder Mann, et al, Editors. World Wide Web Consortium, July 2012. This version of the Performance Timeline specification is available from http://www.w3.org/TR/2012/CR-performance-timeline-20120726/. The latest version of Performance Timeline is available at http://www.w3.org/TR/performance-timeline/.
[High Resolution Time]
High Resolution Time, Jatinder Mann, Editor. World Wide Web Consortium, May 2012. This version of the High Resolution Time specification is available from http://www.w3.org/TR/2012/CR-hr-time-20120522/. The latest version of High Resolution Time is available at http://www.w3.org/TR/hr-time/.
[Web IDL]
Web IDL, Cameron McCormack, Editor. World Wide Web Consortium, April 2012. This version of the Web IDL specification is available from http://www.w3.org/TR/2012/CR-WebIDL-20120419/. The latest version of Web IDL is available at http://www.w3.org/TR/WebIDL/.