StatifierUI.Trace.Buffer (StatifierUI v0.1.0)

Copy Markdown View Source

A fixed-capacity, drop-oldest store of %StatifierUI.Trace.Message{} values - the memory-safety mechanism a chatty session needs so a notebook does not grow without bound (decision 8 of the plan).

Backed by :queue rather than a list: push/2 at capacity has to drop from the far end, and a list would make that O(n) on every message once full. size/1 is tracked on the struct rather than derived, because :queue.len/1 is itself O(n).

There is no drop notification. Every message carries a per-session monotonic seq starting at 0, so a consumer detects loss by reading the first buffered message's seq directly - a synthetic drop message would itself consume a seq and corrupt the very counter it would be reporting on. dropped/1 exists for a status line, not to replace that.

Summary

Types

t()

Functions

clear(buffer)

Empties buffer, preserving capacity and resetting dropped to 0.

dropped(buffer)

Returns the number of messages lost to capacity since the buffer was created or last cleared.

new(capacity)

Builds an empty buffer holding at most capacity messages.

push(buffer, message)

Appends message, dropping the oldest entry when buffer is already at capacity.

size(buffer)

Returns the number of messages currently held.

to_list(buffer)

Returns buffer's messages oldest-first.

Types

t()

@type t() :: %StatifierUI.Trace.Buffer{
  capacity: pos_integer(),
  dropped: non_neg_integer(),
  entries: :queue.queue(StatifierUI.Trace.Message.t()),
  size: non_neg_integer()
}

Functions

clear(buffer)

@spec clear(t()) :: t()

Empties buffer, preserving capacity and resetting dropped to 0.

dropped(buffer)

@spec dropped(t()) :: non_neg_integer()

Returns the number of messages lost to capacity since the buffer was created or last cleared.

new(capacity)

@spec new(capacity :: pos_integer()) :: t()

Builds an empty buffer holding at most capacity messages.

capacity is a programmer argument, not an input value derived from external data, so a non-positive capacity raises ArgumentError rather than returning an error tuple.

push(buffer, message)

@spec push(t(), StatifierUI.Trace.Message.t()) :: t()

Appends message, dropping the oldest entry when buffer is already at capacity.

size(buffer)

@spec size(t()) :: non_neg_integer()

Returns the number of messages currently held.

to_list(buffer)

@spec to_list(t()) :: [StatifierUI.Trace.Message.t()]

Returns buffer's messages oldest-first.