EventSubscription

Description#

Each subscription owns a fixed-capacity buffer. When that buffer is full, the next event replaces its oldest event. The read that follows is a Delivery.Gap naming how many were discarded since the previous read, and only then the events that remain. #droppedCount() is the total across the subscription's life. Another subscription has its own buffer and its own gaps. The control protocol reader only offers values to these buffers, and never runs subscriber code beyond a readiness callback.

One reader at a time. Public operations are thread-safe, and reads from different threads one after another are fine — a coroutine or a fiber moves between threads — but a read that overlaps another, or any read once #stream() or #publisher() has taken the subscription, is refused with IllegalStateException: two readers would split one sequence and its gaps between them. For a second reader, subscribe again; each subscription gets every event.

#next() blocks. #poll() never does, and #onReady(Runnable) arms a one-shot wakeup for when there is something to poll, so an event loop or a coroutine can read without holding a thread while nothing arrives.

A subscription does not reconnect. When it ends, #next() returns empty. #cause() is empty when the caller closed it, and set when the control client ended it. Attach again from the captured session and read a snapshot; nothing already missed is replayed.

Ending is terminal and wakes threads blocked in #next(). A caller's #close() discards buffered events: the caller has chosen not to read them, so they are not overflow and do not increment the loss count. When the control client ends a subscription, what it had already delivered stays readable, a pending gap first, and only then does a read return empty with #cause() set.