README
¶
speculator
The speculator package defines the one speculation extension the speculate controller calls. A Speculator decides which speculation paths to build and which running ones to cancel, within the queue's build budget — and nothing else. It can never express a verdict: whether a batch merges or fails is fixed by the facts and computed by the controller, so swapping in a different Speculator changes which paths run, never a batch's outcome.
Speculate is handed the queue's in-flight batches plus any finalized batches still referenced as dependencies (each with its dependency list and state) and every path set for them — live and recently finished, so a Speculator will not re-propose a path that already passed or failed. It returns a list of build and cancel actions; a path it wants left as-is has no entry in the result. The controller validates the output (dropping builds it shouldn't propose and rejecting cancels of passed paths), so an implementation may read extra injected data without affecting correctness.
Cancel is a Speculator's only cancel power — preempting an in-flight path to free budget for a better candidate. Correctness cancels (refuting a path whose bet a resolved dependency broke, and batch cancellation) belong to the controller and are not routed through the extension.
Like the other extensions, a Speculator is selected per queue by the wiring layer through the Config (queue name) and Factory interface. Budget, clock, and any extra data are injected at construction by the integrator, not carried on the contract.
Adding a backend
Create a package under speculator/<backend>/ whose New(...) returns a speculator.Speculator, injecting whatever it needs at construction. Resolve any content it requires internally; do not add a Config or Factory implementation here — per-queue routing and the factory adapter live in the wiring layer.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// QueueName identifies the queue this Speculator serves.
QueueName string
}
Config carries the per-queue identity handed to a Factory. The system knows only the queue name; everything an implementation needs is injected at construction by the integrator.
type Factory ¶
type Factory interface {
// For returns the Speculator for the given queue.
For(cfg Config) (Speculator, error)
}
Factory builds the Speculator for a queue. Implementations are provided by integrators (and tests) and inject whatever they need — budget, clock, and any extra data — at construction.
type Speculator ¶
type Speculator interface {
// Speculate proposes this run's path actions.
//
// Arguments:
// - batches: every in-flight batch of the queue, plus any finalized batch
// still referenced as a dependency by an in-flight one. Each carries its
// dependency list and state.
// - pathSets: every materialized path set for those batches, holding live
// and recently finished entries, so an implementation can avoid
// re-proposing a path that already passed or failed.
//
// Returns:
// - the proposed actions: a build funds a path, a cancel preempts an
// in-flight one. A path to be left as-is has no entry, so an empty
// result means the queue needs no changes. Order carries no meaning.
// - error: reserved for infrastructure failures — a failed dependency of
// the implementation, or ctx cancellation/expiry, which is passed
// through unwrapped enough for errors.Is(err, context.Canceled) and
// context.DeadlineExceeded to hold. Per the platform/errs rules the
// error is plain (never classified here), and "nothing worth doing" is
// an empty result, not an error. On error the actions are nil and the
// run is abandoned; the next dirty signal retries with fresh state.
Speculate(ctx context.Context, batches []entity.Batch, pathSets []entity.SpeculationPathSet) ([]entity.Speculation, error)
}
Speculator decides which speculation paths to build and which running ones to cancel, within the queue's build budget. It is the only speculation extension the speculate controller calls. It can never express a verdict: whether a batch merges or fails is fixed by the facts and computed by the controller, so a swapped-in Speculator changes which paths run, never a batch's outcome.
Source Files
Directories