testsim

Documentation

Overview

Package testsim implements a deterministic execution runtime driven by simulated logical time.

The runtime controls execution by means of processes. The process represent a context of execution within the simulation runtime. Each process can be either active or inactive. Active processes are allowed to execute while inactive processes are blocked waiting for certain conditions to hold before they can continue execution.

Processes can synchronize and exchange values through channels provided by the runtime. The channel represents an object which processes can send to or receive values from. An attempt to perform the send or receive operation on a channel deactivates the process and blocks waiting until another process performs the complementary operation on the channel. Once that happens, both processes become active and can continue execution, whereas the receiving process obtains the value supplied by the sending process. In case multiple processes get blocked trying to send/receive on the same channel, they complete the operations in FIFO order.

Processes can also get blocked by waiting for a specified duration of simulated time to expire. Such process gets activated back once the simulation reaches that point of simulated time.

The simulation proceeds in steps. Each step represents an instance of simulated time and lasts as long as there is an active process to execute. Execution within the same step is considered happening instantaneously in terms of simulated time. Once there is no more active process, the simulation can proceed to the next step that corresponds to the next action scheduled in the simulated time.

Index

• func RandDuration(r *rand.Rand, min, max time.Duration) time.Duration
• type Chan
  • func NewChan() *Chan
• type Process
  • func (p *Process) Delay(d time.Duration) (ok bool)
  • func (p *Process) Exit()
  • func (p *Process) Fork() *Process
  • func (p *Process) Kill()
  • func (p *Process) Recv(c *Chan) (v any, ok bool)
  • func (p *Process) Send(c *Chan, v any) (ok bool)
  • func (p *Process) Yield() (ok bool)
• type Runtime
  • func NewRuntime(rnd *rand.Rand) *Runtime
  • func (r *Runtime) Run()
  • func (r *Runtime) RunFor(d time.Duration)
  • func (r *Runtime) Spawn() *Process
  • func (r *Runtime) Step() (ok bool)
  • func (r *Runtime) Stop()

Functions

func RandDuration

func RandDuration(r *rand.Rand, min, max time.Duration) time.Duration

RandDuration returns a uniformly distributed pseudo-random duration in the range of [min, max].

Types

type Chan

type Chan struct {
	// contains filtered or unexported fields
}

Chan represents a channel for synchronization and communication between processes in the simulated runtime.

func NewChan

func NewChan() *Chan

NewChan creates a new channel in the simulation runtime.

type Process

type Process struct {
	*Runtime
	// contains filtered or unexported fields
}

Process represents a context of execution in the simulation.

func (*Process) Delay

func (p *Process) Delay(d time.Duration) (ok bool)

Delay suspends the execution and resumes it after d amount of simulated time. It returns false in case the process was killed while waiting.

func (*Process) Exit

func (p *Process) Exit()

Exit terminates the process normally.

func (*Process) Fork

func (p *Process) Fork() *Process

Fork creates a new active process.

func (*Process) Kill

func (p *Process) Kill()

Kill immediately resumes and terminates the process.

func (*Process) Recv

func (p *Process) Recv(c *Chan) (v any, ok bool)

Recv attempts to receive a value from the channel. It either resumes the process waiting in Send operation on the channel, or blocks until another process attempts to send to the channel. It returns the received value and true once the operation is complete. It returns nil and false if the process was killed while waiting.

func (*Process) Send

func (p *Process) Send(c *Chan, v any) (ok bool)

Send attempts to send the value v to the channel c. It either resumes the process waiting in Recv operation on the channel, or blocks until another process attempts to receive from the channel. It returns false in case the process was killed while waiting.

func (*Process) Yield

func (p *Process) Yield() (ok bool)

Yield suspends and resumes the execution in a separate simulation step. It returns false in case the process was killed while waiting.

type Runtime

type Runtime struct {
	*rand.Rand
	// contains filtered or unexported fields
}

Runtime provides a mechanism to run a simulation with logical time.

func NewRuntime

func NewRuntime(rnd *rand.Rand) *Runtime

NewRuntime creates a new simulation runtime given a source of pseudo-random numbers.

func (*Runtime) Run

func (r *Runtime) Run()

Run executes the simulation until there is no more active process or scheduled action.

func (*Runtime) RunFor

func (r *Runtime) RunFor(d time.Duration)

RunFor works the same as Run, but stops execution after expiration of the duration d of simulated time.

func (*Runtime) Spawn

func (r *Runtime) Spawn() *Process

Spawn creates a new active process.

func (*Runtime) Step

func (r *Runtime) Step() (ok bool)

Step executes the next scheduled action in the simulation and waits until there is no more active process. It returns true if there was an action to execute.

func (*Runtime) Stop

func (r *Runtime) Stop()

Stop kills all processes and terminates the simulation.