性能时间线

这是对来自 [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， 则用 options 替换 currentOptions 于 obs 的 选项列表中。
      2. 否则，将 options 添加到 obs 的 选项列表。
   4. 否则，创建并添加一个 已注册性能观察者对象到 relevantGlobal 的 已注册性能观察者对象列表，其中 观察者设为 this，选项列表 设为一个只包含 options 的列表。
   5. 如果 options 的 buffered 标志被设置：
      1. 令 tuple 为 options 的 type 和 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() 方法必须返回 this 的 观察者缓冲区 的副本，并同时清空 this 的 观察者缓冲区。

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

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

每个 全局对象都有一个相关的 受支持条目类型的冻结数组，其初始化为按照字母顺序排列、在注册表中针对该全局对象支持的字符串序列，通过 FrozenArray 创建。

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

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

要队列 PerformanceEntry (newEntry)，执行以下步骤：

1. 如果 newEntry 的 id 未设置：
   1. 令 id 为对 newEntry 运行 生成 id 的结果。
   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. 如果 应添加条目，参数为 newEntry 和 options，结果为 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. 用 relevantGlobal 作为输入，为 PerformanceObserver 排队任务。

要队列导航 PerformanceEntry (newEntry)，执行以下步骤：

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

当要求为 PerformanceObserver 排队任务时，输入为 relevantGlobal，执行以下步骤：

1. 如果 relevantGlobal 的 性能观察者任务已排队标志已设置，则终止这些步骤。
2. 设置 relevantGlobal 的 性能观察者任务已排队标志。
3. 队列任务，包括以下子步骤。 此队列任务的 任务来源为 性能时间线任务来源。
   1. 取消设置 relevantGlobal 的 性能观察者任务已排队标志。
   2. 令 notifyList 为 relevantGlobal 的 已注册性能观察者对象列表 的副本。
   3. 对 notifyList 中每个 已注册性能观察者对象 registeredObserver，执行以下步骤：
      1. 令 po 为 registeredObserver 的 观察者。
      2. 令 entries 为 po 的 观察者缓冲区 的副本。
      3. 如果 entries 为空，则返回。
      4. 清空 po 的 观察者缓冲区。
      5. 令 observerEntryList 为一个新的 PerformanceObserverEntryList， 其 条目列表 设为 entries。
      6. 令 droppedEntriesCount 为 null。
      7. 如果 po 的 需要丢弃条目 已设置，执行以下步骤：
         1. 将 droppedEntriesCount 设为 0。
         2. 对 registeredObserver 的 选项列表中的每个 PerformanceObserverInit item：
            1. 对 item 的 type 或 entryTypes 中的每个 DOMString entryType：
               1. 令 map 为 relevantGlobal 的 性能条目缓冲区映射。
               2. 令 tuple 为在 map 上以 entryType 为 键 获取条目值 的结果。
               3. 将 droppedEntriesCount 增加 tuple 的 丢弃条目计数。
         3. 将 po 的 需要丢弃条目 设为 false。
      8. 令 callbackOptions 为一个 PerformanceObserverCallbackOptions， 如果 droppedEntriesCount 非 null，则将其 droppedEntriesCount 设为 droppedEntriesCount，否则为未设置。
      9. 调用 po 的 观察者回调，参数为 « observerEntryList, po, callbackOptions », "report", 和 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 的 availableFromTimeline 为 false，则继续下一个 tuple。
   3. 令 entries 为对 buffer、name 和 type 执行 按名称和类型过滤缓冲区算法的结果。
   4. 对 entries 中每个 entry，添加 entry 至 result。
6. 按 startTime 对 results 的条目进行时间顺序排序
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. 按 startTime 对 results 的条目进行时间顺序排序
4. 返回 result。

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

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

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

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

用户代理可以选择每次将 最后性能条目 id 增加一个小的随机整数。用户代理不得选择一个全局随机整数并将所有全局对象的 最后性能条目 id 增加该值，因为这可能导致跨域泄漏。