処理能 時列線 — Performance Timeline Level 2

3.1. `Performance^I ~interfaceに対する拡張

この節では、［ 処理能に関係する各種~属性, および［ `処理能時列線$からの処理能~計量~dataを取得する ］ために利用される 各種~method ］を~hostするように， `HR-TIME-2$r の `Performance$I ~interfaceを拡張する。 ◎ This extends the Performance interface [HR-TIME-2] and hosts performance related attributes and methods used to retrieve the performance metric data from the Performance Timeline.

partial interface `Performance$I {
    `PerformanceEntryList$I `getEntries$m();
    `PerformanceEntryList$I `getEntriesByType$m(`DOMString$ %type);
    `PerformanceEntryList$I `getEntriesByName$m(`DOMString$ %name, optional `DOMString$ %type);
};

typedef `sequence$<`PerformanceEntry$I> `PerformanceEntryList$I;

`PerformanceEntryList@I は、 `PerformanceEntry$I の連列を表現する — それは、開発者に~JS配列の便利~methodすべてを供する。 ◎ The PerformanceEntryList represents a sequence of PerformanceEntry, providing developers with all the convenience methods found on JavaScript arrays.

`getEntries()@m

被呼出時には、此れに`関連する処理能~entry~buffer$を ( ~NULL, ~NULL ) で`絞込んだ$結果を返さ~MUST。 ◎ 3.1.1 getEntries() method ◎ Returns a PerformanceEntryList object returned by 4.2 Filter buffer by name and type algorithm with buffer set to relevant performance entry buffer, and name and type set to null.

`getEntriesByType(type)@m

被呼出時には、此れに`関連する処理能~entry~buffer$を ( ~NULL, %type ) で`絞込んだ$結果を返さ~MUST。 ◎ 3.1.2 getEntriesByType() method ◎ Returns a PerformanceEntryList object returned by 4.2 Filter buffer by name and type algorithm with buffer set to relevant performance entry buffer, name set to null, and type set to type.

`getEntriesByName(name, type)@m

被呼出時には、此れに`関連する処理能~entry~buffer$を ( %name, %type （省略時は ~NULL） ) で`絞込んだ$結果を返さ~MUST。 ◎ 3.1.3 getEntriesByName() method ◎ Returns a PerformanceEntryList object returned by 4.2 Filter buffer by name and type algorithm with buffer set to relevant performance entry buffer, name set to name, and type set to null if optional entryType is omitted, and type set to type otherwise.

3.2. `PerformanceEntry^I ~interface

`PerformanceEntry$I ~interfaceは、種々の計量による処理能~dataを~hostする。 ◎ The PerformanceEntry interface hosts the performance data of various metrics.

[`Exposed$=(Window,Worker)]
interface `PerformanceEntry@I {
    readonly attribute `DOMString$           `name$m;
    readonly attribute `DOMString$           `entryType$m;
    readonly attribute `DOMHighResTimeStamp$I `startTime$m;
    readonly attribute `DOMHighResTimeStamp$I `duration$m;
    [`Default$] `object$ `toJSON$m();
};

`name@m

取得子は、此れの識別子を返さ~MUST。 この識別子は、一意になる必要はない。 ◎ This attribute MUST return an identifier for this PerformanceEntry object. This identifier does not have to be unique.

`entryType@m

取得子は、此れで表現される ~interface型 を述べる `DOMString^I を返さ~MUST。 ◎ This attribute MUST return the type of the interface represented by this PerformanceEntry object.

他の仕様で定義される `entryType^m 値の例には、次が挙げられる：

• `mark^l, `measure^l `USER-TIMING-2$r
• `navigation^l `NAVIGATION-TIMING-2$r
• `resource^l `RESOURCE-TIMING-2$r
• `longtask^l 【仕様は不明 — `paint^l `PAINT-TIMING$r ？】

◎ Note ◎ Example entryType values defined by other specifications include: "mark" and "measure" [USER-TIMING-2], "navigation" [NAVIGATION-TIMING-2], "resource" [RESOURCE-TIMING-2], and "longtask".

`startTime@m

取得子は、［ 此れの処理能~計量にて最初に記録された時刻印 ］を~~表現する `DOMHighResTimeStamp$I 値を返さ~MUST。 処理能~計量に開始-時刻の概念は適用されない場合、 0 を返すことにしてもヨイ。 ◎ This attribute MUST return the time value of the first recorded timestamp of this performance metric. If the startTime concept doesn't apply, a performance metric may choose to return a startTime of 0.

`duration@m

取得子は、［ 此れに記録される~event全体の所要時間 ］を~~表現する `DOMHighResTimeStamp$I 値を返さ~MUST。 これは概して，此れに［ 最初に記録された時刻印 ］から［ 最後に記録された時刻印 ］までの時間~差になる。 処理能~計量に所要時間の概念が適用されない場合、 0 を返すことにしてもヨイ。 ◎ This attribute MUST return the time value of the duration of the entire event being recorded by this PerformanceEntry. Typically, this would be the time difference between the last recorded timestamp and the first recorded timestamp of this PerformanceEntry. If the duration concept doesn't apply, a performance metric may choose to return a duration of 0.

`toJSON()@m

~call時には、 `WebIDL$r による`既定の~toJSON演算$を走らす。 ◎ When toJSON is called, run [WebIDL]'s default toJSON operation.

3.3. `PerformanceObserver^I ~interface

`PerformanceObserver$I ~interfaceを利用すれば、`処理能時列線$を観測して，新たな処理能~計量（ `PerformanceEntry$I ~obj）が記録される度に通知させれる。 また，任意選択で、すでに~buffer済みの処理能~計量も通知させれる。 ◎ The PerformanceObserver interface can be used to observe the Performance Timeline to be notified of new performance metrics as they are recorded, and optionally buffered performance metrics.

`PerformanceObserver$I ~objは、単に `処理能~観測器@ とも称される。 各 `処理能~観測器$には、次のものが結付けられる： ◎ Each PerformanceObserver has these associated concepts:

`~callback@

作成-時に設定される， `PerformanceObserverCallback$I ~callback。 ◎ A PerformanceObserverCallback set on creation.

`観測器~buffer@

`PerformanceEntryList$I ~obj。 初期~時は空とする。 ◎ A PerformanceEntryList object called the observer buffer that is initially empty.

`~options@

`PerformanceObserverInit$I 辞書, または ε （なし）。 初期~時は ε とする。 `登録-済み$である間は非 ε になる。 ◎ ↓↓

callback `PerformanceObserverCallback@I = void (
    `PerformanceObserverEntryList$I %entries,
    `PerformanceObserver$I %observer
);

[`Constructor$(`PerformanceObserverCallback$I %callback),
`Exposed$=(Window,Worker)]
interface `PerformanceObserver@I {
    void `observe$m(`PerformanceObserverInit$I %options);
    void `disconnect$m();
    `PerformanceEntryList$I `takeRecords$m();
};

注記： 処理能~overheadを最小限に保つためには、~appは，関心のある~event種別のみを申込んで、処理能~dataを観測する必要がなくなったなら，観測器を `disconnect()$m するべきである。 名前（ `name$m ）による絞込みは~supportされない — それは，暗黙的にすべての~event種別を申込むことになり、可能0ではあるが，大量の~eventを生成することになるので。 ◎ Note ◎ To keep the performance overhead to minimum the application should only subscribe to event types that it is interested in, and disconnect the observer once it no longer needs to observe the performance data. Filtering by name is not supported, as it would implicitly require a subscription for all event types — this is possible, but discouraged, as it will generate a significant volume of events.

dictionary `PerformanceObserverInit@I {
    required `sequence$<`DOMString$> `entryTypes$d;
    `boolean$ `buffered$d = false;
};

[`Exposed$=(Window,Worker)]
interface `PerformanceObserverEntryList@I {
    `PerformanceEntryList$I `getEntries$mO();
    `PerformanceEntryList$I `getEntriesByType$mO(`DOMString$ %type);
    `PerformanceEntryList$I `getEntriesByName$mO(`DOMString$ %name, optional `DOMString$ %type);
};

4.1. `PerformanceEntry^I を~queueする

1. %大域~obj ~LET `関連する大域~obj$ 【どの~objに`関連する大域~obj$かは、この~algoを呼出した文脈に依存する。】 ◎ ↓
2. %大域~obj の`処理能~観測器~list$内の ~EACH ( `処理能~観測器$ %観測器 ) に対し ⇒ ~IF［ %新たな~entry の `entryType$m 値 ~IN %観測器 の`~options$の `entryTypes^m ］ ⇒ %観測器 の`観測器~buffer$に %新たな~entry を付加する ◎ Let interested observers be an initially empty set of PerformanceObserver objects. ◎ For each registered performance observer (observer): ◎ • If observer's PerformanceObserverInit entryTypes includes new entry’s entryType value, append observer to interested observers. ◎ For each observer in interested observers: ◎ • Append new entry to observer buffer.
3. ~IF［ %処理能~entry~bufferに追加する~flag ~EQ ~ON ］ ⇒ %新たな~entry を %大域~obj の`処理能~entry~buffer$に追加する ◎ If the add to performance entry buffer flag is set, add new entry to the performance entry buffer.
4. ~IF［ %大域~obj の`処理能~観測器~task~queue済み~flag$ ~EQ ~ON ］ ⇒ ~RET ◎ If the performance observer task queued flag is set, terminate these steps.
5. %大域~obj の`処理能~観測器~task~queue済み~flag$ ~SET ~ON ◎ Set performance observer task queued flag.

6. 次の下位手続きを走らす`~taskを~queueする$ — この~task用の`~task源$は、 `処理能~時列線~task源@ とする： ◎ Queue a task that consists of running the following substeps. The task source for the queued task is the performance timeline task source.

   1. %大域~obj の`処理能~観測器~task~queue済み~flag$ ~SET ~OFF ◎ Unset performance observer task queued flag.
   2. %通知-~list ~LET ［ %大域~obj の`処理能~観測器~list$ ］の複製 ◎ Let notify list be a copy of relevant global object's list of registered performance observer objects.

   3. %通知-~list 内の~EACH ( `処理能~観測器$ %観測器 ) に対し： ◎ For each PerformanceObserver object po in notify list, run these steps:

      1. ~IF［ %観測器 の`観測器~buffer$は空である ］ ⇒ ~CONTINUE ◎ ↓
      2. %~entryたち ~LET %観測器 の`観測器~buffer$の複製 ◎ Let entries be a copy of po’s observer buffer.
      3. %観測器 の`観測器~buffer$を空にする ◎ Empty po’s observer buffer.

      4. 次を渡して %観測器 の`~callback$を~callする ⇒＃ 引数~list « %~entryたち, %観測器 », `~callback this 値$ %観測器

         この段にて例外が投出された場合は、その`例外を報告する$。

         ◎ If entries is non-empty, call po’s callback with entries as first argument and po as the second argument and callback this value. If this throws an exception, report the exception.

`処理能~時列線~task源$用の`~task~queue$は、低優先度の~queueである — ~UAは、処理能~監視~codeの影響0を最小限に抑えるため，可能0なら遊休中に処理するべきである。 ◎ The performance timeline task queue is a low priority queue that, if possible, should be processed by the user agent during idle periods to minimize impact of performance monitoring code.

4.2. ~bufferを ( %名前, %種別 ) で絞込む

1. %~list ~LET 空~list ◎ Let the list of entry objects be the empty PerformanceEntryList.

2. %~buffer 内の ~EACH ( `PerformanceEntry$I ~obj `~entry~obj@V ) に対し： ◎ For each PerformanceEntry object (entryObject) in the buffer, in chronological order with respect to startTime:

   1. ~IF［ %名前 ~NIN { ~NULL, `~entry~obj$V の `name$m 属性~値 ) ］ ⇒ ~CONTINUE ◎ If name is not null and entryObject's name attribute does not match name in a case-sensitive manner, go to next entryObject.
   2. ~IF［ %種別 ~NEQ { ~NULL, `~entry~obj$V の `entryType$m 属性~値 } ］ ⇒ ~CONTINUE ◎ If type is not null and entryObject's type attribute does not match type in a case-sensitive manner, go to next entryObject.
   3. %~list に `~entry~obj$V を追加する ◎ Add entryObject to the list of entry objects.
3. ~RET %~list ◎ Return the list of entry objects.