処理能 時列線 — 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. • Let relevantGlobal be observer's relevant global 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. %大域~obj ~LET 此れに`関連な大域~obj$ ◎ ↑↑
7. %観測器~list ~LET %大域~obj の`処理能~観測器~list$ ◎ ↓
8. %~supportする~entry種別たち ~LET %大域~obj が`~supportする~entry種別たち$ ◎ ↓

9. ~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 relevantGlobal's frozen array of 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 relevantGlobal 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 relevantGlobal, with observer set to the context object and options list set to a list containing options as its only item.

10. ~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 the relevantGlobal's frozen array of 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 relevantGlobal 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 relevantGlobal, 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~buffer$ ］で`拡張する$ ⇒ `処理能~entry~tupleを得る$( %種別, %大域~obj ) ◎ If options's buffered flag is set: • Let tuple be the relevant performance entry tuple of options's type and relevantGlobal. • For each entry in tuple's performance entry buffer append entry to the observer buffer.

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 属性

各 `大域~obj$には、 `~supportする~entry種別たち@ が結付けられる。 それは、~alphabet-順序による一連の文字列からなるように初期化された `FrozenArray$I であり，［ 当の大域~obj用に~supportするものとして`~registry$に含められた~entry種別たち ］から作成される。 ◎ Each global object has an associated frozen array of supported entry types, which is initialized to the FrozenArray created from the sequence of strings among the registry that are supported for the global object, in alphabetical order.

取得子は、次を返すモノトスル ⇒ 【！`大域~obj$enV】 此れに`関連な大域~obj$が`~supportする~entry種別たち$ ◎ When supportedEntryTypes's attribute getter is called, run the following steps: • Let globalObject be the environment settings object's global object. • Return globalObject's frozen array of supported entry types.

注記： この属性は、~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 (newEntry), 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 newEntry’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 newEntry to observer's observer buffer.
4. %~tuple ~LET `処理能~entry~tupleを得る$( %~entry種別, %大域~obj ) ◎ Let relevantGlobal be newEntry's relevant global object. ◎ Let tuple be the relevant performance entry tuple of entryType and relevantGlobal.
5. ~IF［ %~tuple は`処理能~entryを追加するに適格$である ］ ⇒ %~tuple の`処理能~entry~buffer$に %新たな~entry を`付加する$ ◎ Call the determine eligibility for adding a performance entry algorithm with tuple as input. If it returns true, append newEntry to tuple's performance entry buffer.
6. ~IF［ %大域~obj の`処理能~観測器~task~queue済み~flag$ ~EQ ~T ］ ⇒ ~RET ◎ If the performance observer task queued flag is set, terminate these steps.
7. %大域~obj の`処理能~観測器~task~queue済み~flag$ ~SET ~T ◎ 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 ~F ◎ Unset performance observer task queued flag of relevantGlobal.
   2. %通知-~list ~LET %大域~obj の`処理能~観測器~list$を`~cloneする$ 【~cloneするのは、後~段で~callされる~callbackによる~~影響を避けるため】 ◎ Let notifyList be a copy of relevantGlobal's list of registered performance observer objects.

   3. %通知-~list を成す ~EACH( `処理能~観測器$ %観測器 ) に対し： ◎ For each PerformanceObserver object po in notifyList, 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. ~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.