Performance Engineering

The framework keeps a small timing contract: a Runtime can emit one flat report for each stage of an operation it performs, and an observer receives those reports. Performance engineering is what consumes that contract — the optional recorder in etaf-performance-*, which turns reports into retained operation records and portable reports, and the workspace's scenario and budget tools, which measure end-to-end work through a mounted application. This chapter defines the recorder's public interface, describes what a recorded operation contains, and states the measurement and diagnosis rules that make a number trustworthy. It adds nothing to the rendering path: when no observer is attached, operations run directly and the recorder is not loaded into any decision.

The recorder and the report model

Three levels describe one measurement. An operation is one bounded unit of runtime work, opened with a kind and a label and closed when the work finishes; a Runtime runs at most one operation at a time, and a nested call joins the open one instead of opening a second. A stage is one provider report emitted inside an operation — the Runtime's own timings, and, when the work wrote a buffer, the Ebox flush report that describes the write. A report is the retained, portable view of completed operations: immutable operation records plus an environment snapshot, a summary and a machine-readable operation list.

The recorder does not time anything itself. The Runtime and its providers time their own stages and emit flat plists; the recorder validates nothing that arrives through the prepared observer port, collates the reports of one operation, and keeps the closed operation in a bounded ring. That division is why enabling recording changes what you see, not what the framework does.

Attaching the recorder is explicit and per Runtime. A Runtime accepts one observer; etaf-performance-start claims it, etaf-performance-stop releases it, and a Runtime owned by a different observer is not silently taken over. The mode etaf-performance-mode is the convenience wrapper: it attaches the recorder to the Runtime of the current buffer and detaches it when turned off.

The recorder lifecycle

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

Record operations for the Runtime mounted in the current buffer.

Arguments. ARG follows the minor-mode convention: nil or omitted enables the mode, a positive number enables it, zero or a negative number disables it, and toggle flips it.

Semantics. Enabling looks up the buffer's mounted Runtime and attaches the recorder through etaf-performance-start; if the buffer has no Runtime the mode stays off and the command reports it. Disabling detaches the attachment this mode created. The variable etaf-performance-mode reports the state, and the mode line shows ETAF-Perf while recording.

Returns. The mode variable.

Errors. error→ user-error "Current buffer has no mounted ETAF runtime" when enabling in a buffer without one. An attachment failure such as a foreign observer propagates its own condition and leaves the mode off.

See also. etaf-performance-start, etaf-performance-stop.

Function: etaf-performance-start (runtime)

Attach the recorder to mounted RUNTIME and return RUNTIME.

Arguments. RUNTIME is a mounted Runtime.

Semantics. Attachment is idempotent for this recorder: calling it again while this recorder owns the Runtime keeps the same attachment and pending operations. A Runtime already owned by a different observer is rejected rather than replaced, so two recorders never split one Runtime's reports. Unfinished operations whose later stages never arrive are discarded when the attachment ends.

Returns. RUNTIME.

Errors. error→ etaf-runtime-error when RUNTIME is not mounted. error→ error "ETAF runtime already has a different observer" when another observer owns it.

Example.

(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)))

See also. etaf-performance-stop, etaf-performance-mode.

Function: etaf-performance-stop (runtime)

Detach this recorder from RUNTIME and return RUNTIME.

Arguments. RUNTIME is a Runtime.

Semantics. The recorder's attachment, its pending operations and the ownership of the observer are released together. If another observer already replaced the recorder's sink, that observer is left intact and only the recorder's bookkeeping is discarded. Stopping a Runtime the recorder never attached is a no-op.

Returns. RUNTIME.

Errors. error→ wrong-type-argument (etaf-runtime-p X) when RUNTIME is not a Runtime object.

See also. etaf-performance-start.

Function: etaf-performance-clear ()

Clear completed and unfinished performance records.

Semantics. Every retained operation and every pending operation is dropped. If the performance panel is open, it is reverted so it shows the empty set. The recorder's attachments are untouched: recording continues after a clear.

Returns. Nil.

See also. etaf-performance-records, etaf-performance-show.

Variable: etaf-performance-max-records

Maximum completed operations retained by the recorder.

Semantics. The default is 200. The recorder keeps a ring of this size, so the oldest completed operation is dropped when the bound is exceeded; lowering the value rebuilds the ring around the newest records the next time an operation completes. Zero stops retention: the next completion drops the retained set and keeps nothing. The bound covers completed operations only; an operation still in flight is not counted.

See also. etaf-performance-records, etaf-performance-clear.

Running an operation

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

Evaluate BODY through RUNTIME's canonical operation boundary.

Arguments. RUNTIME is a mounted Runtime, KIND is an operation symbol and LABEL is a descriptive string. BODY is the work.

Semantics. The macro opens one operation, evaluates BODY and closes the operation with the body's status. A nested etaf-performance-with-operation on the same Runtime joins the open operation instead of opening a second, and a nested call on another Runtime is not observed by this one. The operation's reports are emitted only while the recorder owns the Runtime's observer.

Returns. The value of BODY.

Errors. Errors and quits from BODY are recorded as the operation's status, then re-signaled unchanged; the operation still closes.

Example. A refresh that writes a ref and reads back the recorded stage durations.

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

See also. etaf-performance-call-operation, etaf-performance-records.

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

Call FUNCTION as KIND and LABEL through RUNTIME's operation boundary.

Arguments. RUNTIME is a mounted Runtime, KIND is an operation symbol, LABEL is a string and FUNCTION is a zero-argument function.

Semantics. The function form of etaf-performance-with-operation, for a callback that must be passed as a function rather than written in place.

Returns. FUNCTION's result.

Errors. error→ etaf-runtime-error "ETAF runtime is not mounted" when RUNTIME is not mounted. error→ wrong-type-argument (symbolp KIND), (stringp LABEL) or (functionp FUNCTION) for the wrong argument types. FUNCTION's own errors are recorded and re-signaled.

See also. etaf-performance-with-operation.

The operation record

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

Return non-nil when X is a completed operation record.

Semantics. Use it to check a value from a collection before reading slots from it; the slot readers otherwise signal wrong-type-argument.

Returns. Non-nil for an operation record, nil for anything else.

See also. etaf-performance-records.

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

Access slot "id" of `etaf-performance-operation' struct X.

Semantics. The identity is an integer, unique within its Runtime and increasing in call order. A nested call reports the enclosing operation's identity.

Returns. The integer identity.