PtcRunner.TraceLog.Introspection.Holder (PtcRunner v0.13.0)

Copy Markdown View Source

Host-side owner of a loaded turn-log event list backing an introspection grant (P2 of docs/plans/sandbox-heap-rebaseline.md).

PtcRunner.TraceLog.Introspection.tools/2 starts one holder per path/list source; the granted closures ask the holder for projections, so the events never enter the sandbox process and a program's heap cost tracks each result, not the log.

Lifecycle: the holder monitors the process that created the grant and stops when it goes down, so a grant cannot leak past its session. The reverse direction is isolated: a holder crash surfaces to callers as a failed query/3, never as an exit signal into the owner.

Bounds: refuses event lists over :max_bytes (serialized size) at load — fail closed with a clear error rather than silently truncating, because an analysis over silently-dropped events would read as "covered everything". (The live PtcRunner.TraceLog.MemorySink is different: its ring-buffer eviction is the documented retention policy.)

Summary

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

query(holder, fun, timeout \\ 5000)

Runs fun over the held events inside the holder and returns its result.

start(events, opts \\ [])

Starts a holder owning events for the calling process.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

query(holder, fun, timeout \\ 5000)

@spec query(pid(), ([map()] -> term()), timeout()) :: term()

Runs fun over the held events inside the holder and returns its result.

fun must be host-trusted code; if it raises, the error is re-raised in the caller and the holder survives.

start(events, opts \\ [])

@spec start(
  [map()],
  keyword()
) :: {:ok, pid()}

Starts a holder owning events for the calling process.

Options: :max_bytes — serialized-size load cap (default 67108864). Raises ArgumentError when the events exceed it.