Documentation
¶
Overview ¶
Package scaler implements the dynamic worker scaler shared by the iouring, epoll, and adaptive engines. The scaler tracks the active connection count and adjusts how many workers participate in the SO_REUSEPORT group so connections-per-active-worker stays near the configured target — this keeps CQE/event batching density in the sweet spot.
Engines plug in via the Source interface. Per-engine sources (engine/iouring/scaler.go, engine/epoll/scaler.go, adaptive/scaler.go) adapt the engine to this contract; the algorithm in Run is shared.
Implementation is Linux-only because the underlying engines that surface a Source are themselves Linux-only. This package compiles to an empty stub on non-Linux GOOS so godoc and reflection-based tooling still see the public types and contract.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Config ¶
type Config struct {
// Enabled gates the entire scaler. Resolve sets this to true when
// either the typed config or the CELERIS_DYN_WORKERS env is set.
Enabled bool
// StartHigh seeds the scaler at NumWorkers active and scales down
// on idle. Default true (data-validated; preserves SO_REUSEPORT
// distribution at startup, +34-78% over start-low on ramp scenarios).
StartHigh bool
// MinActive is the floor on active worker count.
MinActive int
// TargetConnsPerWorker is the scaling target. desired = ceil(conns/Target).
TargetConnsPerWorker int
// Interval is the tick cadence. Default 250ms.
Interval time.Duration
// ScaleUpStep is the max workers added per tick (burst limit).
ScaleUpStep int
// ScaleDownStep is the max workers removed per tick.
ScaleDownStep int
// ScaleDownHysteresis: scale-down requires desired ≤ active - hyst - 1.
ScaleDownHysteresis int
// ScaleDownIdleTicks: consecutive sub-threshold ticks needed to scale down.
ScaleDownIdleTicks int
// Trace logs every scaler decision when true.
Trace bool
}
Config holds the resolved scaler parameters. All fields are mutable before Run starts; the loop reads them once at startup. Use Resolve to derive a Config from a resource.Config (handles both the typed WorkerScaling field and the env-var fallback).
type Source ¶
type Source interface {
// NumWorkers returns the total worker pool size (= max active count).
// Must be stable across the lifetime of a scaler run.
NumWorkers() int
// ActiveConns returns the current active connection count. Read every tick.
ActiveConns() int64
// PauseWorker deactivates worker i. Idempotent.
PauseWorker(i int)
// ResumeWorker reactivates worker i. Idempotent.
ResumeWorker(i int)
// Generation returns a counter that increments whenever the
// underlying engine identity changes (e.g., adaptive engine switch).
// Per-engine sources return 0 always. The scaler uses this to detect
// switches and re-baseline the active count on the new engine.
Generation() uint64
// Logger returns the slog.Logger used for scaler diagnostics. May
// return nil to suppress log output.
Logger() *slog.Logger
}
Source is the engine-side interface the scaler uses to read load and adjust worker activation. Implementations must be safe for concurrent use; the scaler calls these from its own goroutine.
Source Files