In-memory ring-buffer sink for turn-log events, alongside the JSONL file
sink (PtcRunner.TraceLog.Collector).
A GenServer holding recent events in memory under a total byte budget. When
appending an event would push the buffer over :max_bytes, the oldest events
are evicted until it fits (the newest event is always retained). This makes
"analyze my last session" work with no filesystem setup — mix ptc.repl
enables a sink by default, and the same PtcRunner.TraceLog.Analyzer queries
read its events.
The byte cost of each event is its JSON-encoded size (the same encoding the
file sink writes), so the budget bounds real serialized retention. Retention
and redaction are host policy (plan D2): the default budget is conservative
but host-configurable via :max_bytes.
Records are accepted as already-built event maps (see
PtcRunner.TraceLog.TurnEvent). Like the file sink, the in-memory sink
assigns a monotonic seq and stamps timestamp when absent, so events stay
orderable independent of wall-clock skew.
Summary
Functions
Returns a specification to start this module under a supervisor.
Drops all retained events.
Returns the number of retained events.
Returns all retained events in chronological (oldest-first) order.
Runs fun over the retained events (chronological order) INSIDE the sink
process and returns its result.
Records an event map into the sink (async). Never raises.
Starts an in-memory sink.
Types
@type t() :: %PtcRunner.TraceLog.MemorySink{ bytes: non_neg_integer(), events: [{non_neg_integer(), map()}], max_bytes: pos_integer(), seq: non_neg_integer() }
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec clear(GenServer.server()) :: :ok
Drops all retained events.
@spec count(GenServer.server()) :: non_neg_integer()
Returns the number of retained events.
@spec events(GenServer.server()) :: [map()]
Returns all retained events in chronological (oldest-first) order.
@spec query(GenServer.server(), ([map()] -> term())) :: term()
Runs fun over the retained events (chronological order) INSIDE the sink
process and returns its result.
Host-side projection support (P2 of docs/plans/sandbox-heap-rebaseline.md):
a caller running under a heap budget — the PTC-Lisp sandbox holding a
log/ introspection grant — pays only for the projected result crossing
back, never for a copy of the full buffer. fun must be host-trusted code;
if it raises, the error is re-raised in the caller and the sink survives.
@spec record(GenServer.server(), map()) :: :ok
Records an event map into the sink (async). Never raises.
@spec start_link(keyword()) :: GenServer.on_start()
Starts an in-memory sink.
Options
:max_bytes- total JSON-encoded byte budget (default: 8388608):name- optional registered name for the GenServer