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

被呼出時には、次の結果【を表現する新たな `PerformanceEntryList$I ~obj】を返すモノトスル ⇒ `~buffer~mapを名前と種別で絞込む$( 此れ, ~NULL, ~NULL ) ◎ 3.1.1 getEntries() method ◎ Returns a PerformanceEntryList object returned by the filter buffer map by name and type algorithm with name and type set to null.

`getEntriesByType(type)@m

被呼出時には、次の結果を返すモノトスル ⇒ `~buffer~mapを名前と種別で絞込む$( 此れ, ~NULL, %type ) ◎ 3.1.2 getEntriesByType() method ◎ Returns a PerformanceEntryList object returned by filter buffer map by name and type algorithm with name set to null, and type set to the method's input type parameter.

`getEntriesByName(name, type)@m

被呼出時には、次を走らすモノトスル：

1. ~IF［ %type ~EQ ε ］ ⇒ %type ~SET ~NULL
2. ~RET `~buffer~mapを名前と種別で絞込む$( 此れ, %name, %type )

◎ 3.1.3 getEntriesByName() method ◎ Returns a PerformanceEntryList object returned by filter buffer map by name and type algorithm with name set to the method input name parameter, and type set to null if optional entryType is omitted, or set to the method's input type parameter otherwise.

5.1. `observe(options)@m ~method

この~methodは、此れが`登録-済み$であれば 此れを更新し，そうでなければ此れを`登録-済み$にする。 ◎ The observe() method instructs the user agent to register the observer and＼

被呼出時には、次を走らすモノトスル： ◎ must run these steps: • Let observer be the context object.

1. %種別たち ~LET %options[ "`entryTypes$d" ] ◎ ↓
2. %種別 ~LET %options[ "`type$d" ] ◎ ↓
3. ~IF［ %種別たち ~EQ ε ］~AND［ %種別 ~EQ ε ］ ⇒ ~THROW `SyntaxError^E ◎ If options's entryTypes and type members are both omitted, then throw a SyntaxError.
4. ~IF［ %種別たち ~NEQ ε ］~AND［ %options に `entryTypes$d 以外の~memberは在する ］ ⇒ ~THROW `SyntaxError^E ◎ If options's entryTypes is present and any other member is also present, then throw a SyntaxError.

5. 此れの`種別$pOに応じて： ◎ Update or check observer's observer type by running these steps:

   `未定義^i ◎ If observer's observer type is "undefined":

   此れの`種別$pO ~SET ［ %種別たち ~NEQ ε ならば `複数個^i ／ ~ELSE_ `一個^i ］ ◎ If options's entryTypes member is present, then set observer's observer type to "multiple". ◎ If options's type member is present, then set observer's observer type to "single".

   `一個^i

   ~IF［ %種別たち ~NEQ ε ］ ⇒ ~THROW `InvalidModificationError^E ◎ If observer's observer type is "single" and options's entryTypes member is present, then throw an InvalidModificationError.

   `複数個^i

   ~IF［ %種別 ~NEQ ε ］ ⇒ ~THROW `InvalidModificationError^E ◎ If observer's observer type is "multiple" and options's type member is present, then throw an InvalidModificationError.

6. %観測器~list ~LET 此れに`関連な大域~obj$の`処理能~観測器~list$ ◎ ↓

7. ~IF［ 此れの`種別$pO ~EQ `複数個^i ］： ◎ If observer's observer type is "multiple", run the following steps: • Let entry types be options's entryTypes sequence.

   1. %種別たち から［ `~supportされる~entry種別たち$に含まれない種別 ］をすべて除去する ⇒ ~UAは、除去された種別があれば，開発者に通知するベキである — 例えば、~console警告にそれらを挙げるのが適切になるであろう。 ◎ Remove all types from entry types that are not contained in supported entry types. The user agent SHOULD notify developers if entry types is modified. For example, a console warning listing removed types might be appropriate.
   2. ~IF［ %種別たち は空である ］ ⇒ ~RET ⇒ ~UAは、登録は中止されたことを開発者に通知するベキである — 例えば，~console警告が適切になるであろう。 ◎ If the resulting entry types sequence is an empty sequence, abort these steps. The user agent SHOULD notify developers when the steps are aborted to notify that registration has been aborted. For example, a console warning might be appropriate.
   3. ~IF［ 此れ ~NIN %観測器~list ］ ⇒ 此れを %観測器~list に付加する ◎ ↓
   4. 此れ の`~options~list$pO ~SET %options のみからなる~list ◎ If the list of registered performance observer objects of relevant global object contains a registered performance observer whose observer is the context object, replace its options list with a list containing options as its only item. ◎ Otherwise, create and append a registered performance observer object to the list of registered performance observer objects of relevant global object, with observer set to the context object and options list set to a list containing options as its only item.

8. ~ELSE（ 此れの`種別$pO ~EQ `一個^i ）： ◎ Otherwise, run the following steps: • Assert that observer's observer type is "single".

   1. ~IF［ %種別 ~NIN `~supportされる~entry種別たち$ ］ ⇒ ~RET ⇒ ~UAは、これが起きたことを開発者に通知するベキである — 例えば，~console警告を介して。 ◎ If options's type is not contained in supported entry types, abort these steps. The user agent SHOULD notify developers when this happens, for instance via a console warning.

   2. ~IF［ 此れ ~IN %観測器~list ］： ◎ If the list of registered performance observer objects of relevant global object contains a registered performance observer obs whose observer is the context object:

      1. ~IF［ 此れの`~options~list$pO内の ある~itemの `type$d ~EQ %種別 ］ ⇒ 此れの`~options~list$pO内の その~itemを %options に置換する ◎ If obs's options list contains a PerformanceObserverInit item currentOptions whose type is equal to options's type, replace currentOptions with options in obs's options list.
      2. ~ELSE ⇒ %options を此れの`~options~list$pOに付加する ◎ Otherwise, append options to obs's options list.
   3. ~ELSE ⇒＃ 此れを %観測器~list に付加する； 此れの`~options~list$pO ~SET %options のみからなる~list ◎ Otherwise, create and append a registered performance observer object to the list of registered performance observer objects of relevant global object, with observer set to the context object and options list set to a list containing options as its only item.
   4. ~IF［ %options の `buffered$d ~EQ ~T ］ ⇒ 此れの`~buffer$pOを［ 此れに`関連な処理能~entry~tuple$( %種別 ) の`処理能~entry~buffer$ ］で`拡張する$ ◎ If options's buffered flag is set: • Let tuple be the relevant performance entry tuple given options's type as entryType. • For each entry in tuple's performance entry buffer append entry to the observer buffer.

注記： 同じ `PerformanceObserver$I ~obj上で `observe(options)$m を~callするときは、 %options の［ `entryTypes$d, `type$d ］のうち，~~一貫して片方のみを利用する必要がある — 例えば `observe()$m を `entryTypes$d を与えて~callしてから， `type$d を与えて また~callした場合、例外が投出される。 これには、~callがどう積重なるかについて混同を避けることが意味されている。 `entryTypes$d を利用する下では、 `PerformanceObserverInit$I 内の他の~memberは利用できないことに加え、後方-互換性のため，複数回の `observe()$m ~callは 以前のそれを上書きすることになる — この事例では一回の~callで足りるべきなので。 他方， `type$d を利用する下では、一回の~callは 1 個の種別のみ指定するので，各~callは積重なることになる。 この場合も、同じ `type$d を繰返して `observe()$m を~callしたときは，上書きすることになる。 ◎ A PerformanceObserver object needs to always call observe() with options's entryTypes set OR always call observe() with options's type set. If one PerformanceObserver calls observe() with entryTypes and also calls observe with type, then an exception is thrown. This is meant to avoid confusion with how calls would stack. When using entryTypes, no other parameters in PerformanceObserverInit can be used. In addition, multiple observe() calls will override for backwards compatibility and because a single call should suffice in this case. On the other hand, when using type, calls will stack because a single call can only specify one type. Calling observe() with a repeated type will also override.

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);
};

5.2. `takeRecords()@m ~method

5.3. `disconnect()@m ~method

5.4. `supportedEntryTypes@m 属性

~UAは、 `~supportされる~entry種別たち@ — ［ ~UAが `PerformanceObserver$I ~interface用に~supportする~entry種別を表現している文字列 ］からなる`集合$ — を保守するモノトスル。 この集合は、`処理能~entry種別を登録する$~algoを介して新たな~entry種別を定義する各種~仕様により拡充される。 【原文では集合ではなく~listとして定義されているが、同じ文字列が重複して登録されるべきでない／ことはないので，集合としている。】 ◎ The user agent MUST maintain supported entry types, a list of strings representing the entry types which the user agent supports for the PerformanceObserver interface. This list is populated by specifications that define new entry types via the register a performance entry type algorithm.

取得子は、次を返すモノトスル ⇒ 次の結果を~alphabet-順序で~sortした結果の~list 【！＊~INFRA#list-sort-in-ascending-order】 ⇒ `~supportされる~entry種別たち$を`~cloneする$ ◎ When supportedEntryTypes's attribute getter is called, run the following steps: • Let result be a copy of the user agent's supported entry types. • Sort result in alphabetical order. • Return result.

注記： この属性は、~UAがどの~entry種別を~supportするか，容易に知ることを~web開発者に許容する。 ◎ This attribute allows web developers to easily know which entry types are supported by the user agent.

6.1. `PerformanceEntry^I を~queueする

`処理能~entryを~queueする@ ときは、所与の ( `PerformanceEntry$I ~obj %新たな~entry ) に対し，次を走らす： ◎ To queue a PerformanceEntry (new entry), run these steps:

1. %~entry種別 ~LET %新たな~entry の `entryType$m 値 ◎ ↓
2. %大域~obj ~LET 【%新たな~entry に】`関連な大域~obj$ ◎ ↓
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. ◎ Let entryType be new entry’s entryType value. ◎ 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. %~tuple ~LET 【%新たな~entry に】`関連な処理能~entry~tuple$( %~entry種別 ) ◎ ↓
5. ~IF［ %~tuple は`処理能~entryを追加するに適格$である ］ ⇒ %~tuple の`処理能~entry~buffer$に %新たな~entry を`付加する$ ◎ Call the determine eligibility for adding a performance entry algorithm with tuple set to the relevant performance entry tuple given entryType. If it returns true, append new entry to tuple's performance entry buffer.
6. ~IF［ %大域~obj の`処理能~観測器~task~queue済み~flag$ ~EQ ~ON ］ ⇒ ~RET ◎ If the performance observer task queued flag is set, terminate these steps.
7. %大域~obj の`処理能~観測器~task~queue済み~flag$ ~SET ~ON ◎ Set performance observer task queued flag.

8. `処理能~時列線~task源@ から，次の下位手続きを走らす`~taskを~queueする$： ◎ 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 for the relevant global object.
   2. %通知-~list ~LET %大域~obj の`処理能~観測器~list$を`~cloneする$ 【~cloneするのは、後~段で~callされる~callbackによる~~影響を避けるため】 ◎ 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の影響iを最小限に抑えるため，アリなら遊休中に処理するべきである。 ◎ 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.

6.2. ~buffer~mapを ( 名前, 種別 ) で絞込む

`~buffer~mapを名前と種別で絞込む@ ときは、所与の ( %~obj, %名前, %種別 ) に対し，次を走らす： ◎ When asked to run the filter buffer map by name and type algorithm with optional name and type, run the following steps:

1. %結果 ~LET 新たな`~list$ ◎ Let result be an initially empty list.
2. %~map ~LET %~obj に`関連な大域~obj$の`処理能~entry~buffer~map$ ◎ Let map be the performance entry buffer map associated with the relevant global object of context object.
3. %~tuple~list ~LET %種別 に応じて ⇒＃ ~NULL ならば %~map の`値~listを取得する$ ／ ~ELSE_ « %~map[ %種別 ] » ◎ Let tuple list be an empty list. ◎ If type is not null, append the result of getting the value of entry on map given type as key to tuple list. Otherwise, assign the result of get the values on map to tuple list

4. %~tuple~list を成す ~EACH( %~tuple ) に対し： ◎ For each tuple in tuple list, run the following steps:

   1. %~buffer ~LET %~tuple の`処理能~entry~buffer$ ◎ Let buffer be tuple's performance entry buffer.
   2. ~IF［ %~tuple の`時列線から可用？$ ~EQ ~F ］ ⇒ ~CONTINUE ◎ If tuple's availableFromTimeline is false, continue to the next tuple.
   3. %~entryたち ~LET `~bufferを名前と種別で絞込む$( %~buffer, %名前, %種別 ) ◎ Let entries be the result of running filter buffer by name and type with buffer, name and type as inputs.
   4. %結果 を %~entryたち で`拡張する$ ◎ For each entry in entries, append entry to result.
5. ~RET %結果 を各~entryの `startTime$m の時系列順に~sortした結果 【！＊~INFRA#list-sort-in-ascending-order】 ◎ Sort results's entries in chronological order with respect to startTime ◎ Return result.

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

`~bufferを名前と種別で絞込む@ ときは、所与の ( %~buffer, %名前, %種別 ) に対し，次を走らす： ◎ When asked to run the filter buffer by name and type algorithm, with buffer, name, and type as inputs, run the following steps:

1. %~list ~LET 新たな`~list$ ◎ Let result be an initially empty list.

2. %~buffer を成す ~EACH( `PerformanceEntry$I ~obj %~entry ) に対し： ◎ For each PerformanceEntry entry in buffer, run the following steps:

   1. ~IF［ %種別 ~NIN { ~NULL, %~entry の `entryType$m 属性~値 } ］ ⇒ ~CONTINUE ◎ If type is not null and if type does not match entry's entryType attribute in a case-sensitive manner, continue to next entry.
   2. ~IF［ %名前 ~NIN { ~NULL, %~entry の `name$m 属性~値 ) ］ ⇒ ~CONTINUE ◎ If name is not null and if name does not match entry's name attribute in a case-sensitive manner, continue to next entry.
   3. %~list に %~entry を`付加する$ ◎ Append entry to result.
3. ~RET %~list を 各~entryの `startTime$m の時系列順に~sortした結果 【！＊~INFRA#list-sort-in-ascending-order】 ◎ Sort results's entries in chronological order with respect to startTime ◎ Return result.

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

`処理能~entry種別を登録する@ ときは、所与の ( 文字列 %種別 ) に対し，`~supportされる~entry種別たち$に %種別 を`付加する$set。 ◎ To register a performance entry type, run the following steps: • Let type be the input string. • Append type to supported entry types.

6.5. ~bufferは `PerformanceEntry^I を追加するに適格か？

次を満たす %~tuple は、 `処理能~entryを追加するに適格@ であるとされる ⇒ %~tuple の`処理能~entry~buffer$の~size ~LT %~tuple の`最大~buffer~size$ ◎ To determine eligibility for adding a performance entry, with required performance entry tuple, run the following steps: • Let num current entries be the size of tuple's performance entry buffer. • If num current entries is less than tuples's maxBufferSize, return true. Return false.