性能工程

框架保持一份很小的计时契约：Runtime 可以为它执行的一次 operation 的每个 stage 发出扁平报告，观察者接收这些报告。性能工程就是消费这份契约的东西——可选的 etaf-performance-* 记录器，把报告变成保留的 operation 记录与可携带报告；以及工作区的场景与预算工具，通过已挂载的应用测量端到端工作。本章定义记录器的公共接口，描述一条已记录的 operation 包含什么，并给出让一个数字可信的测量与诊断规则。它不给渲染路径增加任何东西：没有观察到观察者时，operation 直接运行，记录器不会进入任何决策。

记录器与报告模型

描述一次测量有三个层次。一个 operation 是一个有界的运行时工作单元，用 kind 与 label 打开、工作结束时闭合；一个 Runtime 同时最多运行一个 operation，嵌套调用并入已打开的那个，而不是打开第二个。一个 stage 是 operation 内一个 provider 发出的报告——Runtime 自己的计时，以及工作写了缓冲区时描述这次写入的 Ebox flush 报告。一份 report 是已完成 operation 的保留、可携带视图：不可变的 operation 记录，加上环境快照、摘要与机器可读的 operation 列表。

记录器自己不计时。Runtime 与它的 provider 给各自的 stage 计时并发出扁平 plist；记录器把一条 operation 的报告收拢起来，把闭合的 operation 存进有界环形缓冲。这就是为什么开启记录改变的是你看到的东西，而不是框架做的事。

挂载记录器是显式、按 Runtime 进行的。一个 Runtime 接受一个观察者；etaf-performance-start 认领它，etaf-performance-stop 释放它，被别的观察者拥有的 Runtime 不会被悄悄接管。etaf-performance-mode 是便利包装：它把记录器挂到当前缓冲区的 Runtime 上，关闭时摘下。

记录器的生命周期

Function: etaf-performance-mode (&optional arg)

记录当前缓冲区所挂载 Runtime 的 operation。

参数。 ARG 遵循次模式惯例：nil 或省略开启模式，正数开启，零或负数关闭，toggle 取反。

语义。 开启时查找缓冲区已挂载的 Runtime，并经 etaf-performance-start 挂上记录器；缓冲区没有 Runtime 时模式保持关闭并报告。关闭时摘下这个模式建立的 attachment。变量 etaf-performance-mode 报告状态，记录期间模式行显示 ETAF-Perf。

返回。 模式变量。

错误。 error→ user-error "Current buffer has no mounted ETAF runtime"：在没有 Runtime 的缓冲区里开启时。挂载失败（例如已有别的观察者）传播它自己的条件，模式保持关闭。

参见。 etaf-performance-start、etaf-performance-stop。

Function: etaf-performance-start (runtime)

把记录器挂到已挂载的 RUNTIME 上并返回 RUNTIME。

参数。 RUNTIME 是一个已挂载的 Runtime。

语义。 对同一个记录器，挂载是幂等的：在它已经拥有该 Runtime 时再调用，保持同一个 attachment 与未完成的 operation。已被别的观察者拥有的 Runtime 会被拒绝而不是替换，所以两个记录器永远不会分掉同一个 Runtime 的报告。后续 stage 永远不会到达的未完成 operation 在 attachment 结束时丢弃。

返回。 RUNTIME。

错误。 error→ etaf-runtime-error：RUNTIME 未挂载时。error→ error "ETAF runtime already has a different observer"：别的观察者拥有它时。

示例。

(let* ((buffer (etaf-mount "*work*" view))
       (runtime (etaf-runtime-for-buffer buffer)))
  (etaf-performance-start runtime)
  (etaf-performance-with-operation (runtime 'refresh "reload")
    (etaf-set-value count 1)))

参见。 etaf-performance-stop、etaf-performance-mode。

Function: etaf-performance-stop (runtime)

从 RUNTIME 摘下这个记录器并返回 RUNTIME。

参数。 RUNTIME 是一个 Runtime。

语义。 记录器的 attachment、它未完成的 operation 与观察者所有权一起释放。若别的观察者已经替换了记录器的 sink，则保留该观察者，只丢弃记录器的记账。停止一个记录器从未挂载的 Runtime 是空操作。

返回。 RUNTIME。

错误。 error→ wrong-type-argument (etaf-runtime-p X)：RUNTIME 不是 Runtime 对象时。

参见。 etaf-performance-start。

Function: etaf-performance-clear ()

清除已完成与未完成的性能记录。

语义。 每条保留的 operation 与每条未完成的 operation 都被丢弃。性能面板若开着，会被还原成空集。记录器的 attachment 不受影响：清空之后记录继续。

返回。 nil。

参见。 etaf-performance-records、etaf-performance-show。

Variable: etaf-performance-max-records

记录器保留的已完成 operation 上限。

语义。 默认 200。记录器按这个大小维持环形缓冲，超过上限时丢弃最旧的已完成 operation；调小时，下一次 operation 完成时按最新记录重建环形缓冲。零表示停止保留：下一次完成会丢弃已保留的集合、什么都不留。上限只覆盖已完成 operation；仍在进行中的不计入。

参见。 etaf-performance-records、etaf-performance-clear。

运行一次 operation

Macro: etaf-performance-with-operation ((runtime kind label) &rest body)

经 RUNTIME 的规范 operation 边界求值 BODY。

参数。 RUNTIME 是已挂载的 Runtime，KIND 是 operation 符号，LABEL 是描述性字符串。BODY 是要做的工作。

语义。 宏打开一条 operation，求值 BODY，并用体的状态闭合这条 operation。同一个 Runtime 上的嵌套 etaf-performance-with-operation 并入已打开的 operation，而不是打开第二条；另一个 Runtime 上的嵌套调用不被这一条观察到。只有记录器拥有该 Runtime 的观察者时，operation 的报告才会发出。

返回。 BODY 的值。

错误。 BODY 的错误与退出被记为 operation 的状态，然后原样重抛；operation 仍然闭合。

示例。 一次写 ref 后读回记录中 stage 耗时的刷新。

(etaf-performance-with-operation (runtime 'refresh "reload")
  (etaf-set-value query "etaf"))

参见。 etaf-performance-call-operation、etaf-performance-records。

Function: etaf-performance-call-operation (runtime kind label function)

经 RUNTIME 的 operation 边界把 FUNCTION 当作 KIND 与 LABEL 调用。

参数。 RUNTIME 是已挂载的 Runtime，KIND 是 operation 符号，LABEL 是字符串，FUNCTION 是无参函数。

语义。 etaf-performance-with-operation 的函数形式，给必须以函数传递的回调使用，而不是就地写体。

返回。 FUNCTION 的结果。

错误。 error→ etaf-runtime-error "ETAF runtime is not mounted"：RUNTIME 未挂载时。error→ wrong-type-argument (symbolp KIND)、(stringp LABEL) 或 (functionp FUNCTION)：参数类型不对时。FUNCTION 自身的错误被记录并重抛。

参见。 etaf-performance-with-operation。

operation 记录

Function: etaf-performance-operation-p (x)

X 是已完成的 operation 记录时返回非 nil。

语义。 在从它读取槽位之前，用它检查集合里的值；否则槽位读取器报 wrong-type-argument。

返回。 operation 记录返回非 nil，其它任何值返回 nil。

参见。 etaf-performance-records。