# States

### Definitions
- Model
  - Private - internal state of the processor, always up to date.
    - time: Duration, 
    - state: **Running | Paused | Halted | Shutdown | Breakpoint**
  - Shared - shared across threads. updated periodically
    - time: Duration
    - cycles: Integer


## Running
the running state is the main loop of the emulator. 

### Responsibilities:
- run fetch-decode-execute cycle
- handle interrupts
- go to paused state if requested by UI.
- go to the halted state if it hits that instruction
- keep the UI updated occasionally, but prioritise extremely high throughput

### Transitions:
- to `Paused`
  - when the `pause` signal is received
- to `Halted`
  - when hitting the `Hlt` instruction.
- to `Shutdown`
    - when the `shutdown` signal is received

***DEBUG IMPLEMENTATION ONLY***
- to `Breakpoint`
  - when hitting a breakpoint 

## Paused
the paused state is started and ended by the UI thread.

### Responsibilities:
- update the UI when requested
- reset when requested by the UI
- save the running-time and executed instructions since the last pause state.
  - add `private.time` to `shared.time`
  - reset `private.time, shared.time, shared.cycles` on state exit

### Transitions
- to `Halted`
  - when the `run` signal is received and the previous state was `Halted`
- to `Running`
  - when the `run` signal is received
- to `Shutdown`
    - when the `shutdown` signal is received

## Halted
the state reached when the emulator has hit a `Hlt` instruction and is waiting to continue

### Responsibilities:
- update the UI when requested
- unpause when an interrupt is received
- keep track of the time spent in the running state across multiple hlt/interrupt cycles
  - add `private.time` to `shared.time`
  - reset `private.time` on state exit
  - preserve `shared` on state exit

### Transitions
- to `Running` 
  - when the `interrupt` signal is received
- to `Paused`
  - when the `pause` signal is received
- to `Shutdown`
  - when the `shutdown` signal is received

## Shutdown
the shutdown state is a terminal state. the emulator cleans up its memory and exits.

## Breakpoint
debug state used only in the debugger implementation of the emulator

### Transitions
- to `Running`
  - when the `run` signal is received