scriptadmit

package
v1.135.1 Latest Latest
Warning

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

Go to latest
Published: Sep 24, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package scriptadmit decides how many managed-script runs one replica executes at once, and owns the scripts.worker settings that say so (#1843).

A run spends most of its life waiting on a query engine or an upstream API, so a replica's capacity is its free memory and CPU, not a count. Admission is adaptive by default: another run is claimed only while the process's memory and CPU, as internal/procload measures them, are under their thresholds, between a floor that keeps a replica making progress and a ceiling it never passes. The run worker in internal/platform/scriptexec asks before every claim and, past the shed threshold, stops its newest run.

Index

Constants

View Source
const (
	// DefaultMaxConcurrency is the ceiling adaptive admission never passes,
	// whatever headroom the replica reports.
	DefaultMaxConcurrency = 16

	// DefaultMinConcurrency is how many runs adaptive admission always admits,
	// whatever the load, so a replica never stops making progress.
	DefaultMinConcurrency = 1

	// DefaultMaxMemoryPercent is the memory, as a share of the container's
	// limit, above which no further run is claimed. The rest is headroom for
	// the runs already admitted, which keep growing after the decision.
	DefaultMaxMemoryPercent = 70

	// DefaultMaxCPUPercent is the CPU, as a share of the container's quota,
	// above which no further run is claimed.
	DefaultMaxCPUPercent = 75

	// DefaultShedMemoryPercent is the memory above which the most recently
	// started run is stopped and requeued, so a replica sheds work before the
	// container is killed with all of it.
	DefaultShedMemoryPercent = 90
)

Admission defaults (#1843). A run spends most of its life waiting on a query engine or an upstream API, so a replica's capacity is its free memory and CPU, not a count; these are the bounds that turn that into a claim decision.

View Source
const (
	RefusedCeiling = "ceiling"
	RefusedMemory  = "memory"
	RefusedCPU     = "cpu"
)

Refusal reasons, as the admission metric labels them.

View Source
const DefaultRunMemoryPercent = 50

DefaultRunMemoryPercent is the share of the container's memory limit one run may hold when scripts.worker.max_run_memory is unset (#1861). Half leaves the other half for the runs beside it, the sessions the replica serves, and the garbage collector's headroom.

Variables

This section is empty.

Functions

This section is empty.

Types

type Admission

type Admission struct {
	Fixed             int
	Min               int
	Max               int
	MaxMemoryPercent  float64
	MaxCPUPercent     float64
	ShedMemoryPercent float64
}

Admission is how many runs this replica executes at once.

Fixed > 0 is a fixed number, and 1 is the one-at-a-time worker every replica ran before #1843. Fixed == 0 is adaptive: a run is claimed while fewer than Min are executing, or while fewer than Max are and the replica's memory and CPU are both under their thresholds. A measurement the platform cannot take (no container memory limit, no CPU time on this OS) never refuses; the ceiling still applies.

func (Admission) Adaptive

func (a Admission) Adaptive() bool

Adaptive reports whether admission follows the replica's load.

func (Admission) WithDefaults

func (a Admission) WithDefaults() Admission

WithDefaults fills every unset bound. A value at or below zero is unset.

type Admitter

type Admitter struct {
	Admission
	// contains filtered or unexported fields
}

Admitter applies an Admission to the load a source reports.

func NewAdmitter

func NewAdmitter(adm Admission, load LoadSource) Admitter

NewAdmitter applies adm, with its unset bounds defaulted, to the load a source reports; a nil source reads this process through procload.

func (Admitter) Admit

func (a Admitter) Admit(inFlight int) (ok bool, reason string)

Admit decides whether one more run may be claimed while inFlight are executing, and names the reason when it may not.

func (Admitter) OverShed added in v1.135.1

func (a Admitter) OverShed() (over bool, reason string)

OverShed reports whether the replica's memory is past the shed threshold, with a sentence saying so for the run the worker stops (#1861). It answers under every admission, because it is what stands between the only run a replica is executing and the kernel killing the container: Shed never stops the last run, since requeueing it would rebuild the same heap elsewhere, so the last run over the line is failed instead. A replica whose memory the platform cannot measure is never over.

func (Admitter) Shed

func (a Admitter) Shed(live int) bool

Shed reports whether a run should be stopped to relieve memory while live runs are executing. Only adaptive admission sheds, and never its last run: a single run over the line is that script's own size, and stopping it would only rebuild the same heap wherever it ran next.

type Config

type Config struct {
	// Concurrency is "adaptive" (the default, as are empty, zero and a
	// negative number) or a whole number of runs executed at once; 1 is the
	// one-at-a-time worker of earlier releases.
	Concurrency string `yaml:"concurrency"`
	// MaxConcurrency and MinConcurrency bound adaptive admission.
	MaxConcurrency int `yaml:"max_concurrency"`
	MinConcurrency int `yaml:"min_concurrency"`
	// MaxMemoryPercent and MaxCPUPercent are the shares of the container's
	// memory limit and CPU quota above which no further run is claimed;
	// ShedMemoryPercent is the memory above which the newest run is stopped.
	MaxMemoryPercent  float64 `yaml:"max_memory_percent"`
	MaxCPUPercent     float64 `yaml:"max_cpu_percent"`
	ShedMemoryPercent float64 `yaml:"shed_memory_percent"`
	// RunTimeout, MaxSteps and MaxQueryRows are a platform run's ceilings:
	// wall clock, interpreter steps, and the rows one platform.query may
	// return. The worker derives the claim lease from RunTimeout.
	RunTimeout   time.Duration `yaml:"run_timeout"`
	MaxSteps     int64         `yaml:"max_steps"`
	MaxQueryRows int           `yaml:"max_query_rows"`
	// ResultMaxBytes caps the value a run hands back with platform.result
	// (#1845, default 1 MiB).
	ResultMaxBytes int `yaml:"result_max_bytes"`
	// MaxReclaims is how many times a run is taken over from a worker whose
	// lease expired before it is failed instead (#1860, default 2).
	MaxReclaims int `yaml:"max_reclaims"`
	// MaxRunMemory is how much memory one run may hold (#1861): an absolute
	// size ("300MiB", "1GiB"), a share of the container's memory limit
	// ("50%"), or "unlimited". Empty is DefaultRunMemoryPercent of the limit
	// where the platform can read one, and no budget where it cannot.
	MaxRunMemory string `yaml:"max_run_memory"`
}

Config is the capacity half of the scripts.worker configuration block, inlined there beside enabled. Every field is optional; zero or a negative number takes the default.

func (Config) Admission

func (c Config) Admission() (Admission, error)

Admission reads the configured admission. A Concurrency that is neither "adaptive" nor a whole number is refused, so a misspelling fails at startup rather than quietly running adaptive.

func (Config) ProcessRunMemoryBudget added in v1.135.1

func (c Config) ProcessRunMemoryBudget() int64

ProcessRunMemoryBudget is RunMemoryBudget against this process's memory limit, which a platform run and a draft on this replica share. A value it cannot read sets no budget; Config validation refuses one at startup.

func (Config) RunMemoryBudget added in v1.135.1

func (c Config) RunMemoryBudget(limit int64) (int64, error)

RunMemoryBudget is the bytes one run may hold, given the container's memory limit (0 when none is known), or 0 for no budget. A value it cannot read is refused, so a misspelling fails at startup rather than quietly running without a budget.

type LoadSource

type LoadSource interface {
	Sample() procload.Sample
}

LoadSource is the replica's load, as procload measures it.

Jump to

Keyboard shortcuts

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