Help us shape the future of Go! Take the 2026 Go Developer Survey

admission

package
v0.13.0 Latest Latest
Warning

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

 Go to latest Published: Oct 23, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package admission provides opt-in, single-process resource admission. It queues bounded payloads and invokes a caller-owned Go executor exactly once. Reservations are estimates: this package neither allocates OS resources nor changes model requests, kills work under pressure, retries, or selects providers.

Index

Constants

View Source 
const (
	LaneBroker            = "broker"
	LaneReplication       = "replication"
	LaneInference         = "inference"
	LaneRevision          = "revision"
	MiB             int64 = 1 << 20
	// QueueEntryBytes charges metadata in addition to copied ID/lane/payload.
	// It cannot account for memory retained by the caller's context or executor.
	QueueEntryBytes int64 = 512
)

Variables

View Source 
var (
	ErrConfiguration = errors.New("admission_configuration_invalid")
	ErrPaused        = errors.New("admission_paused")
	ErrQueueFull     = errors.New("admission_queue_full")
	ErrDoesNotFit    = errors.New("admission_reservation_does_not_fit")
	ErrDuplicate     = errors.New("admission_job_id_already_present")
	ErrRunning       = errors.New("admission_controller_already_running")
	ErrExecutorPanic = errors.New("admission_executor_panicked_outcome_requires_inspection")
	ErrSignals       = errors.New("admission_resource_signals_unavailable")
)

Functions

This section is empty.

Types

type Config 

type Config struct {
	MinWorkers                  int           `json:"min_workers"`
	MaxWorkers                  int           `json:"max_workers"`
	MaxQueueRows                int           `json:"max_queue_rows"`
	MaxQueueBytes               int64         `json:"max_queue_bytes"`
	ProtectedQueueRows          int           `json:"protected_queue_rows"`
	ProtectedQueueBytes         int64         `json:"protected_queue_bytes"`
	ProtectedCPUMilli           int64         `json:"protected_cpu_milli"`
	ProtectedMemoryBytes        int64         `json:"protected_memory_bytes"`
	MemoryHeadroomBytes         int64         `json:"memory_headroom_bytes"`
	QueueMemoryPercent          int64         `json:"queue_memory_percent"`
	QueueRowsPerWorker          int           `json:"queue_rows_per_worker"`
	RecoverySamples             int           `json:"recovery_samples"`
	RampInterval                time.Duration `json:"ramp_interval"`
	SampleInterval              time.Duration `json:"sample_interval"`
	MaxSampleAge                time.Duration `json:"max_sample_age"`
	ProbeTimeout                time.Duration `json:"probe_timeout"`
	TaskTimeout                 time.Duration `json:"task_timeout"`
	CPULoadHighMilli            int64         `json:"cpu_load_high_milli"`
	CPULoadLowMilli             int64         `json:"cpu_load_low_milli"`
	CPUStallHighMilliPercent    int64         `json:"cpu_stall_high_milli_percent"`
	CPUStallLowMilliPercent     int64         `json:"cpu_stall_low_milli_percent"`
	MemoryStallHighMilliPercent int64         `json:"memory_stall_high_milli_percent"`
	MemoryStallLowMilliPercent  int64         `json:"memory_stall_low_milli_percent"`
	Lanes                       []Lane        `json:"lanes"`
}

Durations encode as nanoseconds in JSON. LoadConfig supports strict complete configurations, while Go callers can modify DefaultConfig before New.

func DefaultConfig 

func DefaultConfig() Config

func LoadConfig 

func LoadConfig(r io.Reader) (Config, error)

func (Config) Validate 

func (c Config) Validate() error

type Executor 

type Executor func(context.Context, Job) error

type Job 

type Job struct {
	ID      string
	Lane    string
	Payload []byte
}

type Lane 

type Lane struct {
	Name        string `json:"name"`
	CPUMilli    int64  `json:"cpu_milli"`
	MemoryBytes int64  `json:"memory_bytes"`
	MaxWorkers  int    `json:"max_workers"`
	// Protected is for cheap persistence/health, never for model generation.
	// Its bounded static allowance remains usable when expensive work pauses.
	Protected bool `json:"protected"`
}

type Outcome 

type Outcome struct {
	ID     string `json:"id"`
	Lane   string `json:"lane"`
	Status string `json:"status"`
	Err    error  `json:"-"`
}

type Pressure 

type Pressure string
const (
	Normal   Pressure = "normal"
	High     Pressure = "high"
	Critical Pressure = "critical"
)

type Scheduler 

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

Scheduler owns one process-local queue. Construct one shared instance for broker, replication and inference lanes. Separate instances/processes do not coordinate capacity. No completed-job history or automatic retry is retained.

func New 

func New(c Config, execute Executor) (*Scheduler, error)

func (*Scheduler) Pending 

func (s *Scheduler) Pending() []Job

Pending returns copied payloads for explicit inspection/recovery. This queue is in memory; durable edge intents remain owned by their store. Run cancellation stops dispatch, retaining pending entries. It does not cancel running callbacks.

func (*Scheduler) Run 

func (s *Scheduler) Run(ctx context.Context, source Source) error

Run samples resources and dispatches work. Source and Executor must honor their contexts. A callback ignoring cancellation remains counted until it returns; it never creates a replacement slot or an automatic retry.

func (*Scheduler) Status 

func (s *Scheduler) Status() Status

func (*Scheduler) Submit 

func (s *Scheduler) Submit(ctx context.Context, j Job) (<-chan Outcome, error)

Submit copies bounded job data. Rejection never calls the executor. Payloads should contain small operation IDs, not credentials or duplicate durable bodies. A result channel contains exactly one outcome. Context cancellation of queued work is explicit cancellation; pressure never removes queued work.

func (*Scheduler) Update 

func (s *Scheduler) Update(snapshot Snapshot)

Update applies fresh measurements. Pressure shrinks immediately; recovery needs consecutive low-pressure samples and increases at most one worker per ramp interval. MinWorkers is only a goal: safety can pause all expensive work.

type Snapshot 

type Snapshot struct {
	At                      time.Time `json:"at"`
	Known                   bool      `json:"known"`
	Source                  string    `json:"source"`
	CPUCapacityMilli        int64     `json:"cpu_capacity_milli"`
	LoadCapacityMilli       int64     `json:"load_capacity_milli"`
	LoadMilli               int64     `json:"load_milli"`
	CPUStallMilliPercent    int64     `json:"cpu_stall_milli_percent"`
	AvailableMemoryBytes    int64     `json:"available_memory_bytes"`
	MemoryPressure          Pressure  `json:"memory_pressure"`
	MemoryStallMilliPercent int64     `json:"memory_stall_milli_percent"`
}

LoadMilli is the one-minute runnable/waiting system load, not CPU percent. It is normalized by LoadCapacityMilli; cgroup PSI separately captures stalls. AvailableMemoryBytes is conservative headroom, not a guaranteed allocation.

type Source 

type Source interface {
	Sample(context.Context) (Snapshot, error)
}

func SystemSource 

func SystemSource() Source

type SourceFunc 

type SourceFunc func(context.Context) (Snapshot, error)

func (SourceFunc) Sample 

func (f SourceFunc) Sample(ctx context.Context) (Snapshot, error)

type Status 

type Status struct {
	Snapshot                     Snapshot       `json:"snapshot"`
	Reason                       string         `json:"reason"`
	ExpensiveWorkerLimit         int            `json:"expensive_worker_limit"`
	PotentialWorkers             int            `json:"potential_workers"`
	Active                       int            `json:"active"`
	ActiveByLane                 map[string]int `json:"active_by_lane"`
	QueuedRows                   int            `json:"queued_rows"`
	QueuedBytes                  int64          `json:"queued_bytes"`
	DynamicQueueRows             int            `json:"dynamic_queue_rows"`
	DynamicQueueBytes            int64          `json:"dynamic_queue_bytes"`
	CPUReservedMilli             int64          `json:"cpu_reserved_milli"`
	MemoryReservedBytes          int64          `json:"memory_reserved_bytes"`
	ReservationsAreOSEnforcement bool           `json:"reservations_are_os_enforcement"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.