README
¶
generator
The generator package is a piece the standard Speculator is built from: a Generator produces the queue's candidate paths as one ordered stream across all heads. It is not controller-facing — the speculate controller only knows the Speculator contract, and a different Speculator need not split its work this way. So there is no Config or Factory here; a Generator is chosen when the standard Speculator is constructed.
Generate starts the stream over the queue's live batches and returns an Iterator. Beyond any ranking work required up front, the generator computes only the candidates the caller pulls. A cancelled or expired context ends the stream with its error. The snapshot must include every batch a head's direct dependencies reference, carry unique non-empty IDs, and give no head an empty, duplicate, or self dependency. Those are the caller's preconditions: a generator may assume them and is not required to detect a breach, so a malformed snapshot yields undefined candidates rather than an error.
Candidates never repeat and never contradict a known fact. Beyond that, the order is the Generator's own: it yields candidates in whatever ranking it implements, and each carries the score it ranked by — higher first, on a scale the generator defines. Consumers take the iterator in the order given and do not interpret the score. Scores mean something only within the run and are never stored.
The generator offers every path in the space, including paths whose builds already ran. Suppressing finished paths is the Allocator's job, since that is the piece reconciling candidates against the stored path sets.
Documentation
¶
Overview ¶
Package generator defines the candidate-stream composition point used by the standard Speculator. A Generator yields candidate paths through a pull iterator, in an order it chooses; it is not a controller-facing extension — an alternate Speculator need not use or expose this split.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Generator ¶
type Generator interface {
// Generate starts the candidate stream. The consumer pulls candidates lazily
// from the returned iterator. A cancelled or expired ctx aborts with its
// error and no iterator.
//
// batches is treated as a snapshot: a generator may hold it, and the
// dependency slices within it, for as long as the iterator lives rather
// than copying them. Callers must not write to either while pulling. A
// queue that has moved on is a new snapshot and a new Generate, which is how
// batches are revised anyway — they are replaced, not edited in place.
//
// A well-formed snapshot carries unique, non-empty batch IDs, includes every
// batch a head's direct dependencies reference, and gives no head an empty,
// duplicate, or self dependency. That is a precondition the caller owns: a
// generator may assume it and is not required to detect a breach, so a
// malformed snapshot yields undefined candidates rather than an error.
Generate(ctx context.Context, batches []entity.Batch) (Iterator, error)
}
Generator produces the queue's candidate paths as a pull-based stream over the queue's live batches. The order candidates are yielded in, and how they are ranked, is the generator's own policy.
type Iterator ¶
type Iterator interface {
// Next yields the next candidate in the generator's order. ok is false once
// the generator has no more candidates to offer. Candidates never repeat and
// never contradict a resolved fact — a dependency that already succeeded is
// never assumed to fail, and one that already failed is never assumed to
// succeed.
//
// A cancelled or expired ctx ends the stream with its error, ok false, and
// no candidate.
Next(ctx context.Context) (c entity.CandidatePath, ok bool, err error)
}
Iterator is a pull-based stream of candidate paths. Beyond what ranking requires up front, the producer computes only what is pulled.
Source Files
Directories