Documentation
¶
Overview ¶
Package sim...
TODO(mwhittaker): Write comprehensive package documentation with examples. We also probably want to put some of this documentation on the website, and we might also want to write a blog.
TODO(mwhittaker): Move things to the weavertest package.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Call ¶
type Call struct {
TraceID int // trace id
SpanID int // span id
Caller string // calling component (or "op")
Replica int // calling component replica (or op number)
Component string // component being called
Method string // method being called
Args []string // method arguments
}
Call represents a component method call.
type DeliverCall ¶
type DeliverCall struct {
TraceID int // trace id
SpanID int // span id
Component string // component being called
Replica int // component replica being called
}
DeliverCall represents a component method call being delivered.
type DeliverError ¶
DeliverError represents the injection of an error.
type DeliverReturn ¶
DeliverReturn represents the delivery of a method return.
type Event ¶
type Event interface {
// contains filtered or unexported methods
}
An Event represents an atomic step of a simulation.
type FakeComponent ¶
type FakeComponent struct {
// contains filtered or unexported fields
}
FakeComponent is a copy of weavertest.FakeComponent. It's needed to access the unexported fields.
TODO(mwhittaker): Remove this once we merge with weavertest.
func Fake ¶
func Fake[T any](impl any) FakeComponent
Fake is a copy of weavertest.Fake.
TODO(mwhittaker): Remove this once we merge with the weavertest package.
type Generator ¶
type Generator[T any] interface { // Generate returns a randomly generated value of type T. While Generate is // "random", it must be deterministic. That is, given the same instance of // *rand.Rand, Generate must always return the same value. // // TODO(mwhittaker): Generate should maybe take something other than a // *rand.Rand? Generate(*rand.Rand) T }
A Generator[T] generates random values of type T.
type OpFinish ¶
type OpFinish struct {
TraceID int // trace id
SpanID int // span id
Error string // returned error message
}
OpFinish represents the finish of an op.
type OpStart ¶
type OpStart struct {
TraceID int // trace id
SpanID int // span id
Name string // op name
Args []string // op arguments
}
OpStart represents the start of an op.
type Options ¶
type Options struct {
Config string // TOML config contents
}
Options configure a Simulator.
type Registrar ¶
type Registrar interface {
// RegisterFake registers a fake implementation of a component.
RegisterFake(FakeComponent)
// RegisterGenerators registers generators for a workload method, one
// generator per method argument. The number and type of the registered
// generators must match the method. For example, given the method:
//
// Foo(context.Context, int, bool) error
//
// we must register a Generator[int] and a Generator[bool]:
//
// var r Registrar = ...
// var i Generator[int] = ...
// var b Generator[bool] = ...
// r.RegisterGenerators("Foo", i, b)
//
// TODO(mwhittaker): Allow people to register a func(*rand.Rand) T instead
// of a Generator[T] for convenience.
RegisterGenerators(method string, generators ...any)
}
A Registrar is used to register fakes and generators with a simulator.
type Results ¶
type Results struct {
Err error // first non-nil error returned by an op
History []Event // a history of the error inducing run, if Err is not nil
NumSimulations int // number of simulations ran
Duration time.Duration // duration of simulations
}
Results are the results of simulating a workload.
type Return ¶
type Return struct {
TraceID int // trace id
SpanID int // span id
Component string // component returning
Replica int // component replica returning
Returns []string // return values
}
Return represents a component method call returning.
type Simulator ¶
type Simulator struct {
// contains filtered or unexported fields
}
A Simulator deterministically simulates a Service Weaver application. See the package documentation for instructions on how to use a Simulator.
type Workload ¶
type Workload interface {
// Init initializes a workload. The Init method must also register
// generators for every exported method.
Init(Registrar) error
}
A Workload defines the set of operations to run as part of a simulation. Every workload is defined as a named struct. To perform a simulation, a simulator constructs an instance of the struct, calls the struct's Init method, and then randomly calls the struct's exported methods. For example, the following is a simple workload:
type myWorkload struct {}
func (w *myWorkload) Init(r sim.Registrar) {...}
func (w *myWorkload) Foo(context.Context, int) error {...}
func (w *myWorkload) Bar(context.Context, bool, string) error {...}
func (w *myWorkload) baz(context.Context) error {...}
When this workload is simulated, its Foo and Bar methods will be called with random values generated by the generators registered in the Init method (see Registrar for details). Note that unexported methods, like baz, are ignored.
Note that every exported workload method must receive a context.Context as its first argument and must return a single error value. A simulation is aborted when a method returns a non-nil error.
TODO(mwhittaker): For now, the Init method is required. In the future, we could make it optional and use default generators for methods.
Source Files