性能时间线

这扩展了来自 [HR-TIME-3] 的 Performance 接口，并提供用于从 性能时间线 中检索性能指标数据的性能相关属性和方法。

WebIDLpartial interface Performance {
              PerformanceEntryList getEntries ();
              PerformanceEntryList getEntriesByType (DOMString type);
              PerformanceEntryList getEntriesByName (DOMString name, optional DOMString type);
            };
            typedef sequence<PerformanceEntry> PerformanceEntryList;

PerformanceEntryList 表示 PerformanceEntry 的序列，为开发人员提供了在 JavaScript 数组上可以找到的所有便捷方法。

WebIDLdictionary PerformanceObserverCallbackOptions {
  unsigned long long droppedEntriesCount;
};

droppedEntriesCount

一个整数，表示当 PerformanceObserver 的 需要丢弃条目 设置时， 观察者正在观察的条目类型的丢弃条目数。

observe() 方法指示用户代理注册 观察者并必须执行以下步骤：

1. 让 relevantGlobal 成为 this 的 相关全局对象。
2. 如果 options 的 entryTypes 和 type 成员 都被省略，则 抛出一个 "TypeError"。
3. 如果 options 的 entryTypes 存在 且 任何其他 成员也存在，则 抛出一个 "TypeError"。
4. 通过运行以下步骤来更新或检查 this 的 观察者类型：
   1. 如果 this 的 观察者类型 是 "undefined":
      1. 如果 options 的 entryTypes 成员存在，则将 this 的 观察者类型 设置为 "multiple"。
      2. 如果 options 的 type 成员 存在，则 将 this 的 观察者类型 设置为 "single"。
   2. 如果 this 的 观察者类型 是 "single" 且 options 的 entryTypes 成员存在，则 抛出一个 "InvalidModificationError"。
   3. 如果 this 的 观察者类型 是 "multiple" 且 options 的 type 成员 存在，则 抛出一个 "InvalidModificationError"。
5. 将 this 的 需要丢弃条目 设置为 true。
6. 如果 this 的 观察者类型 是 "multiple"，请运行以下步骤：
   1. 让 entry types 为 options 的 entryTypes 序列。
   2. 从 entry types 中移除所有不包含在 relevantGlobal 的 受支持条目类型的冻结数组 中的类型。用户代理 应该 通知 开发者 如果 entry types 被修改。例如，列出已移除类型的控制台 警告可能是合适的。
   3. 如果生成的 entry types 序列是空序列，则中止这些步骤。用户代理 应该 通知 开发者当步骤被中止时通知注册 已被中止。例如，控制台警告可能是 合适的。
   4. 如果 relevantGlobal 的 已注册性能观察者对象列表 包含一个 已注册性能观察者，其 观察者 是 this， 用包含 options 作为唯一项的列表替换其 选项列表。
   5. 否则，创建并附加一个 已注册性能观察者 对象到 已注册性能 观察者对象列表 的 relevantGlobal，其中 观察者 设置为 this，并将 选项列表 设置为 包含 options 作为唯一项的列表。
7. 否则，运行以下步骤：
   1. 断言 this 的 观察者类型 是 "single"。
   2. 如果 options 的 type 不包含 在 relevantGlobal 的 受支持条目类型的冻结数组 中，则中止这些步骤。用户代理 应该 通知 开发者当这种情况发生时，例如通过控制台警告。
   3. 如果 relevantGlobal 的 已注册性能观察者对象列表 包含一个 已注册性能观察者 obs，其 观察者 是 this：
      1. 如果 obs 的 选项列表 包含一个 PerformanceObserverInit 项 currentOptions 其 type 等于 options 的 type， 将 currentOptions 替换为 options 在 obs 的 选项列表 中。
      2. 否则，将 options 附加到 obs 的 选项列表。
   4. 否则，创建并附加一个 已注册性能观察者 对象到 已注册性能 观察者对象列表 的 relevantGlobal，其中 观察者 设置为 this 并将 选项列表 设置 为包含 options 作为唯一项的列表。
   5. 如果 options 的 buffered 标志 被设置：
      1. 让 tuple 成为 options 的 相关性能条目元组 和 relevantGlobal。

      2. 对于 tuple 的每个 entry 在 性能条目缓冲区 中：

         1. 如果 应添加条目 使用 entry 和 options 作为 参数返回 true，附加 entry 到 观察者缓冲区。
      3. 排队 PerformanceObserver 任务 与 relevantGlobal 作为输入。

WebIDLdictionary PerformanceObserverInit {
  sequence<DOMString> entryTypes;
  DOMString type;
  boolean buffered;
};

WebIDL[Exposed=(Window,Worker)]
interface PerformanceObserverEntryList {
  PerformanceEntryList getEntries();
  PerformanceEntryList getEntriesByType (DOMString type);
  PerformanceEntryList getEntriesByName (DOMString name, optional DOMString type);
};

takeRecords() 方法必须 返回 此对象的 观察者缓冲区的副本，并清空 此对象的 观察者缓冲区。

disconnect() 方法必须执行以下操作：

1. 将 此对象 从 已注册性能观察者对象列表中移除。
2. 清空 此对象的 观察者缓冲区。
3. 清空 此对象的 选项列表。

每个 全局对象 都有一个相关的 支持的条目类型的冻结数组， 该数组根据支持的条目类型，从 注册表 中按字母顺序排序后 通过 FrozenArray 创建。

当调用 supportedEntryTypes 属性的 getter 时，运行以下步骤：

1. 设 globalObject 为 环境设置对象的全局对象。
2. 返回 globalObject 的 支持的条目类型的冻结数组。

要排队一个 PerformanceEntry (newEntry)，请执行以下步骤：

1. 如果 newEntry 的 id 未设置：
   1. 让 id 成为运行 生成 id 的结果，用于 newEntry。
   2. 将 newEntry 的 id 设置为 id。
2. 令 interested observers 为一个初始为空的集合，包含 PerformanceObserver 对象。
3. 将 entryType 设为 newEntry 的 entryType 值。
4. 将 relevantGlobal 设为 newEntry 的 相关全局对象。
5. 如果 relevantGlobal 有 相关文档：
   1. 将 newEntry 的 navigationId 设置为 relevantGlobal 的 相关文档 的 最近的导航的 id。
6. 否则，将 newEntry 的 navigationId 设置为 null。
7. 对于 relevantGlobal 的每个 注册的性能观察者 regObs:

   1. 如果 regObs 的 选项列表 包含一个 PerformanceObserverInit 的 options，其 entryTypes 成员包括 entryType，或者其 type 成员 等于 entryType：

      1. 如果 应该添加条目 返回 true，则将 regObs 的 观察者 添加到 interested observers。
8. 对于 interested observers 中的每个 observer:
   1. 将 newEntry 添加到 observer 的 观察者缓冲区。
9. 将 tuple 设为 相关性能条目元组，包括 entryType 和 relevantGlobal。
10. 将 isBufferFull 设为运行 确定性能条目缓冲区是否已满 算法的结果，输入为 tuple。
11. 将 shouldAdd 设为 是否应添加条目 算法的结果，输入为 newEntry。
12. 如果 isBufferFull 为 false 且 shouldAdd 为 true，则将 newEntry 附加 到 tuple 的 性能条目缓冲区。
13. 排队 PerformanceObserver 任务 ，输入为 relevantGlobal。

要排队一个导航 PerformanceEntry (newEntry)，请执行以下步骤：

1. 令 id 成为运行 生成 id 的结果，用于 newEntry。
2. 令 relevantGlobal 为 newEntry 的 相关全局对象。
3. 将 newEntry 的 id 设置为 id。
4. 将 newEntry 的 navigationId 设置为 id。
5. 如果 relevantGlobal 有 相关文档：
   1. 将 relevantGlobal 的 相关文档 的 最近的导航 设置为 newEntry。
6. 使用 newEntry 作为输入，排队一个 PerformanceEntry。

在给定relevantGlobal作为输入的情况下，要求排队PerformanceObserver任务时，请执行以下步骤：

1. 如果relevantGlobal的performance observer任务排队标志已设置，终止这些步骤。
2. 设置relevantGlobal的performance observer任务排队标志。
3. 排队一个任务，包括执行以下子步骤。排队任务的任务源是性能时间线任务源。
   1. 取消设置relevantGlobal的performance observer任务排队标志。
   2. 让notifyList成为relevantGlobal的已注册的performance observer对象列表的副本。
   3. 对于notifyList中的每个已注册的performance observer对象registeredObserver，执行以下步骤：
      1. 令po为registeredObserver的observer。
      2. 让entries成为po的观察者缓冲区的副本。
      3. 如果entries为空，则返回。
      4. 清空po的观察者缓冲区。
      5. 让observerEntryList成为一个新的PerformanceObserverEntryList，其条目列表设置为entries。
      6. 让droppedEntriesCount为空。
      7. 如果po的需要丢弃条目已设置，则执行以下步骤：
         1. 将droppedEntriesCount设置为0。
         2. 对于registeredObserver的选项列表中的每个PerformanceObserverInititem：
            1. 对于item的type或其entryTypes中出现的每个DOMString entryType：
               1. 令map为relevantGlobal的性能条目缓冲区映射。
               2. 令tuple为获取map中以entryType为键的条目的结果。
               3. 将droppedEntriesCount增加tuple的丢弃条目计数。
         3. 将po的需要丢弃条目设置为false。
      8. 令callbackOptions为PerformanceObserverCallbackOptions，其droppedEntriesCount已设置为droppedEntriesCount（如果droppedEntriesCount不为空），否则未设置。
      9. 使用observerEntryList作为第一个参数，po作为第二个参数，并作为回调this值，以及callbackOptions作为第三个参数调用po的观察者回调。如果这抛出异常，报告该异常。

性能时间线的任务队列是一个低优先级队列，如果可能，用户代理应在空闲时段处理此队列，以尽量减少性能监控代码的影响。

当要求使用可选的name和type运行按名称和类型过滤缓冲区映射算法时，请执行以下步骤：

1. 让result成为一个最初为空的列表。
2. 让map为与性能条目缓冲区映射关联的缓冲区，且此缓冲区关联的是this的相关全局对象。
3. 让tuple list成为一个空的列表。
4. 如果type不为null，附加在map上通过type作为键获取条目的值的结果到tuple list。否则，分配通过获取值在map上的结果到tuple list。
5. 对于tuple list中的每个tuple，执行以下步骤：
   1. 让buffer成为tuple的性能条目缓冲区。
   2. 如果tuple的从时间线可用为false，继续下一个tuple。
   3. 让entries成为运行按名称和类型过滤缓冲区算法，使用buffer、name和type作为输入的结果。
   4. 对于entries中的每个entry，附加entry到result。
6. 按时间顺序对results的条目进行排序，依据startTime。
7. 返回result。

当要求使用buffer、name和type作为输入运行按名称和类型过滤缓冲区算法时，请执行以下步骤：

1. 让result成为一个最初为空的列表。
2. 对于buffer中的每个PerformanceEntry entry，执行以下步骤：
   1. 如果type不为null，且type与entry的entryType属性不相同，则继续下一个entry。
   2. 如果name不为null，且name与entry的name属性不相同，则继续下一个entry。
   3. 附加entry到result。
3. 按时间顺序对result中的条目进行排序，依据startTime。
4. 返回result。

要判断性能条目缓冲区是否已满，输入tuple，请执行以下步骤：

1. 让num current entries为tuple的性能条目缓冲区的大小。
2. 如果num current entries小于tuple的maxBufferSize，返回false。
3. 将tuple的丢弃的条目数增加1。
4. 返回true。

当被要求为entry生成生成一个id时，执行以下步骤：

1. 让relevantGlobal为entry的相关全局对象。
2. 将relevantGlobal的上一个性能条目id增加一个由用户代理选择的小数。
3. 返回relevantGlobal的上一个性能条目id。

用户代理可以选择每次增加一个小的随机整数作为last performance entry id。用户代理不得选择一个全局的随机整数，并将其应用于所有全局对象的last performance entry id，因为这可能会引入跨域泄漏。