admission

package
v0.3.0-beta.37 Latest Latest
Warning

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

Go to latest
Published: Oct 20, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package admission owns the daemon-wide new-work admission boundary.

Index

Constants

View Source
const DefaultLoadSampleInterval = 5 * time.Second

DefaultLoadSampleInterval is how often the load monitor reads the host load average.

Variables

View Source
var ErrDraining = errors.New("daemon is draining; new work admission is closed")

ErrDraining reports that the daemon is temporarily refusing new work.

View Source
var ErrLoadAverageUnsupported = errors.New("admission: load average is unsupported on this platform")

ErrLoadAverageUnsupported reports a platform without a cheap load-average source.

Functions

func IsBackgroundWork

func IsBackgroundWork(ctx context.Context) bool

IsBackgroundWork reports whether ctx carries the background-work marker.

func WithBackgroundWork

func WithBackgroundWork(ctx context.Context) context.Context

WithBackgroundWork marks ctx as daemon-initiated background work (automation, Loop, scheduler wakes). Background work yields to host CPU pressure at admission; unmarked work is treated as user-initiated and never waits.

Types

type Checker

type Checker interface {
	Check(context.Context) error
}

Checker is the read-only admission surface injected into work owners.

type Gate

type Gate struct {
	// contains filtered or unexported fields
}

Gate is a concurrency-safe, in-memory daemon admission gate.

func (*Gate) Check

func (g *Gate) Check(ctx context.Context) error

Check admits active daemons and rejects new work while draining. Background work (see WithBackgroundWork) first waits, bounded, for host CPU pressure to clear.

func (*Gate) Drain

func (g *Gate) Drain() bool

Drain closes the gate and reports whether this call changed the state.

func (*Gate) SetLoadMonitor

func (g *Gate) SetLoadMonitor(monitor *LoadMonitor)

SetLoadMonitor attaches host-load-aware admission for background work; nil detaches it.

func (*Gate) State

func (g *Gate) State() State

State returns the current admission state.

func (*Gate) Undrain

func (g *Gate) Undrain() bool

Undrain opens the gate and reports whether this call changed the state.

type LoadMonitor

type LoadMonitor struct {
	// contains filtered or unexported fields
}

LoadMonitor samples host load and holds background admissions while the host is saturated.

func NewLoadMonitor

func NewLoadMonitor(cfg LoadMonitorConfig) *LoadMonitor

NewLoadMonitor constructs a monitor; Start begins sampling.

func (*LoadMonitor) Shutdown

func (m *LoadMonitor) Shutdown(ctx context.Context) error

Shutdown stops sampling, releases waiters, and joins the sampling goroutine.

func (*LoadMonitor) Snapshot

func (m *LoadMonitor) Snapshot() LoadSnapshot

Snapshot returns the latest pressure observation.

func (*LoadMonitor) Start

func (m *LoadMonitor) Start(ctx context.Context) error

Start takes a baseline sample and starts the sampling goroutine. A zero threshold or an unsupported platform leaves the monitor permanently idle.

func (*LoadMonitor) Wait

func (m *LoadMonitor) Wait(ctx context.Context) error

Wait holds the caller while the host is pressured, up to MaxWait. It returns nil once pressure clears or the bound elapses, and ctx's error if ctx ends first.

type LoadMonitorConfig

type LoadMonitorConfig struct {
	// Threshold is the 1-minute load average divided by logical CPUs above which
	// background work waits. Zero disables the monitor entirely.
	Threshold float64
	// MaxWait bounds how long one background admission waits before proceeding.
	MaxWait time.Duration
	// Interval is the sampling cadence; nonpositive uses DefaultLoadSampleInterval.
	Interval time.Duration
	Logger   *slog.Logger

	// Sample and LogicalCPUs are test seams; nil/zero use the platform source.
	Sample      func() (float64, error)
	LogicalCPUs int
	Now         func() time.Time
}

LoadMonitorConfig configures host-load-aware admission.

type LoadSnapshot

type LoadSnapshot struct {
	Enabled        bool
	Supported      bool
	Pressured      bool
	Threshold      float64
	MaxWait        time.Duration
	LogicalCPUs    int
	Load1          float64
	NormalizedLoad float64
	SampledAt      time.Time
	Waiting        int
	Deferred       uint64
	WaitExpired    uint64
}

LoadSnapshot is one immutable view of host CPU pressure as seen by admission.

type State

type State string

State is the closed set of daemon admission states.

const (
	StateActive   State = "active"
	StateDraining State = "draining"
)

Jump to

Keyboard shortcuts

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