Module com.darkcollective.relix.events
Package com.darkcollective.relix.events.internal

Class EventBuffer

java.lang.Object
com.darkcollective.relix.events.internal.EventBuffer
All Implemented Interfaces:
QueryEventListener
public final class EventBuffer extends Object implements QueryEventListener
A bounded, in-memory QueryEventListener that retains what it observes so the feed can be read back instead of only printed.

The listener seam is a push port: a producer calls onEvent(QueryEvent) and the event is gone unless someone held on to it. A buffer holds on to it, which is what lets a temporal feed be surfaced as a relation — the bridge between "what happened during that run" and "what can be queried now". Nothing here knows about relations or the catalog; it is a listener that remembers, and the mapping to columns lives in the consumer.

Bounded by construction

A buffer never grows without limit: at capacity() events the oldest is evicted to make room, and droppedCount() records how many were lost that way. An unbounded collector attached to a long-lived session would be a slow leak whose size is set by how much the user runs, so the cap is not configurable per event — it is the point of the type. When events have been dropped, the retained feed is the most recent window, not the whole run.

Ordering

events() returns the retained events oldest-first, in the order they were observed. A QueryEvent carries no timestamp, so this arrival order is the only temporal fact the feed has; consumers that need a stable sort key derive it from the position.

Thread safety

Every method is synchronized on the buffer, so producers may emit from any thread — a REPL evaluating on a worker while the shell reads back, or an executor emitting as a stream is drained. events() returns an immutable snapshot, so a reader is never exposed to a concurrent append.

  • Field Details

  • Constructor Details

    • EventBuffer

      public EventBuffer()
      Creates a buffer retaining up to DEFAULT_CAPACITY events.

    • EventBuffer

      public EventBuffer(int capacity)
      Creates a buffer retaining up to capacity events.
      Parameters:
      capacity - the maximum number of events retained; must be positive
      Throws:
      IllegalArgumentException - if capacity is not positive

  • Method Details

    • onEvent

      public void onEvent(QueryEvent event)
      Description copied from interface: QueryEventListener
      Called once per observed decision. Implementations should be fast and must not throw — an emitter is not expected to guard against listener failures.
      Specified by:
      onEvent in interface QueryEventListener
      Parameters:
      event - the event; never null

    • events

      public List<QueryEvent> events()
      Returns the retained events, oldest first.
      Returns:
      an immutable snapshot of the retained feed; never null

    • clear

      public void clear()
      Discards every retained event and resets droppedCount() — used to start a fresh observation window.

    • droppedCount

      public long droppedCount()
      Returns how many events were evicted to stay within capacity() since the last clear().
      Returns:
      the number of dropped events; zero when nothing overflowed

    • size

      public int size()
      Returns the number of events currently retained.
      Returns:
      the retained count, never greater than capacity()

    • capacity

      public int capacity()
      Returns the maximum number of events this buffer retains.
      Returns:
      the capacity given at construction