stepper

Documentation

Index

• Variables
• func DontStop(_ interface{}, _ int) bool
• type PauseNotifier
• type RunState
  • func (i RunState) String() string
• type Stepper
  • func New() *Stepper
  • func (st *Stepper) Active() bool
  • func (st *Stepper) CheckStates() (cur, req RunState)
  • func (st *Stepper) Enter(state RunState)
  • func (st *Stepper) Grain() int
  • func (st *Stepper) Init() *Stepper
  • func (st *Stepper) Pause()
  • func (st *Stepper) PauseIfStepsComplete() (pauseNow bool)
  • func (st *Stepper) PleaseEnter(state RunState)
  • func (st *Stepper) RegisterPauseNotifier(notifier PauseNotifier, pnState interface{})
  • func (st *Stepper) RegisterStopChecker(checker StopConditionChecker, cs interface{})
  • func (st *Stepper) RequestPause(wait bool)
  • func (st *Stepper) RequestState(state RunState, wait bool) RunState
  • func (st *Stepper) RequestStop(wait bool)
  • func (st *Stepper) SetNSteps(toTake int)
  • func (st *Stepper) SetStepGrain(grain int)
  • func (st *Stepper) StartStepping(grain int, nSteps int)
  • func (st *Stepper) StepPoint(grain int) (stop bool)
  • func (st *Stepper) Stop()
  • func (st *Stepper) StopRequested() bool
  • func (st *Stepper) WaitToGo() RunState
  • func (st *Stepper) WaitUntil(state RunState) RunState
  • func (st *Stepper) WaitWithTimeout(cond *sync.Cond, secs int)
• type StopConditionChecker

Variables

var KiT_RunState = kit.Enums.AddEnum(RunStateN, kit.NotBitFlag, nil)

Functions

func DontStop

func DontStop(_ interface{}, _ int) bool

DontStop is a StopConditionChecker that does nothing, i.e., it will never trigger a pause

Types

type PauseNotifier

type PauseNotifier func(sv interface{})

A PauseNotifier is a callback that will be invoked if the program enters the Paused state. It takes an arbitrary state variable, sv, which is set by RegisterPauseNotifier.

type RunState

type RunState int

const (
	Created  RunState = iota // this is the initial state, when a stepper is first created.
	Stopped                  // execution is stopped. The Stepper is NOT waiting, so running again is basically a restart. The only way to go from Running or Stepping to Stopped is to explicitly call Stop(). Program state will not be preserved once the Stopped state is entered.
	Paused                   // execution is paused. The sim is waiting for further instructions, and can continue, or stop.
	Stepping                 // the application is running, but will pause if it hits a StepPoint that matches the current StepGrain.
	Running                  // the application is running, and will NOT pause at StepPoints. It will pause if a stop has been requested.
	RunStateN
)

func (RunState) String

func (i RunState) String() string

type Stepper

type Stepper struct {
	StateMut       sync.Mutex           `view:"-" desc:"mutex for RunState"`
	StateChange    *sync.Cond           `view:"-" desc:"state change condition variable"`
	CurState       RunState             `desc:"current run state"`
	RequestedState RunState             `desc:"requested run state"`
	StepGrain      int                  `desc:"granularity of one step. No enum type here so clients can define their own"`
	CondChecker    StopConditionChecker `view:"-" desc:"function to test for special stopping conditions"`
	CheckerState   interface{}          `view:"-" desc:"arbitrary state information for condition checker"`
	PauseNotifier  PauseNotifier        `view:"-" desc:"function to deal with any changes on client side when paused after stepping"`
	PNState        interface{}          `view:"-" desc:"arbitrary state information for pause notifier"`
	Stepping       bool                 `desc:"flag for stepping (as opposed to running"`
	StepsPerClick  int                  `desc:"number of steps to execute before returning"`
	StepsRemaining int                  `desc:"number of steps yet to execute before returning"`
	WaitTimer      chan RunState        `desc:"watchdog timer channel"`
}

The Stepper struct contains all of the state info for stepping a program, enabling step points. where the running application can be suspended with no loss of state.

func New

func New() *Stepper

New makes a new Stepper. Always call this to create a Stepper, so that initialization will be run correctly.

func (*Stepper) Active

func (st *Stepper) Active() bool

Active checks that the application is either Running or Stepping (neither Paused nor Stopped).

func (*Stepper) CheckStates

func (st *Stepper) CheckStates() (cur, req RunState)

CheckStates gets the RunStates, both current and requested.

func (*Stepper) Enter

func (st *Stepper) Enter(state RunState)

Enter unconditionally enters the specified RunState, without checking or waiting

func (*Stepper) Grain

func (st *Stepper) Grain() int

Grain gets the current StepGrain

func (*Stepper) Init

func (st *Stepper) Init() *Stepper

Init puts everything into a good state before starting a run Init is called automatically by New, and should be called before running again after calling Stop (not Pause). Init should not be called explicitly when creating a new Stepper--the preferred way to initialize is to call New.

func (*Stepper) Pause

func (st *Stepper) Pause()

Pause sets CurState to Paused. Note that the running program may not actually be paused.

func (*Stepper) PauseIfStepsComplete

func (st *Stepper) PauseIfStepsComplete() (pauseNow bool)

func (*Stepper) PleaseEnter

func (st *Stepper) PleaseEnter(state RunState)

PleaseEnter requests that the running application enter the requested state. After calling this, the caller should check to see if the application has changed CurState

func (*Stepper) RegisterPauseNotifier

func (st *Stepper) RegisterPauseNotifier(notifier PauseNotifier, pnState interface{})

RegisterPauseNotifier registers a PauseNotifier callback. A PauseNotifier is not required, but is recommended. As an alternative, the controlling code could poll Stepper state periodically.

func (*Stepper) RegisterStopChecker

func (st *Stepper) RegisterStopChecker(checker StopConditionChecker, cs interface{})

RegisterStopChecker registers a StopConditionChecker callback. This is completely optional: it's fine to not have a StopConditionChecker at all.

func (*Stepper) RequestPause

func (st *Stepper) RequestPause(wait bool)

RequestPause requests that the running program pause, and optionally waits. Really just a wrapper around RequestState.

func (*Stepper) RequestState

func (st *Stepper) RequestState(state RunState, wait bool) RunState

RequestState sets RequestedState to the passed in RunState, and will optionally wait for CurState to match the requested RunState. RequestState will wait forever if nothing responds to the request, so it should be used with caution.

func (*Stepper) RequestStop

func (st *Stepper) RequestStop(wait bool)

RequestStop requests that the running program stop, and optionally waits. Really just a wrapper around RequestState.

func (*Stepper) SetNSteps

func (st *Stepper) SetNSteps(toTake int)

SetNSteps sets the number of times to go through a StepPoint of the current granularity before actually pausing.

func (*Stepper) SetStepGrain

func (st *Stepper) SetStepGrain(grain int)

SetStepGrain sets the internal value of StepGrain to an uninterpreted int. Semantics are up to the client

func (*Stepper) StartStepping

func (st *Stepper) StartStepping(grain int, nSteps int)

StartStepping enters the Stepping run state.

func (*Stepper) StepPoint

func (st *Stepper) StepPoint(grain int) (stop bool)

StepPoint checks for possible pause or stop. If the application is: Running: keep going with no further examination of state. Stopped: return true, and the application should return (i.e., stop completely). Stepping: check to see if we should pause (if StepGrain matches, decrement StepsRemaining, stop if <= 0). Paused: wait for state change.

func (*Stepper) Stop

func (st *Stepper) Stop()

Stop sets CurState to Stopped. The running program will exit at the next StepPoint it hits.

func (*Stepper) StopRequested

func (st *Stepper) StopRequested() bool

StopRequested checks for a request to enter the Stopped state.

func (*Stepper) WaitToGo

func (st *Stepper) WaitToGo() RunState

WaitToGo waits for the application to enter Running, Stepping, or Stopped. It returns the entered state.

func (*Stepper) WaitUntil

func (st *Stepper) WaitUntil(state RunState) RunState

WaitUntil waits for RunState to become the passed-in state, or Stopped. WaitUntil may return Stopped, in which case the caller should clean up and return to its caller.

func (*Stepper) WaitWithTimeout

func (st *Stepper) WaitWithTimeout(cond *sync.Cond, secs int)

Watchdog timer for StateChange. Go Wait never times out, so this artificially injects a StateChange event to keep processes from getting stuck.

type StopConditionChecker

type StopConditionChecker func(sv interface{}, grain int) (matched bool)

A StopConditionChecker is a callback to check whether an arbitrary condition has been matched. If a StopConditionChecker returns true, the program is suspended with a RunState of Paused, and will remain so until the RunState changes to Stepping, Running, or Stopped.