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 ¶
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.
const ( RefusedCeiling = "ceiling" RefusedMemory = "memory" RefusedCPU = "cpu" )
Refusal reasons, as the admission metric labels them.
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) WithDefaults ¶
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 ¶
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
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.
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 ¶
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
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
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 ¶
LoadSource is the replica's load, as procload measures it.