dispatch

package
v0.1.0-alpha.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 15, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package dispatch provides KeyedPool, a worker pool that keeps per-key order: work items that share a key are processed one at a time, in the order they were submitted, while items with different keys run concurrently.

How it works

KeyedPool has a fixed number of lanes. Each lane is one goroutine reading its own bounded queue. A work item goes to lane fnv1a(KeyOf(work)) % Lanes, so every item with the same key lands on the same lane and is processed in submit order. Process receives the lane index, so a caller can keep per-lane state (for example an applied-sequence guard) without locking: only that lane's goroutine touches it. A panic in Process is recovered; the lane keeps running and the optional OnPanic callback is called with the item, so the caller can dispose of it (for example Nak the message it came from).

Use it when two items with the same key must never be processed out of order or at the same time, as graph-ingest needs for one entity's updates (ADR-072, in SemStreams).

pool, err := dispatch.NewKeyedPool(ctx, dispatch.KeyedConfig[ingestWork]{
    Lanes:      lanes,
    QueueDepth: 256,
    Name:       "graph_ingest",
    KeyOf:      func(w ingestWork) string { return w.entityID },
    Process:    processIngest, // func(ctx, lane, work) error
    OnPanic:    func(w ingestWork, _ any) { _ = w.msg.Nak() },
}, dispatch.KeyedDeps{MetricsRegistry: registry, Logger: logger})

SubmitBlocking applies backpressure: when the item's lane queue is full, the call waits until the lane has room or its context ends.

Stopping

Cancelling the context given to NewKeyedPool aborts the pool: the lanes stop without processing what is still queued. Shutdown(ctx) is the graceful stop. From its first call, SubmitBlocking returns ErrStopped; submits already accepted land in their queues, every lane finishes its queue and exits, and Shutdown returns nil. If ctx ends first, Shutdown returns ctx.Err() and the lanes keep draining; call Shutdown again to wait for them. Shutdown has no timeout of its own: a context with no deadline waits as long as Process takes. A nil context is refused with an error.

A producer parked in SubmitBlocking on a full lane holds Shutdown up until the lane takes its item. On shutdown, cancel the context passed to SubmitBlocking first, then call Shutdown.

Metrics

With KeyedDeps.MetricsRegistry set, the pool registers six collectors labelled pool=<Name> through metric.RegisterOrGet: dispatch_queue_wait_seconds, dispatch_processing_duration_seconds, dispatch_queue_depth, dispatch_inflight, dispatch_submitted_total and dispatch_completed_total. Two pools with the same Name on one registry share these collectors. A registration the registry refuses makes NewKeyedPool return the error. With no registry the pool keeps no metrics.

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrInvalidConfig is returned by NewKeyedPool for a nil context or
	// a KeyedConfig that is incomplete or out of range (Lanes <= 0,
	// QueueDepth <= 0, a missing KeyOf or Process). Catches wiring bugs
	// at construction time.
	ErrInvalidConfig = errors.New("dispatch: invalid config")

	// ErrStopped is returned by KeyedPool.SubmitBlocking once Shutdown
	// has begun.
	ErrStopped = errors.New("dispatch: pool stopped")
)

Package error sentinels. Callers compare with errors.Is.

Functions

This section is empty.

Types

type KeyedConfig

type KeyedConfig[W any] struct {
	// Lanes is the number of parallel serial lanes. Same-key work is
	// serialized within a lane; different keys spread across lanes.
	// Must be > 0. Fixed for the pool's lifetime (lane assignment is a
	// pure function of the key over this count).
	Lanes int

	// QueueDepth bounds each lane's queue. SubmitBlocking waits while
	// the target lane is at capacity. Must be > 0.
	QueueDepth int

	// KeyOf maps a work item to its partition key. Items with equal
	// keys are processed serially in submit order on one lane. Must be
	// non-nil and pure (called once per submit).
	KeyOf func(W) string

	// Process handles one work item. It is called by the assigned
	// lane's single goroutine, with that lane's index — a composer can
	// use the index to shard per-lane state without locking (the pool
	// guarantees at most one goroutine per lane). Must be non-nil.
	Process func(ctx context.Context, lane int, work W) error

	// OnPanic — optional. When Process panics, the pool recovers it,
	// keeps the lane goroutine alive, and (if set) calls OnPanic with
	// the work item and the recovered value so the composer can
	// dispose of it (e.g. Nak the underlying message). Called from the
	// lane goroutine. If nil, a recovered panic is logged and dropped.
	OnPanic func(work W, recovered any)

	// Name labels this pool's metrics (the `pool` label). Optional;
	// the pool has metrics only when KeyedDeps.MetricsRegistry is set.
	Name string
}

KeyedConfig parameterizes KeyedPool construction. The zero value is NOT valid — NewKeyedPool rejects Lanes <= 0, QueueDepth <= 0, and a missing KeyOf or Process.

type KeyedDeps

type KeyedDeps struct {
	MetricsRegistry *metric.MetricsRegistry
	Logger          *slog.Logger
}

KeyedDeps carries the framework dependencies. Both are optional: MetricsRegistry nil → the pool keeps no metrics; Logger nil → slog.Default.

type KeyedPool

type KeyedPool[W any] struct {
	// contains filtered or unexported fields
}

KeyedPool is the framework's keyed-ordered bounded-concurrency primitive: it partitions work into N lanes by a caller-supplied key. All items sharing a key route to the same lane and are processed serially in submit order, while items with different keys spread across lanes and run concurrently.

It exists for at-least-once consumers that need per-key ordered concurrency — e.g. graph-ingest, whose arrival-order (full-set- replace) merge requires that all messages for one entity apply in order, but which is otherwise latency-bound on a serial Get+CAS chain (ADR-072).

Structure: N separate bounded lane channels, one goroutine per lane. A shared channel read by N workers cannot preserve per-key order, which is why each lane has its own channel and goroutine.

Concurrency: SubmitBlocking and Shutdown are safe to call from concurrent goroutines. The Process function for a given lane is only ever invoked by that lane's single goroutine, so a composer maintaining per-lane state (indexed by the lane number passed into Process) needs no locking on it.

func NewKeyedPool

func NewKeyedPool[W any](ctx context.Context, cfg KeyedConfig[W], deps KeyedDeps) (*KeyedPool[W], error)

NewKeyedPool constructs and starts a KeyedPool. Lane goroutines are running and ready to receive SubmitBlocking calls when it returns — callers don't call a separate Start.

The ctx is the pool's run context: it is passed to Process, and its cancellation aborts all lanes immediately (in-flight Process calls see the cancellation via their ctx; buffered items are NOT drained); once they return, no goroutine of the pool is left running. For a graceful drain that DOES finish buffered work, call Shutdown. The ctx must be non-nil.

Returns ErrInvalidConfig for a nil ctx or a missing or out-of-range required field, and the registry's refusal when one of the pool's metrics cannot be registered; either way no goroutine is started.

func (*KeyedPool[W]) Shutdown

func (p *KeyedPool[W]) Shutdown(ctx context.Context) error

Shutdown halts the pool gracefully: it stops accepting new work (SubmitBlocking returns ErrStopped from the first call on), drains each lane's buffered items to completion, and returns nil once every lane has drained and exited. If ctx ends first it returns ctx.Err(); the lanes keep draining and exit once Process returns, and a later Shutdown waits for that and returns nil. Given a ctx with no deadline, Shutdown waits for the join however long it takes: it has no wait of its own. A nil ctx is refused with an error and begins no shutdown.

Shutdown does NOT cancel the pool's run context, so in-flight and buffered Process calls run to completion.

func (*KeyedPool[W]) SubmitBlocking

func (p *KeyedPool[W]) SubmitBlocking(ctx context.Context, work W) error

SubmitBlocking routes work to its lane, blocking until the lane has capacity or the ctx ends (returns ctx.Err()). From the moment Shutdown has begun it returns ErrStopped. This is the backpressure form — a full lane blocks the caller rather than dropping.

Composer note (ADR-072 M3): Shutdown waits for a call already parked on a full lane, and that call returns only when the lane takes its item or its ctx ends. On shutdown, cancel the ctx passed here BEFORE calling Shutdown, so a synchronous producer (e.g. a NATS consume callback) parked here unblocks and can dispose of its message.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL