simgo

README

SimGo

SimGo is a discrete event simulation framework for Go. It is similar to SimPy and aims to be easy to set up and use.

Processes are defined as simple functions receiving simgo.Process as their first argument. Each process is executed in a separate goroutine, but it is guaranteed that only one process is executed at a time. For examples, look into the examples folder. A short example simulating two clocks ticking in different time intervals looks like this:

package main

import (
    "fmt"

    "github.com/fschuetz04/simgo"
)

func clock(proc simgo.Process, name string, delay float64) {
    for {
        fmt.Println(name, proc.Now())
        proc.Wait(proc.Timeout(delay))
    }
}

func main() {
    sim := simgo.NewSimulation()

    sim.ProcessReflect(clock, "slow", 2)
    sim.ProcessReflect(clock, "fast", 1)

    sim.RunUntil(5)
}

When run, the following output is generated:

slow 0
fast 0
fast 1
slow 2
fast 2
fast 3
slow 4
fast 4

You can find more examples in the examples directory.

Copyright and License

Copyright © 2024 Felix Schütz.

Licensed under the MIT License. See the LICENSE file for details.

Documentation

Index

• type Awaitable
• type Event
  • func (ev *Event) Abort() bool
  • func (ev *Event) Aborted() bool
  • func (ev *Event) AddAbortHandler(handler Handler)
  • func (ev *Event) AddHandler(handler Handler)
  • func (ev *Event) Pending() bool
  • func (ev *Event) Processed() bool
  • func (ev *Event) Trigger() bool
  • func (ev *Event) TriggerDelayed(delay float64) bool
  • func (ev *Event) Triggered() bool
• type GetEvent
• type Handler
• type Process
  • func (proc Process) Aborted() bool
  • func (proc Process) AddAbortHandler(handler Handler)
  • func (proc Process) AddHandler(handler Handler)
  • func (proc Process) Pending() bool
  • func (proc Process) Processed() bool
  • func (proc Process) Triggered() bool
  • func (proc Process) Wait(ev Awaitable)
• type PutEvent
• type Simulation
  • func NewSimulation() *Simulation
  • func (sim *Simulation) AllOf(evs ...Awaitable) *Event
  • func (sim *Simulation) AnyOf(evs ...Awaitable) *Event
  • func (sim *Simulation) Event() *Event
  • func (sim *Simulation) Now() float64
  • func (sim *Simulation) Process(runner func(proc Process)) Process
  • func (sim *Simulation) ProcessReflect(runner interface{}, args ...interface{}) Process
  • func (sim *Simulation) Run()
  • func (sim *Simulation) RunUntil(target float64)
  • func (sim *Simulation) Shutdown()
  • func (sim *Simulation) Step() bool
  • func (sim *Simulation) Timeout(delay float64) *Event
• type Store
  • func NewStore[T any](sim *Simulation) *Store[T]
  • func NewStoreWithCapacity[T any](sim *Simulation, capacity int) *Store[T]
  • func (store *Store[T]) Available() int
  • func (store *Store[T]) Capacity() int
  • func (store *Store[T]) Get() *GetEvent[T]
  • func (store *Store[T]) Put(item T) *PutEvent[T]

Types

type Awaitable

type Awaitable interface {
	// Processed must return true when the event is processed.
	Processed() bool

	// Aborted must return true when the event is aborted.
	Aborted() bool

	// AddHandler must add the given normal handler. When the event is
	// processed, the normal handler must be called.
	AddHandler(handler Handler)

	// AddAbortHandler must add the given abort handler. When the event is
	// aborted, the abort handler must be called.
	AddAbortHandler(handler Handler)
}

Awaitable represents any awaitable thing like an event.

type Event

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

Event is an event in a discrete-event simulation. The event does not contain information about whether it is scheduled to be processed.

To create a new event, use (*Simulation).Timeout, (*Simulation).Event, (*Simulation).AnyOf, or (*Simulation).AllOf:

ev1 := sim.Event()
ev2 := sim.Timeout(5)
ev3 := sim.AnyOf(ev1, ev2)
ev4 := sim.AllOf(ev1, ev2)

func (*Event) Abort

func (ev *Event) Abort() bool

Abort aborts the event and calls all abort handlers of the event.

If the event is not pending, it will not be aborted.

Returns true if the event has been aborted or false otherwise.

TODO: Abort immediately calls it handlers, which leads to a growing call stack. Instead, the processing could be scheduled similar to that of (*Event).Trigger.

func (*Event) Aborted

func (ev *Event) Aborted() bool

Aborted returns whether the event has been aborted. All abort handlers of an aborted event are currently being called or have been called.

func (*Event) AddAbortHandler

func (ev *Event) AddAbortHandler(handler Handler)

AddAbortHandler adds the given handler as an abort handler to the event. The handler will be called when the event is aborted.

If the event is already processed or aborted, the handler is not stored, since it will never be called.

func (*Event) AddHandler

func (ev *Event) AddHandler(handler Handler)

AddHandler adds the given handler as a normal handler to the event. The handler will be called when the event is processed.

If the event is already processed or aborted, the handler is not stored, since it will never be called.

func (*Event) Pending

func (ev *Event) Pending() bool

Pending returns whether the event is pending. A pending event has not yet been triggered or processed. This is the initial state of a new event.

func (*Event) Processed

func (ev *Event) Processed() bool

Processed returns whether the event has been processed. All normal handlers of a processed event are currently being called or have been called.

func (*Event) Trigger

func (ev *Event) Trigger() bool

Trigger schedules the event to be processed immediately. This will call all normal handlers of the event.

If the event is not pending, it will not be scheduled.

func (*Event) TriggerDelayed

func (ev *Event) TriggerDelayed(delay float64) bool

TriggerDelayed schedules the event to be processed after the given delay. This will call all normal handlers of the event.

If the event is not pending, it will not be scheduled.

Returns true if the event has been scheduled or false otherwise. Panics if the given delay is negative.

Note that an event can be triggered delayed multiple times, or triggered immediately after it is already triggered delayed. The event will be processed once at the earliest scheduled time.

func (*Event) Triggered

func (ev *Event) Triggered() bool

Triggered returns whether the event has been triggered. A triggered event will be processed at the current simulation time if it has not been processed already.

type GetEvent

type GetEvent[T any] struct {
	// Event is the underlying event.
	*Event

	// Item holds the item retrieved from the store after the underlying event is
	// triggered.
	Item T
}

GetEvent is the event returned from (*Store).Get.

type Handler

type Handler func(ev *Event)

Handler is either a normal handler or an abort handler, which is called when an event is processed / aborted. The handler gets a pointer to the relevant pointer, so one function can be used to handle multiple events and distinguish between them.

type Process

type Process struct {
	// Simulation is used to generate timeouts and other events, and start new
	// processes.
	*Simulation
	// contains filtered or unexported fields
}

Process is a process in a discrete-event simulation.

A process can wait for events and other processes, create new events and start new processes.

To start a process, use (*Simulation).Process or (*Simulation).ProcessReflect:

func myProcess (proc simgo.Process) {
    fmt.Println("Start")
    proc.Wait(proc.Timeout(5))
    fmt.Println("End")
}
sim.Process(myProcess)

Process encapsulates *Simulation, so all its methods can be used.

func (Process) Aborted

func (proc Process) Aborted() bool

Aborted returns whether the underlying event is aborted.

func (Process) AddAbortHandler

func (proc Process) AddAbortHandler(handler Handler)

AddAbortHandler adds the given abort handler to the underlying event.

func (Process) AddHandler

func (proc Process) AddHandler(handler Handler)

AddHandler adds the given handler to the underlying event.

func (Process) Pending

func (proc Process) Pending() bool

Pending returns whether the underlying event is pending.

func (Process) Processed

func (proc Process) Processed() bool

Processed returns whether the underlying event is processed.

func (Process) Triggered

func (proc Process) Triggered() bool

Triggered retrusn whether the underlying event is triggered.

func (Process) Wait

func (proc Process) Wait(ev Awaitable)

Wait yields from the process to the simulation and waits until the given awaitable is processed.

If the awaitable is already processed, the process is not paused. If the awaitable is aborted, the process is aborted too.

type PutEvent

type PutEvent[T any] struct {
	// Event is the underlying event.
	*Event
	// contains filtered or unexported fields
}

PutEvent is the returned from (*Store).Put.

type Simulation

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

Simulation runs a discrete-event simulation. To create a new simulation, use NewSimulation().

func NewSimulation

func NewSimulation() *Simulation

NewSimulation creates a new simulation.

func (*Simulation) AllOf

func (sim *Simulation) AllOf(evs ...Awaitable) *Event

AllOf creates and returns a pending event which is triggered when all of the given events are processed. TODO: Handle aborted events.

func (*Simulation) AnyOf

func (sim *Simulation) AnyOf(evs ...Awaitable) *Event

AnyOf creates and returns a pending event which is triggered when any of the given events is processed. TODO: Handle aborted events.

func (*Simulation) Event

func (sim *Simulation) Event() *Event

Event creates and returns a pending event.

func (*Simulation) Now

func (sim *Simulation) Now() float64

Now returns the current simulation time.

func (*Simulation) Process

func (sim *Simulation) Process(runner func(proc Process)) Process

Process starts a new process with the given runner.

Creates and triggers an event. As soon as this event is processed, the runner is executed. Whenever the runner waits for a pending event, it is paused until the event is processed.

It is ensured that only one process is executed at the same time.

Returns the process. This can be used to wait for the process to finish. As soon as the process finishes, the underlying event is triggered.

func (*Simulation) ProcessReflect

func (sim *Simulation) ProcessReflect(runner interface{}, args ...interface{}) Process

ProcessReflect starts a new process with the given runner and the given additional argument. This uses reflection.

See (*Simulation).Process for further documentation.

func (*Simulation) Run

func (sim *Simulation) Run()

Run runs the simulation until the event queue is empty.

func (*Simulation) RunUntil

func (sim *Simulation) RunUntil(target float64)

RunUntil runs the simulation until the event queue is empty or the next event in the event queue is scheduled at or after the given target time. Sets the current simulation time to the target time at the end. Panics if the given target time is smaller than the current simulation time.

func (*Simulation) Shutdown

func (sim *Simulation) Shutdown()

Shutdown shuts down all process goroutines of this simulation.

func (*Simulation) Step

func (sim *Simulation) Step() bool

Step sets the current simulation time to the scheduled time of the next event in the event queue and processes the next event. Returns false if the event queue was empty and no event was processed, true otherwise.

func (*Simulation) Timeout

func (sim *Simulation) Timeout(delay float64) *Event

Timeout creates and returns a pending event which is processed after the given delay. Panics if the given delay is negative.

type Store

type Store[T any] struct {
	// contains filtered or unexported fields
}

Store is a resource for storing objects. The objects are put and retrieved from the store in a first-in first-out order.

func NewStore

func NewStore[T any](sim *Simulation) *Store[T]

NewStore creates a store for the given simulation with an unlimited capacity.

func NewStoreWithCapacity

func NewStoreWithCapacity[T any](sim *Simulation, capacity int) *Store[T]

NewStoreWithCapacity crates a store for the given simulation with the given capacity.

func (*Store[T]) Available

func (store *Store[T]) Available() int

Available returns the number of items currently in the store.

func (*Store[T]) Capacity

func (store *Store[T]) Capacity() int

Capacity returns the capacity of the store.

func (*Store[T]) Get

func (store *Store[T]) Get() *GetEvent[T]

Get returns an event that is triggered when an item is retrieved from the store, which may be immediately.

func (*Store[T]) Put

func (store *Store[T]) Put(item T) *PutEvent[T]

Put returns an event that is triggered when the given item is returned to the store, which may be immediately.