処理能 時列線 — 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

被呼出時には、次の結果を返すモノトスル ⇒ `~bufferを絞込む$( 此れに`関連する処理能~entry~buffer$, ~NULL, ~NULL ) ◎ 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

被呼出時には、次の結果を返すモノトスル ⇒ `~bufferを絞込む$( 此れに`関連する処理能~entry~buffer$, ~NULL, %type ) ◎ 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

被呼出時には、次の結果を返すモノトスル ⇒ `~bufferを絞込む$( 此れに`関連する処理能~entry~buffer$, %name, %type （省略時は ~NULL） ) ◎ 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

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

`entryType@m

取得子は、此れで表現される ~interface型 を述べる `DOMString^I を返すモノトスル。 ◎ 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 値を返すモノトスル。 処理能~計量に開始-時刻の概念は適用されない場合、 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 値を返すモノトスル。 これは概して，此れに［ 最初に記録された時刻印 ］から［ 最後に記録された時刻印 ］までの時間~差になる。 処理能~計量に所要時間の概念が適用されない場合、 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@pO

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

`~buffer@pO

`PerformanceEntryList$I ~obj。 この~objが表現する連列は、初期~時は空とする。 ◎ A PerformanceEntryList object called the observer buffer that is initially empty.

`種別@pO

次のいずれか — 初期~時は `未定義^i とする 【`登録-済み$になった時点で、他の値に更新される】 ⇒ `未定義^i ／ `一個^i ／ `複数個^i ◎ A DOMString observer type which is initially "undefined".

`~options~list@pO

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

【 原文では、 “登録-済み処理能~観測器” という別個の構造体を定義して，それに — `処理能~観測器$への参照とともに — `~options~list$pOを保たせているが、この構造体は，実質的に［ 処理能~観測器は`処理能~観測器~list$内に含まれるかどうか ］の区別を表現するだけに過ぎず，無為に冗長なので、この訳では単純化している。 】

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

[`Constructor$(`PerformanceObserverCallback$I %callback),
`Exposed$=(Window,Worker)]
interface `PerformanceObserver@I {
    void `observe$m(optional `PerformanceObserverInit$I %options);
    void `disconnect$m();
    `PerformanceEntryList$I `takeRecords$m();
    static readonly attribute `FrozenArray$<`DOMString$> `supportedEntryTypes$m;
};

注記： 処理能~overheadを最小限に保つためには、~appは，関心のある~event種別のみを申込んで、処理能~dataを観測する必要がなくなったなら，観測器を `disconnect()$m するべきである。 名前（ `name$m ）による絞込みは~supportされない — それは，暗黙的にすべての~event種別を申込むことになり、アリではあるが，大量の~eventを生成することになるので。 ◎ Note ◎ To keep the performance overhead to minimum the application ought 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 {
    `sequence$<`DOMString$> `entryTypes$d;
    DOMString `type$d;
    `boolean$ `buffered$d;
};

[`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. %~entry種別 ~LET %新たな~entry の `entryType$m 値 ◎ ↓
2. %大域~obj ~LET `関連する大域~obj$ 【どの~objに`関連する大域~obj$かは、この~algoを呼出した文脈に依存する。】 ◎ ↓
3. %大域~obj の`処理能~観測器~list$内の ~EACH ( `処理能~観測器$ %観測器 ) に対し ⇒ ~IF［ %観測器 の`~options~list$pO内に ある `PerformanceObserverInit$I ~item %D が在って，［ %~entry種別 ~IN %D の `entryTypes^m ］~OR［ %~entry種別 ~EQ %D の `entryType^m ］を満たす ］ ⇒ %観測器 の`~buffer$pOに %新たな~entry を付加する ◎ Let interested observers be an initially empty set of PerformanceObserver objects. ◎ For each registered performance observer (regObs): • If regObs's options list contains a PerformanceObserverInit item whose entryTypes member includes entryType or whose type member equals to entryType, append regObs's observer to interested observers. ◎ For each observer in interested observers: • Append new entry to observer's observer buffer.
4. ~IF［ %処理能~entry~bufferに追加する~flag ~NEQ ε ］ ⇒ %新たな~entry を %大域~obj の`処理能~entry~buffer$に追加する ◎ If the add to performance entry buffer flag is set, add new entry to the performance entry buffer.
5. ~IF［ %大域~obj の`処理能~観測器~task~queue済み~flag$ ~EQ ~ON ］ ⇒ ~RET ◎ If the performance observer task queued flag is set, terminate these steps.
6. %大域~obj の`処理能~観測器~task~queue済み~flag$ ~SET ~ON ◎ Set performance observer task queued flag.

7. 次の下位手続きを走らす`~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$pOは空である ］ ⇒ ~CONTINUE ◎ ↓
      2. %~entryたち ~LET %観測器 の`~buffer$pOの複製 ◎ Let entries be a copy of po’s observer buffer.
      3. %観測器 の`~buffer$pOを空にする ◎ Empty po’s observer buffer.

      4. 次を渡して %観測器 の`~callback$pOを~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を最小限に抑えるため，アリなら遊休中に処理するべきである。 ◎ 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 ) に対し： ◎ For each PerformanceEntry object (entryObject) in the buffer, in chronological order with respect to startTime:

   1. ~IF［ %名前 ~NIN { ~NULL, %~entry~obj の `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 の `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 を追加する ◎ Add entryObject to the list of entry objects.
3. ~RET %~list ◎ Return the list of entry objects.

4.3. 処理能~entry種別を登録する

`処理能~entry種別を登録する@ ときは、所与の ( 文字列 %種別 ) に対し，`~supportされる~entry種別たち$に %種別 を付加する。 【当然ながら、同じ文字列がすでに登録-済みの場合は付加しないであろう。】 ◎ To register a performance entry type, run the following steps: • Let type be the input string. • Append type to supported entry types.