Documentation
¶
Overview ¶
Package scriptstmt decides how long a managed script's statement may run and records how long it took (#2073): the scripts.sql ceiling a deployment sets, the timeout one trino_query or trino_execute call runs under (the script's timeout_seconds, the tools' default, and never past the time left in the run), and the timing get_run reports the slowest of. It also writes the limit into the error of a statement Trino stopped at it, which the failure's sentence names. Extracted from internal/platform/scriptrun for its size budget.
Index ¶
- Constants
- func ClampTo(args map[string]any, ceiling time.Duration) int
- func IsStatementTool(tool string) bool
- func Slowest(current, next *runstate.StatementTiming) *runstate.StatementTiming
- func Time(tool string, limit Limit, elapsed time.Duration, err error, site []string) *runstate.StatementTiming
- type Bounds
- type Config
- type Limit
- type Statement
Constants ¶
const ( ToolQuery = "trino_query" ToolExecute = "trino_execute" ArgTimeout = "timeout_seconds" )
The tools whose statements run under a timeout the host decides, and the argument the timeout is passed in.
const ( ToolDefaultTimeout = 120 * time.Second ToolMaxTimeout = 300 * time.Second )
The statement timeouts trino_query and trino_execute apply (mcp-trino): the one a call that names no timeout_seconds runs under, and the most a call may name.
const ( LimitDefault = "default" LimitRequested = "requested" LimitRunRemaining = "run_remaining" LimitClamped = "clamped" )
Where a statement's limit came from. LimitClamped is a request above the ceiling run at the ceiling, which only a version saved before the ceiling was enforced gets (#2085).
const MaxTimeoutKey = "scripts.sql.max_timeout_seconds"
MaxTimeoutKey is the configuration key that lowers the timeout a script's statement may ask for.
Variables ¶
This section is empty.
Functions ¶
func ClampTo ¶ added in v1.144.0
ClampTo lowers a timeout_seconds in args above ceiling to the ceiling and returns the seconds that were asked for, zero when it lowered nothing (an absent, unreadable or allowed value is left for Decide). It is applied only to a run of a version saved before the ceiling was enforced (#2085): such a version ran for as long as it existed with mcp-trino cutting the request to 300 seconds, so it keeps running at the ceiling instead of failing every run after an upgrade. A new version is refused above the ceiling by Decide.
func IsStatementTool ¶
IsStatementTool reports whether tool runs a statement under a timeout the host decides.
func Slowest ¶
func Slowest(current, next *runstate.StatementTiming) *runstate.StatementTiming
Slowest is the slower of two timings, the first when they tie; either may be nil.
func Time ¶
func Time(tool string, limit Limit, elapsed time.Duration, err error, site []string) *runstate.StatementTiming
Time is how long a statement call took against its limit. When Trino stopped the statement at the limit it writes the limit into the error's envelope, which the failure's sentence names and a script that asked for its failures reads.
Types ¶
type Bounds ¶ added in v1.144.0
type Bounds struct {
Ceiling, Remaining time.Duration
// Clamp is set for a version saved before the ceiling was enforced
// (#2085), never for a draft or a test: a timeout_seconds above the
// ceiling runs at it instead of being refused, and Log is handed the line
// that says what was lowered and why.
Clamp bool
Log func(string)
}
Bounds is what a run's statement call is decided against: the ceiling, the run's remaining time, and whether the version predates the ceiling.
type Config ¶
type Config struct {
// MaxTimeoutSeconds is the most a script's platform.query,
// platform.execute or platform.call to trino_query or trino_execute may
// pass as timeout_seconds. Zero takes the tools' own cap, 300 seconds,
// which is also the most it may be: the tools cut anything longer.
MaxTimeoutSeconds int `yaml:"max_timeout_seconds"`
}
Config is the scripts.sql section (#2073).
func (Config) MaxTimeout ¶
MaxTimeout is the configured ceiling, the tools' cap when unset.
type Limit ¶
type Limit struct {
Timeout time.Duration
// Source is "default" (the call named none), "requested", or
// "run_remaining" when the run's deadline is nearer than either.
Source string
}
Limit is the timeout one statement runs under and where it came from.
func Decide ¶
Decide sets the timeout one statement call runs under from the timeout_seconds in args (absent is the tools' default), refusing one above ceiling and cutting one the run's remaining time would not outlast. The limit reaches the tool in args when the script named one or it is not the tools' own default, so a call that names no timeout on a deployment that leaves the default alone is the call it always was.
func StatementLimit ¶
StatementLimit decides the timeout a statement runs under: the requested seconds (zero is the tools' default), refused by name above ceiling, and cut to the run's remaining time less a margin, so the run outlasts its statement. A request is never cut to the ceiling: a script that asks for more than the deployment allows is told so.
type Statement ¶
type Statement struct {
// contains filtered or unexported fields
}
Statement is one statement call in progress: the limit it runs under and when it started.
func Begin ¶
Begin decides the limit of a call to tool (Decide) and starts its clock; it is nil, and changes nothing, for a tool that runs no statement.
func (*Statement) End ¶
func (s *Statement) End(err error, site []string) *runstate.StatementTiming
End is the call's timing (Time), nil for no statement.
func (*Statement) MarkClamped ¶ added in v1.144.0
func (s *Statement) MarkClamped()
MarkClamped records that the call's requested limit was lowered to the ceiling (ClampTo), so its timing reports limit_source "clamped". Nil-safe.
Source Files