Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,10 @@ served it.

## [Unreleased]

### Added

- `Options.UpgradeStepFactor` and `Options.UpgradeMaxSteps` bound the `UpgradeRoots` pass in solver steps instead of time: its re-solves together may take this many times the first solve's steps, or this many steps. Steps do not depend on the clock, so the same inputs give the same pins on every run, even on a loaded machine. The time bounds still work and can be kept as a backstop, but an answer they cut can differ between runs. With neither new option set, nothing changes.

## [0.25.0] - 2026-11-14

### Changed
Expand Down
9 changes: 9 additions & 0 deletions resolver/export_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -46,3 +46,12 @@ func SetClock(f func() time.Time) (restore func()) {
now = f
return func() { now = time.Now }
}

// RecordSteps records the solver steps of each resolution Resolve runs, the
// first solve then each upgrade re-solve, until restore is called.
// Not safe with parallel tests.
func RecordSteps() (got func() []int, restore func()) {
var all []int
onSteps = func(n int) { all = append(all, n) }
return func() []int { return all }, func() { onSteps = nil }
}
66 changes: 59 additions & 7 deletions resolver/resolver.go
Original file line number Diff line number Diff line change
Expand Up @@ -197,15 +197,34 @@ type Options struct {
// ones are bounded. Zero (the default) means no time bound.
//
// The bound reads the clock, so with it set the answer can differ between
// runs on a loaded machine. It never fails a resolution: the best answer so
// far is returned, as when the budget or ctx ends.
// runs on a loaded machine; UpgradeStepFactor is the repeatable bound. It
// never fails a resolution: the best answer so far is returned, as when the
// budget or ctx ends.
UpgradeTimeFactor float64

// UpgradeMaxTime, when above zero, is an absolute cap on the time the
// UpgradeRoots pass may run, including a re-solve in progress, which is
// stopped at the cap. It applies together with UpgradeTimeFactor; whichever
// limit is reached first ends the pass. Zero (the default) means no cap.
UpgradeMaxTime time.Duration

// UpgradeStepFactor, when above zero, bounds the UpgradeRoots pass in
// solver steps: all its re-solves together may take this many times the
// steps the first solve took. A step is one round of the solver's main loop
// or one step of conflict resolution. A re-solve that reaches the bound is
// stopped, counts as no gain, and ends the pass. Zero (the default) means
// no step bound.
//
// Unlike the time bounds, steps do not depend on the clock or machine load,
// so the same inputs give the same answer every run. Use a step bound to
// limit the pass; keep a time bound only as a backstop, since an answer it
// cuts can still differ between runs.
UpgradeStepFactor float64

// UpgradeMaxSteps, when above zero, is an absolute cap on the solver steps
// all UpgradeRoots re-solves may take together. It applies together with
// UpgradeStepFactor; the lower bound wins. Zero (the default) means no cap.
UpgradeMaxSteps int
}

// Resolution is a successful resolution: one version chosen for every package
Expand Down Expand Up @@ -370,11 +389,36 @@ func Resolve(
opts Options,
) (*Resolution, error) {
start := now()
res, err := resolveOnce(ctx, reqs, idx, opts)
steps := &stepMeter{}
res, err := resolveOnce(ctx, reqs, idx, opts, steps)
if err != nil || opts.UpgradeRoots <= 0 {
return res, err
}
return upgradeRoots(ctx, reqs, idx, opts, res, now().Sub(start)), nil
return upgradeRoots(ctx, reqs, idx, opts, res, now().Sub(start), steps.used), nil
}

// stepMeter counts the solver steps of one resolution, across all its solves,
// and stops it once limit steps are used. Zero limit means no limit.
type stepMeter struct {
used, limit int
}

// errStepBudget stops a re-solve that used the upgrade pass's last step.
var errStepBudget = errors.New("resolver: upgrade step budget spent")

// interrupt is the solver's Interrupt: the solver calls it once per step,
// on one goroutine, so the count depends only on the inputs.
func (m *stepMeter) interrupt(ctx context.Context) func() error {
return func() error {
if err := ctx.Err(); err != nil {
return err
}
if m.limit > 0 && m.used >= m.limit {
return errStepBudget
}
m.used++
return nil
}
}

// providerOptions maps Options to the provider's options for one resolution.
Expand All @@ -396,13 +440,18 @@ func providerOptions(reqs []requirement.Requirement, opts Options) provider.Opti
}
}

// resolveOnce is one resolution, with no upgrade pass.
// resolveOnce is one resolution, with no upgrade pass. steps counts its
// solver steps and may stop it.
func resolveOnce(
ctx context.Context,
reqs []requirement.Requirement,
idx index.MetadataIndex,
opts Options,
steps *stepMeter,
) (*Resolution, error) {
if onSteps != nil {
defer func() { onSteps(steps.used) }()
}
if err := validate(opts); err != nil {
return nil, err
}
Expand Down Expand Up @@ -436,8 +485,8 @@ func resolveOnce(
s.ClashThreshold = opts.ClashThreshold
s.ClashFirst = opts.ClashFirst
s.MaxConflicts = opts.MaxConflicts
// Stop on cancel or deadline; the error unwraps to ctx.Err().
s.Interrupt = ctx.Err
// Stop on cancel, deadline or step budget; the error unwraps to the cause.
s.Interrupt = steps.interrupt(ctx)
if onSolver != nil {
onSolver(s)
}
Expand Down Expand Up @@ -506,6 +555,9 @@ var now = time.Now
// onSolve, when set by a test, is called before each solve.
var onSolve func()

// onSteps, when set by a test, gets the steps each resolveOnce used.
var onSteps func(int)

// onSolver, when set by a test, sees each Solver after Resolve has configured it.
var onSolver func(*solver.Solver[provider.Package, pep440set.Set])

Expand Down
46 changes: 40 additions & 6 deletions resolver/upgrade.go
Original file line number Diff line number Diff line change
Expand Up @@ -222,22 +222,46 @@ func upgradeTimeLimit(opts Options, baseDur time.Duration) (limit time.Duration,
return limit, ok
}

// upgradeStepLimit is how many solver steps the pass's re-solves may take in
// all, from the options and the first solve's steps. ok is false when neither
// bound is set.
func upgradeStepLimit(opts Options, baseSteps int) (limit int, ok bool) {
if opts.UpgradeMaxSteps > 0 {
limit, ok = opts.UpgradeMaxSteps, true
}
if opts.UpgradeStepFactor > 0 {
// A huge factor is no bound; it must not overflow the int.
if f := float64(baseSteps) * opts.UpgradeStepFactor; f < math.MaxInt {
if n := int(f); !ok || n < limit {
limit, ok = n, true
}
}
}
return limit, ok
}

// upgradeRoots is the pass behind Options.UpgradeRoots. base is a valid answer
// to reqs, and baseDur is how long it took; the result is base or a valid
// answer that scores strictly better.
// to reqs, and baseDur and baseSteps are what it took; the result is base or a
// valid answer that scores strictly better.
func upgradeRoots(
ctx context.Context,
reqs []requirement.Requirement,
idx index.MetadataIndex,
opts Options,
base *Resolution,
baseDur time.Duration,
baseSteps int,
) *Resolution {
passStart := now()
limit, timed := upgradeTimeLimit(opts, baseDur)
// cut is set once a re-solve is stopped by the bound; the pass then ends.
stepLimit, stepped := upgradeStepLimit(opts, baseSteps)
spent := 0 // solver steps the re-solves have used
// cut is set once a re-solve is stopped by the time bound; the pass then
// ends. A re-solve stopped by the step bound leaves spent at stepLimit.
cut := false
timeUp := func() bool { return cut || (timed && now().Sub(passStart) >= limit) }
timeUp := func() bool {
return cut || (stepped && spent >= stepLimit) || (timed && now().Sub(passStart) >= limit)
}
u := &usability{
p: provider.New(ctx, idx, providerOptions(reqs, opts)),
memo: map[usableKey]bool{},
Expand Down Expand Up @@ -265,6 +289,11 @@ func upgradeRoots(
if err != nil {
return nil
}
// Callers check timeUp first, so this cannot fire; it keeps a zero
// meter limit, which means no limit, from ever reaching resolveOnce.
if stepped && spent >= stepLimit {
return nil
}
budget--
all := append(slices.Clone(reqs), floor)
solveCtx := ctx
Expand All @@ -274,9 +303,14 @@ func upgradeRoots(
defer cancel()
solveCtx = c
}
got, err := resolveOnce(solveCtx, all, idx, inner)
steps := &stepMeter{}
if stepped {
steps.limit = stepLimit - spent
}
got, err := resolveOnce(solveCtx, all, idx, inner, steps)
spent += steps.used
if err != nil {
// Stopped by the bound, not the caller: no gain, and the pass ends.
// Stopped by the time bound, not the caller: no gain, and the pass ends.
if ctx.Err() == nil && solveCtx.Err() != nil {
cut = true
}
Expand Down
Loading
Loading