1. Introduction

This section is non-normative.

The ECMAScript Language specification [ECMA-262] defines the Date object as a time value representing time in milliseconds since 01 January, 1970 UTC. For most purposes, this definition of time is sufficient as these values represent time to millisecond precision for any instant that is within approximately 285,616 years from 01 January, 1970 UTC. The DOMTimeStamp is defined similarly [WebIDL].

In practice, these definitions of time are subject to both clock skew and adjustment of the system clock. The value of time may not always be monotonically increasing and subsequent values may either decrease or remain the same.

For example, the following script may log a positive number, negative number, or zero.

var mark_start = Date.now();
doTask(); // Some task
if (window.console) window.console.log('Duration of task: ' + (Date.now() - mark_start));

For certain tasks this definition of time may not be sufficient as it does not allow for sub-millisecond resolution and is subject to system clock skew. For example,

• When attempting to accurately measure the elapsed time of navigating to a Document, fetching of resources or execution of script, a monotonically increasing clock with sub-millisecond resolution is desired.
• When calculating the animation state from script, developers will need to accurately know the amount of time that has elapsed in the animation in order to properly update the next scene of the animation.
• When calculating the frame rate of a script based animation, developers will need sub-millisecond resolution in order to determine if an animation is drawing at 60 FPS. Without sub-millisecond resolution, a developer can only determine if an animation is drawing at 58.8 FPS or 62.5 FPS.
• In order to cue audio to a specific point in an animation or ensure that the audio is synchronized with the animation, developers will need to accurately know the amount of time elapsed in the animation and audio.

This specification does not propose changing the behavior of Date.now() [ECMA-262] as it is genuinely useful in determining the current value of the calendar time and has a long history of usage. The DOMHighResTimeStamp type and the now method of the Performance interface resolve the issues summarized in this section by providing a monotonically increasing time value in sub-millisecond resolution.

// ---- worker.js -----------------------------
// Shared worker script
onconnect = function(e) {
  var port = e.ports[0];
  port.onmessage = function(e) {
    // Time execution in worker
    var task_start = performance.now();
    result = runSomeWorkerTask();
    var task_end = performance.now();

    port.postMessage({
       'task': 'Some worker task',
       'start_time': task_start,
       'end_time': task_end,
       'result': result
    });
  }
}

// ---- application.js ------------------------
// Timing tasks in the document
var task_start = performance.now();
result = runSomeWorkerTask();
var task_end = performance.now();

plotEventOnTimeline({
  'task': 'Some document task',
  'start_time': task_start,
  'end_time': task_end,
  'result': result
});

// Translating worker timestamps into document's time origin
var worker = new SharedWorker('worker.js');
worker.port.onmessage = function (event) {
  var msg = event.data;

  // translate timestamps into document's time origin
  msg.start_time = performance.translateTime(msg.start_time, worker);
  msg.end_time = performance.translateTime(msg.end_time, worker);

  // plot the results on document's timeline
  plotEventOnTimeline(msg);
}