Documentation
¶
Overview ¶
Package engine implements VegaLoad's core execution engine: the virtual user (VU) scheduler and the load-shape executors that decide how many VUs run, and when, over the life of a scenario.
This package knows nothing about HTTP, gRPC, WebSocket, JavaScript, or Harness RT. It schedules calls to an IterationFunc supplied by the caller — the protocol and scripting layers (built later in Phase 0) are what give that function its real behaviour. See AGENTS.md at the repository root for the module boundary this package is expected to hold.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ConstantArrivalRate ¶
type ConstantArrivalRate struct {
// Rate is the target number of iterations per second.
Rate float64
// Dur is the total duration this executor runs for.
Dur time.Duration
// PreAllocatedVUs is accepted for forward compatibility with
// k6-style arrival-rate configuration. The current implementation
// spawns goroutines on demand up to MaxVUs rather than pre-warming
// a fixed pool, since goroutines are cheap; this field is not yet
// used.
PreAllocatedVUs int
// MaxVUs caps concurrently running iterations. Arrivals beyond
// this cap are dropped. Defaults to 1 if left at 0.
MaxVUs int
}
ConstantArrivalRate starts iterations at a fixed rate, independent of how long each iteration takes — an open workload model. FixedVUs, Ramp, and Step all hold a VU count steady and let each VU run iterations back-to-back (a closed model); under that model, a slow target automatically throttles the iteration rate, because VUs spend longer per iteration. ConstantArrivalRate does not throttle: it keeps starting new iterations on schedule even if earlier ones are still running, which is the point of it — it answers "can this target sustain X requests per second", not "what throughput do N users produce".
If an iteration takes longer than the arrival interval, more than one VU runs concurrently to keep up. MaxVUs caps how many will ever run at once; an arrival that would exceed MaxVUs is dropped and recorded as a failed iteration with VUID -1, rather than queued, so a struggling target doesn't cause unbounded VU growth.
func (ConstantArrivalRate) Duration ¶
func (c ConstantArrivalRate) Duration() time.Duration
Duration implements Executor.
func (ConstantArrivalRate) Name ¶
func (c ConstantArrivalRate) Name() string
Name implements Executor.
func (ConstantArrivalRate) Run ¶
func (c ConstantArrivalRate) Run(ctx context.Context, iter IterationFunc, rec Recorder) error
Run implements Executor.
type Executor ¶
type Executor interface {
// Name identifies the load shape, e.g. "fixed-vus", "ramp".
Name() string
// Duration is the total wall-clock time this executor will run for.
Duration() time.Duration
// Run executes the shape, calling iter for every iteration across
// however many VUs the shape decides to run, and sending every
// result to rec.
Run(ctx context.Context, iter IterationFunc, rec Recorder) error
}
Executor runs a scenario's iterations according to one load shape (fixed-VU, ramp, step, or constant-arrival-rate) and reports every iteration to rec. Run blocks until the shape's duration elapses or ctx is cancelled, whichever comes first.
The four executors in this package are the only four load shapes FR-CLI-04 requires for Phase 0. Adding a fifth later means adding a type that implements this interface — it should never require changing the ones that already exist.
type FixedVUs ¶
FixedVUs runs a constant number of virtual users for a fixed duration. Each VU loops iterations back-to-back for the whole duration. This is the simplest load shape: no ramping, no arrival rate, just "N users, hammering, for T time."
type IterationFunc ¶
IterationFunc runs one iteration of a scenario. It returns a non-nil error if the iteration failed — a connection error, a timeout, a threshold the scenario itself chose to enforce, and so on. A VU calls this repeatedly for as long as its executor keeps it alive.
Implementations should respect ctx cancellation promptly: an executor cancels ctx when the load shape's duration elapses or the run is stopped, and a slow-to-return IterationFunc delays shutdown.
type IterationResult ¶
IterationResult is what the engine records after every iteration. VUID identifies which VU ran the iteration; it has no meaning beyond that, except for ConstantArrivalRate, where -1 marks an arrival that was dropped rather than run (see that executor's doc comment).
type Ramp ¶
type Ramp struct {
Stages []Stage
}
Ramp runs a variable number of virtual users, linearly interpolating the target VU count between each Stage's start and end over that stage's duration — the "ramping-vus" shape k6 and Gatling both call a ramp. The VU count starts at 0 before the first stage.
type Recorder ¶
type Recorder interface {
Record(IterationResult)
}
Recorder receives one IterationResult per completed iteration, from any number of VUs concurrently. Implementations must be safe for concurrent use.
This package ships only Summary, a minimal Recorder for tests and simple use. The real HTML/JSON report (Phase 1, internal/report) will implement this same interface with full percentile tracking — engine does not need to know that package exists.
type Stage ¶
Stage is one segment of a Ramp or Step load shape: hold, or move toward, Target VUs over Duration.
type Step ¶
type Step struct {
Stages []Stage
}
Step runs a variable number of virtual users, holding each Stage's target VU count constant for that stage's duration, then jumping straight to the next stage's target — no interpolation in between, unlike Ramp.
type Summary ¶
type Summary struct {
// contains filtered or unexported fields
}
Summary is a minimal Recorder that keeps running counts: total iterations, failed iterations, and mean duration. It exists so the engine and its tests have something to record into in Phase 0, before internal/report exists. It is not a substitute for that package's real percentile tracking.
func (*Summary) Failed ¶
Failed returns the number of recorded iterations that had a non-nil error, including arrivals ConstantArrivalRate dropped.
func (*Summary) MeanDuration ¶
MeanDuration returns the mean iteration duration across every recorded iteration, including failed ones. It returns 0 if nothing has been recorded yet.