1. 序論
~INFORMATIVE~web~appの処理能~特性を正確aに計測することは、~web~appを より速くするための重要な側面である。 この仕様は、~web開発者が, ~web~appの全存続期間にわたる様々な処理能~計量[ に~accessする / を測定する / を検索取得する ]ことを可能化するために必要とされる `処理能時列線$の~primitiveを定義する。 ◎ Accurately measuring performance characteristics of web applications is an important aspect of making web applications faster. This specification defines the necessary Performance Timeline primitives that enable web developers to access, instrument, and retrieve various performance metrics from the full lifecycle of a web application.
[ `NAVIGATION-TIMING-2$r / `RESOURCE-TIMING-2$r / `USER-TIMING-2$r ]は、順に[ 文書の~navi / ~page上の資源 / 開発者~script ]に関係する計時~情報を定義する仕様の例である。 これらは、他の処理能~interfaceと伴に,~web~appの`処理能時列線$を述べる処理能の計量を定義する。 例えば,次の~scriptは、開発者が[ 文書の~navi / ~page上の資源 / 開発者~script ]に関係する処理能~計量を得るために `処理能時列線$に~accessする方法を示すものである: ◎ [NAVIGATION-TIMING-2], [RESOURCE-TIMING-2], and [USER-TIMING-2] are examples of specifications that define timing information related to the navigation of the document, resources on the page, and developer scripts, respectively. Together these and other performance interfaces define performance metrics that describe the Performance Timeline of a web application. For example, the following script shows how a developer can access the Performance Timeline to obtain performance metrics related to the navigation of the document, resources on the page, and developer scripts:
<!doctype html><html><head></head> <body onload="init()"> <img id="image0" src="https://www.w3.org/Icons/w3c_main.png" /> <script> function init() { /* `USER-TIMING-2$r を見よ ◎ see [[USER-TIMING-2]] */ performance.mark("startWork"); doWork(); /* 何らかの開発者~code ◎ Some developer code */ performance.mark("endWork"); measurePerf(); } function measurePerf() { performance .getEntries() .map(%entry => JSON.stringify(%entry, null, 2)) .forEach(%json => console.log(%json)); } </script> </body></html>
別法として,開発者は、`処理能時列線$を観測して,新たな処理能~計量が記録される度に `PerformanceObserver$I ~interfaceを介して通知させられる — 加えて,任意選択で、指定した種別の,それまでに~bufferされた処理能~計量も通知させられる。 ◎ Alternatively, the developer can observe the Performance Timeline and be notified of new performance metrics and, optionally, previously buffered performance metrics of specified type, via the PerformanceObserver interface:
`PerformanceObserver$I ~interfaceは、この仕様の~level 2 にて追加された。 それは、最初の例に示した~bufferに基づく~approachにおける制限nに取組むように設計されている。 `PerformanceObserver$I ~interfaceを利用すれば、~appは: ◎ The PerformanceObserver interface was added in Performance Timeline Level 2 and is designed to address limitations of the buffer-based approach shown in the first example. By using the PerformanceObserver interface, the application can:
- 時列線を調べ続ける( `polling^en )ことなく,新たな計量を検出できる。 ◎ Avoid polling the timeline to detect new metrics
- ~costがかかる~~重複排除~logic( `deduplication^en )なしに,新たな計量を識別できる。 ◎ Eliminate costly deduplication logic to identify new metrics
- ~bufferを操作しようと求める他の消費器との競争を排せる。 ◎ Eliminate race conditions with other consumers that may want to manipulate the buffer
開発者には、アリな所では `PerformanceObserver$I を利用することが奨励される。 更には、新たな処理能~APIの計量は, `PerformanceObserver$I ~interfaceを通す以外に可用にならないこともある。 観測器は、構築子に~callbackを指定して,関心のある処理能~entryを `observe()$m ~methodを介して指定することにより働く。 ~callbackをいつ実行するかは、~UAが選ぶ — それは、~queueされた処理能~entryたちを受取る。 ◎ The developer is encouraged to use PerformanceObserver where possible. Further, new performance API's and metrics may only be available through the PerformanceObserver interface. The observer works by specifying a callback in the constructor and specifying the performance entries it's interested in via the observe() method. The user agent chooses when to execute the callback, which receives performance entries that have been queued.
`PerformanceObserver$I ~interfaceの利用に際し、初期~page読込nに関する特別な考慮点がある: 登録が~eventを受取るためには,作動中でなければならないが、登録~scriptは[ その時点で可用でないか, `critical path^en 内には欲されない ]こともあろう。 これに取組むため、~UAは,~pageが構築されている間 ある個数までの~eventを~bufferする — ~bufferされたこれらの~eventは、観測器を登録するときに `buffered$d ~flagを介して~accessできる。 この~flagが ~T にされた場合、~UAは,指定された~entry種別~用に~bufferされた~eventを検索取得して配送し、それらを `observe()$m ~callが生じた後の初回の~callbackに送達する。 ◎ There are special considerations regarding initial page load when using the PerformanceObserver interface: a registration must be active to receive events but the registration script may not be available or may not be desired in the critical path. To address this, user agents buffer some number of events while the page is being constructed, and these buffered events can be accessed via the buffered flag when registering the observer. When this flag is set, the user agent retrieves and dispatches events that it has buffered, for the specified entry type, and delivers them in the first callback after the observe() call occurs.
注記: ~bufferされる~eventの個数の上限は、当の計量を定義する仕様により決定される。 ~buffer法は、その上限個数までの~eventに限り利用されるものと意図され,継続的でもない。 ◎ The number of buffered events is determined by the specification that defines the metric and buffering is intended to used for first-N events only; buffering is not unbounded or continuous.
<!doctype html><html><head></head> <body> <img id="image0" src="https://www.w3.org/Icons/w3c_main.png" /> <script> /* 利用したい~entry種別は~supportされているかどうかを知る関数 ◎ Know when the entry types we would like to use are not supported. */ function detectSupport(%entryTypes) { for (const %entryType of %entryTypes) { if (!PerformanceObserver.supportedEntryTypes.includes(%entryType)) { /* %entryType は~supportされていないことを~client側~解析に指示する。 ◎ Indicate to client-side analytics that entryType is not supported. */ } } } detectSupport(["resource", "mark", "measure"]); const %userTimingObserver = new PerformanceObserver(%list => { %list .getEntries() /* 挿入された値を取得する ◎ Get the values we are interested in */ .map(({ %name, %entryType, %startTime, %duration }) => { const %obj = { "Duration": %duration, "Entry Type": %entryType, "Name": %name, "Start Time": %startTime, }; return JSON.stringify(%obj, null, 2); }) /* それらを~consoleに表示する ◎ Display them to the console. */ .forEach(console.log); /* ~eventを処理したなら~disconnectする ◎ Disconnect after processing the events. */ %userTimingObserver.disconnect(); }); /* User-Timing 用に新たな~eventを申込む ◎ Subscribe to new events for User-Timing. */ %userTimingObserver.observe({entryTypes: ["mark", "measure"]}); const %resourceObserver = new PerformanceObserver(list => { list .getEntries() /* 関心ある値を取得する ◎ Get the values we are interested in */ .map(({ name, startTime, fetchStart, responseStart, responseEnd }) => { const %obj = { "Name": name, "Start Time": startTime, "Fetch Start": fetchStart, "Response Start": responseStart, "Response End": responseEnd, }; return JSON.stringify(%obj, null, 2); }) /* それらを~consoleに表示する ◎ Display them to the console. */ .forEach(console.log); /* ~eventを処理したなら~disconnectする ◎ Disconnect after processing the events. */ %resourceObserver.disconnect(); }); /* Resource Timing 用に~buffer済みの~eventを検索取得するとともに,それ用に新たな~eventも申込む ◎ Retrieve buffered events and subscribe to newer events for Resource Timing. */ %resourceObserver.observe({type: "resource", buffered: true}); </script> </body> </html>
【この訳に固有の表記規約】
この訳の,~algoの記述に利用されている各種記号( 此れ, ~LET, ~IF, ~RET, 等々)の意味や定義の詳細は、~SYMBOL_DEF_REFを~~参照されたし。
2. 適合性
【 この節の内容は W3C 日本語訳 共通ページ に委譲 】
3. 処理能時列線
各 `大域~obj$には、次のものが結付けられる: ◎ Each global object has:
- `処理能~観測器~task~queue済み~flag@
- 真偽値。 【初期~時は ~F 】 ◎ a performance observer task queued flag
- `処理能~観測器~list@
- `処理能~観測器$からなる~list【実質的には`集合$】。 初期~時は空とする。 ◎ a list of registered performance observer objects that is initially empty
- `処理能~観測器$は、この~list内にあることを `登録-済み@ であるともいう。
- `処理能~entry~buffer~map@
-
`~map$。 この~mapを成す各~entryの`~key$mapは、~bufferが所属する~entry種別を表現する `DOMString^I を与える。 各~entryの`値$mapは、次のものからなる~tupleを与える: ◎ a performance entry buffer map map, keyed on a DOMString, representing the entry type to which the buffer belongs. The map's value is the following tuple:
- `処理能~entry~buffer@ ⇒ `PerformanceEntry$I ~objたちを格納する。 初期~時は空とする。 ◎ A performance entry buffer to store PerformanceEntry objects, that is initially empty.
- `最大~buffer~size@ ⇒ 整数をとり,この~entry種別~用の`~registry$値に初期化される。 ◎ An integer maxBufferSize, initialized to the registry value for this entry type.
- `時列線から可用?@ ⇒ 真偽値をとり,この~entry種別~用の`~registry$値に初期化される。 ◎ A boolean availableFromTimeline, initialized to the registry value for this entry type.
`処理能~entry~tupleを得る@ ときは、所与の ( %~entry種別, %大域~obj ) に対し,次を返す ⇒ %大域~obj の`処理能~entry~buffer~map$[ %~entry種別 ] ◎ In order to get the relevant performance entry tuple, given entryType and globalObject as input, run the following steps: • Let map be the performance entry buffer map associated with globalObject. • Return the result of getting the value of an entry from map, given entryType as the key.
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
-
被呼出時には、次を走らすモノトスル:
- ~IF[ %type ~EQ ε ] ⇒ %type ~SET ~NULL
- ~RET `~buffer~mapを名前と種別で絞込む$( 此れ, %name, %type )
4. `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の種別 を返すモノトスル。 ◎ This attribute MUST return the type of the interface represented by this PerformanceEntry object.
- 注記: すべての `entryType$m 値は関連な`~registry$にて定義される。 例として、次が挙げられる ⇒# `mark^l, `measure^l `USER-TIMING-2$r / `navigation^l `NAVIGATION-TIMING-2$r / `resource^l `RESOURCE-TIMING-2$r / `longtask^l 【 `LONGTASKS$r 】 / 【 `paint^l `PAINT-TIMING$r 】 ◎ Note ◎ All entryType values are defined in the relevantregistry. Examples 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.
5. `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$内に含まれるかどうか ]の区別を表現するだけに過ぎず,無為に冗長なので、この訳では単純~化している。 】
`PerformanceObserver(callback)@m 構築子の被呼出時には、次を走らすモノトスル:
- %観測器 ~LET 新たな `PerformanceObserver$I ~obj
- %観測器 の`~callback$pO ~SET %callback
- ~RET %観測器
callback `PerformanceObserverCallback@I = void ( `PerformanceObserverEntryList$I %entries, `PerformanceObserver$I %observer ); [`Exposed$=(Window,Worker)] interface `PerformanceObserver@I { `constructor$(`PerformanceObserverCallback$I %callback); void `observe$m(optional `PerformanceObserverInit$I %options = {}); void `disconnect$m(); `PerformanceEntryList$I `takeRecords$m(); [`SameObject$] 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 to 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.
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.
- %種別たち ~LET %options[ "`entryTypes$d" ] ◎ ↓
- %種別 ~LET %options[ "`type$d" ] ◎ ↓
- ~IF[ %種別たち ~EQ ε ]~AND[ %種別 ~EQ ε ] ⇒ ~THROW `SyntaxError$E ◎ If options's entryTypes and type members are both omitted, then throw a SyntaxError.
- ~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.
-
此れの`種別$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.
- %大域~obj ~LET 此れに`関連な大域~obj$ ◎ ↑↑
- %観測器~list ~LET %大域~obj の`処理能~観測器~list$ ◎ ↓
- %~supportする~entry種別たち ~LET %大域~obj が`~supportする~entry種別たち$ ◎ ↓
-
~IF[ 此れの`種別$pO ~EQ `複数個^i ]: ◎ If observer's observer type is "multiple", run the following steps: • Let entry types be options's entryTypes sequence.
- %種別たち から[ %~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.
- ~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.
- ~IF[ 此れ ~NIN %観測器~list ] ⇒ 此れを %観測器~list に付加する ◎ ↓
- 此れの`~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.
-
~ELSE( 此れの`種別$pO ~EQ `一個^i ): ◎ Otherwise, run the following steps: • Assert that observer's observer type is "single".
- ~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.
-
~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:
- ~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.
- ~ELSE ⇒ %options を此れの`~options~list$pOに付加する ◎ Otherwise, append options to obs's options list.
- ~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.
- ~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.
注記: 同じ `PerformanceObserver$I ~obj上で `observe(options)$m を~callするときは、 %options の[ `entryTypes$d, `type$d ]のうち,~~一貫して片方のみを利用する必要がある — 例えば `observe()$m を `entryTypes$d を与えて~callしてから, `type$d を与えて また~callした場合、例外が投出される。 これには、~callがどう積重なるかについて混同を避けることが意味されている:
- `entryTypes$d を利用する下では【すなわち, `種別$pO ~EQ `複数個^i 】 ⇒ `PerformanceObserverInit$I 内の他の~memberは利用できないことに加え、後方-互換性を得るため,複数回の `observe()$m ~callは 以前のそれを上書きすることになる — この事例では一回の~callで足りるべきなので。
- `type$d を利用する下では【すなわち, `種別$pO ~EQ `一個^i 】 ⇒ 1 回の~callは 1 個の種別のみ指定するので,各~callは積重なることになる。 この場合も、同じ `type$d を繰返して `observe()$m を~callしたときは,上書きすることになる。
5.1.1. `PerformanceObserverInit^I 辞書
dictionary `PerformanceObserverInit@I { `sequence$<`DOMString$> `entryTypes$d; DOMString `type$d; boolean `buffered$d; };
- `entryTypes@d
- 観測されることになる一連の~entry種別からなる~list。 この~listが在する場合、空であってはナラナイ, かつ 他のすべての~memberも在してはナラナイ。 ~UAは、この~list内の種別のうち,自身が認識しないものは無視するモノトスル。 ◎ A list of entry types to be observed. If present, the list MUST NOT be empty and all other members MUST NOT be present. Types not recognized by the user agent MUST be ignored.
- `type@d
- 観測されることになる単独の~entry種別。 ~UAは、自身が認識しない種別を無視するモノトスル。 ◎ A single entry type to be observed. A type that is not recognized by the user agent MUST be ignored. Other members may be present.
- `buffered@d
- [ ~bufferされた~entryは,観測器の~bufferに~queueされる ]べきかどうかを指示する~flag。 ◎ A flag to indicate whether buffered entries should be queued into observer's buffer.
5.1.2. `PerformanceObserverEntryList^I ~interface
[`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); };
- `getEntries()@mO
- 被呼出時には、次の結果【を表現する新たな `PerformanceEntryList$I ~obj】を返すモノトスル ⇒ `~bufferを名前と種別で絞込む$( 此れが表現する`~buffer$pO, ~NULL, ~NULL ) ◎ 5.1.2.1 getEntries() method ◎ Returns a PerformanceEntryList object returned by filter buffer by name and type algorithm with the context object's observer buffer, name and type set to null.
- `getEntriesByType(type)@mO
- 被呼出時には、次の結果を返すモノトスル ⇒ `~bufferを名前と種別で絞込む$( 此れが表現する`~buffer$pO, ~NULL, %type ) ◎ 5.1.2.2 getEntriesByType() method ◎ Returns a PerformanceEntryList object returned by filter buffer by name and type algorithm with the context object's observer buffer, name set to null, and type set to the method's input type parameter.
- `getEntriesByName(name, type)@mO
-
被呼出時には、次を走らすモノトスル:
- ~IF[ %type ~EQ ε ] ⇒ %type ~SET ~NULL
- ~RET `~bufferを名前と種別で絞込む$( 此れが表現する`~buffer$pO, %name, %type )
5.2. `takeRecords()@m ~method
被呼出時には、次を走らすモノトスル:
- %複製 ~LET 此れの`~buffer$pOの複製
- 此れの`~buffer$pOを空にする
- ~RET %複製
5.3. `disconnect()@m ~method
被呼出時には、次を走らすモノトスル:
- 此れに`関連な大域~obj$の`処理能~観測器~list$から,此れを除去する
- 此れの`~options~list$pO ~LET ε
- 此れの`~buffer$pOを空にする
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. 処理
6.1. `PerformanceEntry^I を~queueする
`処理能~entryを~queueする@ ときは、所与の ( `PerformanceEntry$I ~obj %新たな~entry ) に対し,次を走らす: ◎ To queue a PerformanceEntry (newEntry), run these steps:
- %~entry種別 ~LET %新たな~entry の `entryType$m 値 ◎ ↓
- %大域~obj ~LET %新たな~entry に`関連な大域~obj$ ◎ ↓
- %大域~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.
- %~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.
- ~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.
- ~IF[ %大域~obj の`処理能~観測器~task~queue済み~flag$ ~EQ ~T ] ⇒ ~RET ◎ If the performance observer task queued flag is set, terminate these steps.
- %大域~obj の`処理能~観測器~task~queue済み~flag$ ~SET ~T ◎ Set performance observer task queued flag.
-
`処理能~時列線~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.
- %大域~obj の`処理能~観測器~task~queue済み~flag$ ~SET ~F ◎ Unset performance observer task queued flag of relevantGlobal.
- %通知-~list ~LET %大域~obj の`処理能~観測器~list$を`~cloneする$ 【~cloneするのは、後~段で~callされる~callbackによる~~影響を避けるため】 ◎ Let notifyList be a copy of relevantGlobal's list of registered performance observer objects.
-
%通知-~list を成す ~EACH( `処理能~観測器$ %観測器 ) に対し: ◎ For each PerformanceObserver object po in notifyList, run these steps:
- ~IF[ %観測器 の`~buffer$pOは空である ] ⇒ ~CONTINUE ◎ ↓
- %~entryたち ~LET %観測器 の`~buffer$pOの複製 ◎ Let entries be a copy of po’s observer buffer.
- %観測器 の`~buffer$pOを空にする ◎ Empty po’s observer buffer.
-
次を渡して %観測器 の`~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:
- %結果 ~LET 新たな`~list$ ◎ Let result be an initially empty list.
- %~map ~LET %~obj に`関連な大域~obj$の`処理能~entry~buffer~map$ ◎ Let map be the performance entry buffer map associated with the relevant global object of context object.
- %~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
-
%~tuple~list を成す ~EACH( %~tuple ) に対し: ◎ For each tuple in tuple list, run the following steps:
- %~buffer ~LET %~tuple の`処理能~entry~buffer$ ◎ Let buffer be tuple's performance entry buffer.
- ~IF[ %~tuple の`時列線から可用?$ ~EQ ~F ] ⇒ ~CONTINUE ◎ If tuple's availableFromTimeline is false, continue to the next tuple.
- %~entryたち ~LET `~bufferを名前と種別で絞込む$( %~buffer, %名前, %種別 ) ◎ Let entries be the result of running filter buffer by name and type with buffer, name and type as inputs.
- %結果 を %~entryたち で`拡張する$ ◎ For each entry in entries, append entry to result.
- ~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:
- %~list ~LET 新たな`~list$ ◎ Let result be an initially empty list.
-
%~buffer を成す ~EACH( `PerformanceEntry$I ~obj %~entry ) に対し: ◎ For each PerformanceEntry entry in buffer, run the following steps:
- ~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.
- ~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.
- %~list に %~entry を`付加する$ ◎ append entry to result.
- ~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.
7. ~privacyと~security
この仕様は、 `HR-TIME-2$r に定義された `Performance$I ~interfaceを拡張し,`処理能時列線$[ に~entryを~queueする/から~entryを検索取得する ]ための~methodを供する。 高-分解能な計時~情報を公開することによる[ ~privacy/~security ]上の考慮点については、 `HR-TIME-2$r を~~参照されたし。 ◎ This specification extends the Performance interface defined by [HR-TIME-2] and provides methods to queue and retrieve entries from the performance timeline. Please refer to [HR-TIME-2] for privacy and security considerations of exposing high-resoluting timing information.
8. 依存関係
【 他の仕様に定義される用語(の一部)。 この節の和訳は、省略する。 】 ◎ The [INFRA] specification defines the following: key, getting the value of an entry.
謝辞
この仕様に貢献された次の方々に: