Documentation
¶
Overview ¶
Package disruptor provides an in-process, bounded event exchange based on a preallocated ring buffer and monotonically increasing sequences.
Producers claim a sequence, mutate its preallocated event, and publish the sequence. Consumers wait through a SequenceBarrier, process available events in batches, and advance their own Sequence. The slowest registered gating sequence prevents producers from overwriting unread entries. EventPoller provides the same sequence-aware consumption for application-controlled loops.
The repository's production guide covers topology assembly, ring sizing, ownership, lifecycle, and operational validation.
Index ¶
- Constants
- Variables
- type BatchProcessor
- type BlockingWaitStrategy
- type BusySpinWaitStrategy
- type EventFactory
- type EventHandler
- type EventPoller
- type EventTranslator
- type HandlerError
- type HandlerPanicError
- type PollState
- type ProcessorOption
- type ProducerType
- type ProducerWaitMode
- type RingBuffer
- func (r *RingBuffer[T]) AddGatingSequences(sequences ...*Sequence)
- func (r *RingBuffer[T]) BufferSize() int64
- func (r *RingBuffer[T]) Close()
- func (r *RingBuffer[T]) Cursor() int64
- func (r *RingBuffer[T]) DiscardRange(low, high int64)
- func (r *RingBuffer[T]) DiscardSequence(sequence int64)
- func (r *RingBuffer[T]) Get(sequence int64) T
- func (r *RingBuffer[T]) IsDiscarded(sequence int64) bool
- func (r *RingBuffer[T]) NewBarrier(dependencies ...*Sequence) *SequenceBarrier
- func (r *RingBuffer[T]) Next(ctx context.Context) (int64, error)
- func (r *RingBuffer[T]) NextN(ctx context.Context, count int64) (int64, error)
- func (r *RingBuffer[T]) Publish(ctx context.Context, translator EventTranslator[T]) (err error)
- func (r *RingBuffer[T]) PublishN(ctx context.Context, count int64, translator EventTranslator[T]) (err error)
- func (r *RingBuffer[T]) PublishRange(low, high int64)
- func (r *RingBuffer[T]) PublishSequence(sequence int64)
- func (r *RingBuffer[T]) RemainingCapacity() int64
- func (r *RingBuffer[T]) RemoveGatingSequence(sequence *Sequence) bool
- func (r *RingBuffer[T]) Shutdown(ctx context.Context) error
- func (r *RingBuffer[T]) TryNext() (int64, error)
- func (r *RingBuffer[T]) TryNextN(count int64) (int64, error)
- func (r *RingBuffer[T]) TryPublish(translator EventTranslator[T]) (err error)
- func (r *RingBuffer[T]) TryPublishN(count int64, translator EventTranslator[T]) (err error)
- type RingOption
- type Sequence
- type SequenceBarrier
- type Sequencer
- type SleepingWaitStrategy
- type WaitStrategy
- type YieldingWaitStrategy
Constants ¶
const InitialSequence int64 = -1
InitialSequence is the logical position before the first ring entry.
Variables ¶
var ( // ErrInvalidBufferSize indicates that a ring size is not a positive power of two. ErrInvalidBufferSize = errors.New("disruptor: buffer size must be a positive power of two") // ErrInvalidProducerType indicates that the selected producer mode is unknown. ErrInvalidProducerType = errors.New("disruptor: invalid producer type") // ErrInvalidProducerWaitMode indicates that the selected producer wait mode is unknown. ErrInvalidProducerWaitMode = errors.New("disruptor: invalid producer wait mode") // ErrInvalidClaimSize indicates that a batch claim is outside the ring bounds. ErrInvalidClaimSize = errors.New("disruptor: claim size must be between one and the buffer size") // ErrInsufficientCapacity indicates that a non-blocking claim would overtake a gate. ErrInsufficientCapacity = errors.New("disruptor: insufficient capacity") // ErrNilFactory indicates that New received no event factory. ErrNilFactory = errors.New("disruptor: event factory must not be nil") // ErrNilTranslator indicates that Publish or TryPublish received no translator. ErrNilTranslator = errors.New("disruptor: event translator must not be nil") // ErrNilHandler indicates that NewBatchProcessor received no event handler. ErrNilHandler = errors.New("disruptor: event handler must not be nil") // ErrInvalidBatchSize indicates that a processor batch limit is not positive. ErrInvalidBatchSize = errors.New("disruptor: batch size must be positive") // ErrAlerted indicates that a barrier alert interrupted a wait. ErrAlerted = errors.New("disruptor: barrier alerted") // ErrClosed indicates that the ring was closed before an operation completed. ErrClosed = errors.New("disruptor: ring buffer closed") // ErrAlreadyRunning indicates that Run was called on an active processor. ErrAlreadyRunning = errors.New("disruptor: processor already running") )
Functions ¶
This section is empty.
Types ¶
type BatchProcessor ¶
type BatchProcessor[T any] struct { // contains filtered or unexported fields }
BatchProcessor waits on a barrier, handles all currently available published events in order, skips discarded claims, then advances its consumer sequence once per batch. A BatchProcessor must not be copied after first use; pass it by pointer.
func NewBatchProcessor ¶
func NewBatchProcessor[T any](ring *RingBuffer[T], barrier *SequenceBarrier, handler EventHandler[T], options ...ProcessorOption) (*BatchProcessor[T], error)
NewBatchProcessor creates an ordered consumer for ring using barrier.
func (*BatchProcessor[T]) Halt ¶
func (p *BatchProcessor[T]) Halt()
Halt alerts the barrier and causes the active Run call to return after its current handler invocation and selected batch complete. Halt is a no-op when the processor is idle.
func (*BatchProcessor[T]) Run ¶
func (p *BatchProcessor[T]) Run(ctx context.Context) error
Run processes events until Halt is called, the context is cancelled, the ring is closed, or a handler returns an error. Ring closure returns ErrClosed. On handler error or panic the current batch is not acknowledged, so restarting the processor replays that batch. Handler failures are returned as *HandlerError and recovered handler panics as *HandlerPanicError.
func (*BatchProcessor[T]) Running ¶
func (p *BatchProcessor[T]) Running() bool
Running reports whether Run is ready to process events or is finishing after Halt. It remains true after Halt until that Run call returns.
func (*BatchProcessor[T]) Sequence ¶
func (p *BatchProcessor[T]) Sequence() *Sequence
Sequence returns the processor's last fully acknowledged batch position.
type BlockingWaitStrategy ¶
type BlockingWaitStrategy struct {
// contains filtered or unexported fields
}
BlockingWaitStrategy sleeps consumers until a producer publishes. After the producer cursor passes the desired sequence, dependency waiting yields. A BlockingWaitStrategy must not be copied after it is shared by barriers.
type BusySpinWaitStrategy ¶
type BusySpinWaitStrategy struct{}
BusySpinWaitStrategy continuously polls a dependency and consumes a CPU core. A BusySpinWaitStrategy must not be copied after it is shared by barriers.
type EventFactory ¶
type EventFactory[T any] func() T
EventFactory creates one reusable event for each physical ring slot.
type EventHandler ¶
EventHandler processes one published event in sequence order.
type EventPoller ¶ added in v0.5.0
type EventPoller[T any] struct { // contains filtered or unexported fields }
EventPoller consumes currently available events without owning a goroutine. Call Poll from one application-controlled event loop. An EventPoller must not be copied after first use; pass it by pointer.
func NewEventPoller ¶ added in v0.5.0
func NewEventPoller[T any](ring *RingBuffer[T], barrier *SequenceBarrier, handler EventHandler[T], options ...ProcessorOption) (*EventPoller[T], error)
NewEventPoller creates a non-blocking consumer for ring using barrier. Processor options, including WithMaxBatchSize, configure each poll batch.
func (*EventPoller[T]) Poll ¶ added in v0.5.0
func (p *EventPoller[T]) Poll() (PollState, error)
Poll processes up to the configured batch limit without waiting. It returns PollIdle when no new producer sequence exists, PollGating when a publication gap or upstream dependency prevents progress, and PollProcessing after a batch is acknowledged. A handler error or panic leaves that batch unacknowledged for a later poll and is returned as HandlerError or HandlerPanicError. Visible events are processed before a closed ring returns ErrClosed; an alert returns ErrAlerted.
func (*EventPoller[T]) Sequence ¶ added in v0.5.0
func (p *EventPoller[T]) Sequence() *Sequence
Sequence returns the poller's last fully acknowledged batch position.
type EventTranslator ¶
EventTranslator initializes a claimed event before its sequence is published.
type HandlerError ¶ added in v0.2.0
type HandlerError struct {
// Sequence is the first sequence in the failed batch.
Sequence int64
// Err is the error returned by the handler.
Err error
}
HandlerError reports an error returned by an event handler.
func (*HandlerError) Error ¶ added in v0.2.0
func (e *HandlerError) Error() string
Error returns a sequence-aware description of the handler failure.
func (*HandlerError) Unwrap ¶ added in v0.2.0
func (e *HandlerError) Unwrap() error
Unwrap returns the error returned by the handler.
type HandlerPanicError ¶ added in v0.2.0
type HandlerPanicError struct {
// Sequence is the first sequence in the failed batch.
Sequence int64
// Value is the value recovered from the handler panic.
Value any
}
HandlerPanicError reports a panic recovered from an event handler.
func (*HandlerPanicError) Error ¶ added in v0.2.0
func (e *HandlerPanicError) Error() string
Error returns a sequence-aware description of the recovered panic.
func (*HandlerPanicError) Unwrap ¶ added in v0.2.0
func (e *HandlerPanicError) Unwrap() error
Unwrap returns the panic value when that value implements error.
type PollState ¶ added in v0.5.0
type PollState uint8
PollState describes the result of a non-blocking EventPoller.Poll call.
const ( // PollIdle indicates that the producer has not published another sequence. PollIdle PollState = iota // PollGating indicates that publication or an upstream dependency is ahead // of the poller's next sequence, but the sequence is not yet consumable. PollGating // PollProcessing indicates that at least one sequence was acknowledged. PollProcessing )
type ProcessorOption ¶
type ProcessorOption func(*processorConfig) error
ProcessorOption configures a BatchProcessor or EventPoller.
func WithMaxBatchSize ¶
func WithMaxBatchSize(size int64) ProcessorOption
WithMaxBatchSize limits the number of events acknowledged as one batch.
type ProducerType ¶
type ProducerType uint8
ProducerType selects the claim and publication protocol.
const ( // SingleProducer selects the non-atomic claim path for exactly one producer goroutine. SingleProducer ProducerType = iota // MultiProducer selects the CAS claim path for concurrent producer goroutines. MultiProducer )
type ProducerWaitMode ¶ added in v0.2.0
type ProducerWaitMode uint8
ProducerWaitMode controls how a blocking producer claim waits for consumer gating sequences to release capacity.
const ( // ProducerWaitYielding yields to the Go scheduler while capacity is unavailable. // It is the default and preserves the original producer wait behavior. ProducerWaitYielding ProducerWaitMode = iota // ProducerWaitBlocking sleeps until a gate advances, a gate is removed, the // context is cancelled, or the ring closes. ProducerWaitBlocking // ProducerWaitBusySpin continuously checks capacity and is intended for // latency-sensitive workloads with a dedicated CPU core. ProducerWaitBusySpin )
type RingBuffer ¶
type RingBuffer[T any] struct { // contains filtered or unexported fields }
RingBuffer is a preallocated, power-of-two store coordinated by logical sequences. The same physical event is reused on every lap.
A handler must not retain or mutate an event after it advances its consumer sequence. Prefer a pointer type for T when callers need in-place translation. A RingBuffer must not be copied after first use; pass it by pointer.
func New ¶
func New[T any](size int64, producerType ProducerType, factory EventFactory[T], wait WaitStrategy, options ...RingOption) (*RingBuffer[T], error)
New creates a ring buffer with preallocated events and the selected producer mode. Producer claims yield while waiting for capacity unless configured otherwise.
func (*RingBuffer[T]) AddGatingSequences ¶
func (r *RingBuffer[T]) AddGatingSequences(sequences ...*Sequence)
AddGatingSequences prevents producers from wrapping over the supplied consumers.
func (*RingBuffer[T]) BufferSize ¶
func (r *RingBuffer[T]) BufferSize() int64
BufferSize returns the fixed number of physical ring slots.
func (*RingBuffer[T]) Close ¶
func (r *RingBuffer[T]) Close()
Close immediately prevents future claims and unblocks waits for unavailable sequences with ErrClosed. Use Shutdown to drain registered gating sequences before closing consumers.
func (*RingBuffer[T]) Cursor ¶
func (r *RingBuffer[T]) Cursor() int64
Cursor returns the producer cursor.
func (*RingBuffer[T]) DiscardRange ¶ added in v0.3.0
func (r *RingBuffer[T]) DiscardRange(low, high int64)
DiscardRange resolves every claimed sequence from low through high without delivering their events to processors. Duplicate resolution calls are ignored; the first terminal resolution wins.
func (*RingBuffer[T]) DiscardSequence ¶ added in v0.3.0
func (r *RingBuffer[T]) DiscardSequence(sequence int64)
DiscardSequence resolves a claimed sequence without delivering its event to processors. Duplicate resolution calls are ignored; the first terminal resolution wins.
func (*RingBuffer[T]) Get ¶
func (r *RingBuffer[T]) Get(sequence int64) T
Get returns the reusable event stored at sequence's physical ring slot.
func (*RingBuffer[T]) IsDiscarded ¶ added in v0.3.0
func (r *RingBuffer[T]) IsDiscarded(sequence int64) bool
IsDiscarded reports whether sequence was resolved as discarded in its current ring lap. Discarded sequences are visible to barriers but are skipped by BatchProcessor handlers.
func (*RingBuffer[T]) NewBarrier ¶
func (r *RingBuffer[T]) NewBarrier(dependencies ...*Sequence) *SequenceBarrier
NewBarrier creates a consumer barrier over the producer cursor or dependencies.
func (*RingBuffer[T]) Next ¶
func (r *RingBuffer[T]) Next(ctx context.Context) (int64, error)
Next blocks until one sequence can be claimed or ctx is cancelled.
func (*RingBuffer[T]) NextN ¶
NextN blocks until count contiguous sequences can be claimed and returns the highest.
func (*RingBuffer[T]) Publish ¶
func (r *RingBuffer[T]) Publish(ctx context.Context, translator EventTranslator[T]) (err error)
Publish claims one sequence, invokes translator on its preallocated event, and publishes the sequence even when translator returns an error.
func (*RingBuffer[T]) PublishN ¶ added in v0.4.0
func (r *RingBuffer[T]) PublishN(ctx context.Context, count int64, translator EventTranslator[T]) (err error)
PublishN claims count contiguous sequences, translates each event, and publishes the complete range. Translation stops at the first error, but all claimed sequences are still published to prevent a visibility gap. A panic also publishes the complete range before propagating.
func (*RingBuffer[T]) PublishRange ¶
func (r *RingBuffer[T]) PublishRange(low, high int64)
PublishRange makes every claimed sequence from low through high visible. Every successful raw claim must be resolved by either publishing or discarding it.
func (*RingBuffer[T]) PublishSequence ¶
func (r *RingBuffer[T]) PublishSequence(sequence int64)
PublishSequence makes one claimed sequence visible to consumers. Every successful raw claim must be resolved by either publishing or discarding it.
func (*RingBuffer[T]) RemainingCapacity ¶
func (r *RingBuffer[T]) RemainingCapacity() int64
RemainingCapacity returns the number of sequences claimable without overtaking a gate.
func (*RingBuffer[T]) RemoveGatingSequence ¶
func (r *RingBuffer[T]) RemoveGatingSequence(sequence *Sequence) bool
RemoveGatingSequence removes a gate and reports whether it was registered.
func (*RingBuffer[T]) Shutdown ¶ added in v0.2.0
func (r *RingBuffer[T]) Shutdown(ctx context.Context) error
Shutdown prevents future claims, waits for the gating sequences present when it begins to acknowledge the final claimed sequence, and then closes consumer waits. Publisher operations must have returned before Shutdown is called. Shutdown returns a context error if draining does not complete; the ring is closed whether draining succeeds or fails.
func (*RingBuffer[T]) TryNext ¶
func (r *RingBuffer[T]) TryNext() (int64, error)
TryNext claims one sequence without blocking.
func (*RingBuffer[T]) TryNextN ¶
func (r *RingBuffer[T]) TryNextN(count int64) (int64, error)
TryNextN claims count contiguous sequences without blocking and returns the highest.
func (*RingBuffer[T]) TryPublish ¶
func (r *RingBuffer[T]) TryPublish(translator EventTranslator[T]) (err error)
TryPublish is the non-blocking form of Publish.
func (*RingBuffer[T]) TryPublishN ¶ added in v0.4.0
func (r *RingBuffer[T]) TryPublishN(count int64, translator EventTranslator[T]) (err error)
TryPublishN is the non-blocking form of PublishN.
type RingOption ¶ added in v0.2.0
type RingOption func(*ringConfig) error
RingOption configures a RingBuffer.
func WithProducerWait ¶ added in v0.2.0
func WithProducerWait(mode ProducerWaitMode) RingOption
WithProducerWait selects how blocking producer claims wait for capacity.
type Sequence ¶
type Sequence struct {
// contains filtered or unexported fields
}
Sequence is a padded, atomically updated logical position. A Sequence must not be copied after first use; pass it by pointer.
func NewSequence ¶
NewSequence creates an atomic sequence at initial.
func (*Sequence) CompareAndSwap ¶
CompareAndSwap atomically replaces old with new when the current value equals old.
type SequenceBarrier ¶
type SequenceBarrier struct {
// contains filtered or unexported fields
}
SequenceBarrier coordinates a consumer with the producer cursor and optional upstream consumer sequences. A SequenceBarrier must not be copied after first use; pass it by pointer.
func (*SequenceBarrier) Alert ¶
func (b *SequenceBarrier) Alert()
Alert unblocks current waiters with ErrAlerted.
func (*SequenceBarrier) ClearAlert ¶
func (b *SequenceBarrier) ClearAlert()
ClearAlert permits the barrier to wait again.
func (*SequenceBarrier) Cursor ¶
func (b *SequenceBarrier) Cursor() int64
Cursor returns the slowest dependency position observed by the barrier.
func (*SequenceBarrier) IsAlerted ¶
func (b *SequenceBarrier) IsAlerted() bool
IsAlerted reports whether the barrier is currently alerted.
type Sequencer ¶
type Sequencer interface {
Next(context.Context, int64) (int64, error)
TryNext(int64) (int64, error)
Publish(int64, int64)
IsAvailable(int64) bool
HighestPublished(int64, int64) int64
Cursor() *Sequence
BufferSize() int64
RemainingCapacity() int64
AddGatingSequences(...*Sequence)
RemoveGatingSequence(*Sequence) bool
NewBarrier(...*Sequence) *SequenceBarrier
Close()
Shutdown(context.Context) error
}
Sequencer coordinates producer claims, publication, capacity, and consumer gates. It is an advanced API whose method set is part of the compatibility contract; most applications should use RingBuffer instead of implementing or calling a Sequencer directly.
type SleepingWaitStrategy ¶
type SleepingWaitStrategy struct {
// SpinTries is the number of polling iterations before yielding.
SpinTries int
// YieldTries is the number of scheduler yields before sleeping.
YieldTries int
// Sleep is the duration of each sleep after spinning and yielding.
Sleep time.Duration
}
SleepingWaitStrategy spins, yields, and then sleeps while awaiting publication. A SleepingWaitStrategy must not be copied after it is shared by barriers.
type WaitStrategy ¶
type WaitStrategy interface {
// contains filtered or unexported methods
}
WaitStrategy controls how consumers wait for a sequence to become visible. Implementations must be safe for concurrent use by multiple barriers. The interface is intentionally sealed; use one of the built-in constructors rather than implementing a custom wait strategy.
func BlockingWait ¶
func BlockingWait() WaitStrategy
BlockingWait returns a strategy that sleeps until producers signal publication.
func BusySpinWait ¶
func BusySpinWait() WaitStrategy
BusySpinWait returns a strategy intended for consumers on dedicated cores.
func SleepingWait ¶
func SleepingWait() WaitStrategy
SleepingWait returns a balanced wait strategy with default retry counts.
func YieldingWait ¶
func YieldingWait() WaitStrategy
YieldingWait returns a scheduler-yielding wait strategy.
type YieldingWaitStrategy ¶
type YieldingWaitStrategy struct{}
YieldingWaitStrategy yields to the scheduler between publication checks. A YieldingWaitStrategy must not be copied after it is shared by barriers.