1. 序論
~INFORMATIVE~web開発者は、~appの処理能~特性について，~accessし, 理解する能を必要とする。 ~JS `ECMA-262$r は，~appの遅延を測定する仕組み（ `Date.now()^m ~methodで現在の時刻印を検索取得する）を供するが、この時刻印の精度は~UAによってまちまちである。 ◎ Web developers need the ability to assess and understand the performance characteristics of their applications. While JavaScript [ECMA-262] provides a mechanism to measure application latency (retrieving the current timestamp from the Date.now() method), the precision of this timestamp varies between user agents.
この文書は、高精度かつ単調増加する時刻印を公開する［ `PerformanceMark$I, `PerformanceMeasure$I ］~interfaceを定義し， `Performance$I ~interfaceを拡張して、開発者が~appの処理能をより良く測定できるようにする。 ◎ This document defines the PerformanceMark and PerformanceMeasure interfaces, and extensions to the Performance interface, which expose a high precision, monotonically increasing timestamp so that developers can better measure the performance characteristics of their applications.
次の~scriptに，開発者が~scriptに関係する計時~dataを得るために、この文書で定義される~interfaceを利用する例を示す： ◎ Example 1 ◎ The following script shows how a developer can use the interfaces defined in this document to obtain timing data related to developer scripts.
async function run() {
performance.mark("startTask1");
await doTask1(); /*
何らかの開発者~code
◎
Some developer code
*/
performance.mark("endTask1");
performance.mark("startTask2");
await doTask2(); /*
何らかの開発者~code
◎
Some developer code
*/
performance.mark("endTask2");
/*
~logに出す
◎
Log them out
*/
const %entries = performance.getEntriesByType("mark");
for (const %entry of %entries) {
console.table(%entry.toJSON());
}
}
run();
`PERFORMANCE-TIMELINE-2$r は、記録された計量を検索取得するときに利用できる 2 つの仕組みを定義する：
- `getEntries()$m, `getEntriesByType()$m ~methodは、ある時点の特定0の計量を名前で検索取得するときに適する。
- `PerformanceObserver$I ~interfaceは、新たな計量が可用になり次第，その通知を受取る場合に最適化されている。
2. 適合性
【 この節の内容は W3C 日本語訳 共通ページ に委譲 】
【この訳に固有の表記規約】
この訳の，~algoや定義の記述に利用されている各種記号（ ~LET, ~EQ, ~IF, ~EACH (…), ~RET, 等々）の意味や定義の詳細は、~SYMBOL_DEF_REFを~~参照されたし。
次の非公式な用語を導入する：
- `時刻~値@ ／ `所要時間@ と記されたときは、何らかの 時刻 ／ 時間~差 を表現する `DOMHighResTimeStamp$I 型の値を表すとする。 `HR-TIME-2$r
3. 利用者~計時
3.1. `Performance^I ~interfaceに対する拡張
`Performance$I ~interfaceは、`HR-TIME-2$r にて定義される。 ◎ The Performance interface is defined in [HR-TIME-2].
partial interface `Performance$I {
void `mark$m(DOMString %markName);
void `clearMarks$m(optional DOMString %markName);
void `measure$m(
`DOMString$ %measureName,
optional `DOMString$ %startMark,
optional `DOMString$ %endMark
);
void `clearMeasures$m(optional `DOMString$ %measureName);
};
- `mark(markName)@m ◎ 3.1.1 mark() method
- この~methodは、時刻印に所与の名前（ “~mark” ）を結付けて格納する。 ◎ Stores a timestamp with the associated name (a "mark").＼
-
被呼出時には、次を走らせ~MUST： ◎ It MUST run these steps:
- ~IF［ `大域~obj$は `Window$I ~objである ］~AND［ %markName は `PerformanceTiming$I ~interface内のある`読専$属性の名前である ］ ⇒ ~THROW `SyntaxError$E ◎ If the global object is a Window object and markName uses the same name as a read only attribute in the PerformanceTiming interface, throw a SyntaxError.
- %~entry ~LET 各種~属性が次のように設定された新たな `PerformanceMark$I ~obj ⇒＃ `name^m ~SET %markName, `entryType^m ~SET `mark^l, `startTime^m ~SET `現在の高分解能~時刻$, `duration^m ~SET 0 ◎ Create a new PerformanceMark object (entry). • Set entry's name attribute to markName. • Set entry's entryType attribute to DOMString "mark". • Set entry's startTime attribute to the value that would be returned by the Performance object's now() method. • Set entry's duration attribute to 0.
- `処理能~entryを~queueする$( %~entry ) ◎ Queue entry.
- %~entry を`処理能~entry~buffer$に追加する ◎ Add entry to the performance entry buffer. ◎ Return undefined.
- `clearMarks(markName)@m ◎ 3.1.2 clearMarks() method
- この~methodは、格納-済み時刻印のうち，所与の名前が結付けられたものを除去する。 ◎ Removes the stored timestamp with the associated name.＼
- 被呼出時には、`処理能~entry~buffer$から，次を満たす `PerformanceMark$I ~objすべてを除去し~MUST ⇒ %markName は与えられていないならば無条件 ／ ~ELSE_ `name^m ~EQ %markName なるもの ◎ It MUST run these steps: ◎ If markName is omitted, remove all PerformanceMark objects from the performance entry buffer. ◎ Otherwise, remove all PerformanceMark objects listed in the performance entry buffer whose name matchesmarkName. ◎ Return undefined.
- `measure(measureName, startMark, endMark)@m ◎ 3.1.3 measure() method
- この~methodは、 2 つの~markの間の`所要時間$（ “測定” ）に所与の名前を結付けて格納する。 ◎ Stores the DOMHighResTimeStamp duration between two marks along with the associated name (a "measure").＼
-
被呼出時には、次を走らせ~MUST： ◎ It MUST run these steps:
- %終端~時刻 ~LET ［ %endMark は与えられていないならば`現在の高分解能~時刻$ ／ ~ELSE_ `名前を時刻印に変換する$( %endMark ) の結果 ］ ◎ Let end time be 0. ◎ If endMark is omitted, let end time be the value that would be returned by the Performance object's now() method. Otherwise: • If endMark has the same name as a read only attribute in the PerformanceTiming interface, let end time be the value returned by running the convert a name to a timestamp algorithm with name set to the value of endMark. • Otherwise let end time be the value of the startTime attribute from the most recent occurrence of a PerformanceMark object in the performance entry buffer whose name matches the value of endMark. If no matching entry is found, throw a SyntaxError.
- %始端~時刻 ~LET ［ %startMark は与えられていないならば 0 ／ ~ELSE_ `名前を時刻印に変換する$( %startMark ) の結果 ］ ◎ If startMark is omitted, let start time be 0. Otherwise: • If startMark has the same name as a read only attribute in the PerformanceTiming interface, let start time be the value returned by running the convert a name to a timestamp algorithm with name set to startMark. • Otherwise let start time be the value of the startTime attribute from the most recent occurrence of a PerformanceMark object in the performance entry buffer whose name matches the value of startMark. If no matching entry is found, throw a SyntaxError.
- %~entry ~LET 各種~属性が次のように設定された新たな `PerformanceMeasure$I ~obj ⇒＃ `name^m ~SET %measureName, `entryType^m ~SET `measure^l, `startTime^m ~SET %始端~時刻, `duration^m ~SET %終端~時刻 − %始端~時刻 （負にもなり得る） ◎ Create a new PerformanceMeasure object (entry). • Set entry's name attribute to measureName. • Set entry's entryType attribute to DOMString "measure". • Set entry's startTime attribute to start time. • Set entry's duration attribute to the duration from start time to end time. The resulting duration value MAY be negative.
- `処理能~entryを~queueする$( %~entry ) ◎ Queue entry.
- `処理能~entry~buffer$に %~entry を追加する ◎ Add entry to the performance entry buffer. ◎ Return undefined.
- `clearMeasures(measureName)@m ◎ 3.1.4 clearMeasures() method
- この~methodは、所与の名前が結付けられた，格納-済み時刻印を除去する。 ◎ Removes stored timestamp with the associated name.＼
- 被呼出時には、`処理能~entry~buffer$から，次を満たす `PerformanceMeasure$I ~objすべてを除去し~MUST ⇒ %measureName は与えられていないならば無条件 ／ ~ELSE_ `name^m ~EQ %measureName なるもの ◎ It MUST run these steps: ◎ If measureName is omitted, remove all PerformanceMeasure objects in the performance entry buffer. ◎ Otherwise remove all PerformanceMeasure objects listed in the performance entry buffer whose name matches measureName. ◎ Return undefined.
3.2. `PerformanceMark^I ~interface
`PerformanceMark$I ~interfaceは、 `mark()$m ~methodを介して作成された~markも`処理能時列線$に公開する。 ◎ The PerformanceMark interface also exposes marks created via the performance.mark method to the Performance Timeline.
[Exposed=(Window,Worker)]
interface `PerformanceMark@I : `PerformanceEntry$I {
};
`PerformanceMark$I ~interfaceは `PerformanceEntry$I ~interfaceの次の属性を拡張する： ◎ The PerformanceMark interface extends the following attributes of the PerformanceEntry interface:
- `name^m
- ~mark名を返さ~MUST。 ◎ The name attribute must return the mark's name.
- `entryType^m
- 文字列 `mark^l を返さ~MUST。 ◎ The entryType attribute must return the DOMString "mark".
- `startTime^m
- ~markの`時刻~値$を返さ~MUST。 ◎ The startTime attribute must return a DOMHighResTimeStamp with the mark's time value.
- `duration^m
- `所要時間$ 0 を返さ~MUST。 ◎ The duration attribute must return a DOMHighResTimeStamp of value 0.
3.3 `PerformanceMeasure^I ~interface
`PerformanceMeasure$I ~interfaceは、 `measure()$m ~methodにより作成された測定も`処理能時列線$に公開する。 ◎ The PerformanceMeasure interface also exposes measures created via the performance.measure method to the Performance Timeline.
[Exposed=(Window,Worker)]
interface `PerformanceMeasure@I : `PerformanceEntry$I {
};
`PerformanceMeasure$I ~interfaceは、 `PerformanceEntry$I ~interfaceの次の属性を拡張する： ◎ The PerformanceMeasure interface extends the following attributes of the PerformanceEntry interface:
- `name^m
- 測定の名前を返さ~MUST。 ◎ The name attribute must return the measure's name.
- `entryType^m
- 文字列 `measure^l を返さ~MUST。 ◎ The entryType attribute must return the DOMString "measure".
- `startTime^m
- 測定の始端~markの`時刻~値$を返さ~MUST。 ◎ The startTime attribute must return a DOMHighResTimeStamp with the measure's start mark.
- `duration^m
- 測定の`所要時間$を返さ~MUST。 ◎ The duration attribute must return a DOMHighResTimeStamp with the duration of the measure.
4. 処理
`名前を時刻印に変換する@ ときは、所与の ( 文字列 %名前 ) に対し，次の手続きを走らす： ◎ 4.1. Convert a name to a timestamp ◎ To convert a name to a timestamp given a name＼
-
~IF［ %名前 は `PerformanceTiming$I ~interface内のある`読専$属性の名前である ］： ◎ that is a read only attribute in the PerformanceTiming interface, run these steps:
- ~IF［ `大域~obj$は `Window$I ~objでない ］ ⇒ ~THROW `SyntaxError$E ◎ If the global object is not a Window object, throw a SyntaxError.
- ~IF［ %名前 ~EQ `navigationStart^l ］ ⇒ ~RET 0 ◎ If name is navigationStart, return 0.
- %始端~時刻 ~LET `PerformanceTiming$I ~interfaceの `navigationStart$m 値 ◎ Let startTime be the value of navigationStart in the PerformanceTiming interface.
- %終端~時刻 ~LET `PerformanceTiming$I ~interfaceの %名前 属性の値 ◎ Let endTime be the value of name in the PerformanceTiming interface.
- ~IF［ %終端~時刻 ~EQ 0 ］ ⇒ ~THROW `InvalidAccessError$E ◎ If endTime is 0, throw an InvalidAccessError.
- ~RET %終端~時刻 − %始端~時刻 ◎ Return result of subtracting startTime from endTime.
`NAVIGATION-TIMING$r にて定義される `PerformanceTiming$I ~interfaceは、今や廃用にされたものと見なされている。 `PerformanceTiming$I ~interfaceからの名前の利用は，後方互換であり続けるよう~supportされるが、将来に，この機能性を `NAVIGATION-TIMING-2$r に定義される `PerformanceNavigationTiming$I （あるいは他の~interface）内の名前にまで拡張する計画は無い。 ◎ The PerformanceTiming interface was defined in [[NAVIGATION-TIMING]] and is now considered obsolete. The use of names from the PerformanceTiming interface is supported to remain backwards compatible, but there are no plans to extend this functionality to names in the PerformanceNavigationTiming interface defined in [[NAVIGATION-TIMING-2]] (or other interfaces) in the future.
-
~IF［ `処理能~entry~buffer$内の `PerformanceMark$I ~objに［ その `name^m 属性の値 ~EQ %名前 ］なるものはある ］ ⇒ ~RET それらの~objの `startTime^m 属性~値のうち，最も近過去を指す値
【 記述を集約するため、この訳では，この手続きを利用している他所の記述を この段と次の段に移動している。 】
- ~THROW `SyntaxError$E
5. ~privacyと保安
~INFORMATIVEこの仕様に定義される~interfaceは、~page上の特定の~JS活動を感知し得る計時~情報を公開する。 高分解能な計時~情報を公開する際の~privacyと保安の考慮点については `HR-TIME-2$r を~~参照されたし。 ◎ The interfaces defined in this specification expose potentially sensitive timing information on specific JavaScript activity of a page. Please refer to [HR-TIME-2] for privacy and security considerations of exposing high-resolution timing information.
~web~platformは、同じ~pageに含められれた どの~scriptも，それら~scriptの生成元（ origin ）に関わらず 同じ~accessを有する、という不変則の下に設計されているので、この仕様に定義される~interfaceは，［ 計時~情報を記録する ／ 記録された計時~情報を検索取得する ］ときに制約を課すものではない。 すなわち、~pageに含められた~scriptにより記録された利用者~計時~markや測定は、同じ~pageで走っている他のどの~scriptからも，その生成元に関わらず読取れる。 ◎ 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 the same page, regardless of the origin of either scripts, the interfaces defined by this specification do not place any restrictions on recording or retrieval of recorded timing information - i.e. a user timing mark or measure recorded by any script included on the page can be read by any other script running on the same page, regardless of origin.