use std::fmt;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Hash)]
pub enum DebuggerState {
#[default]
Idle,
Building,
Ready,
Starting,
Running,
Paused,
Exited,
Failed,
}
impl DebuggerState {
pub const ALL: [DebuggerState; 8] = [
DebuggerState::Idle,
DebuggerState::Building,
DebuggerState::Ready,
DebuggerState::Starting,
DebuggerState::Running,
DebuggerState::Paused,
DebuggerState::Exited,
DebuggerState::Failed,
];
pub const fn label(self) -> &'static str {
match self {
DebuggerState::Idle => "idle",
DebuggerState::Building => "building",
DebuggerState::Ready => "ready",
DebuggerState::Starting => "starting",
DebuggerState::Running => "running",
DebuggerState::Paused => "paused",
DebuggerState::Exited => "exited",
DebuggerState::Failed => "failed",
}
}
pub const fn is_session_active(self) -> bool {
matches!(
self,
DebuggerState::Starting | DebuggerState::Running | DebuggerState::Paused
)
}
pub const fn can_inspect(self) -> bool {
matches!(self, DebuggerState::Paused)
}
pub const fn can_step(self) -> bool {
matches!(self, DebuggerState::Paused)
}
pub const fn can_continue(self) -> bool {
matches!(self, DebuggerState::Paused)
}
pub const fn can_interrupt(self) -> bool {
matches!(self, DebuggerState::Running)
}
pub const fn can_launch(self) -> bool {
matches!(
self,
DebuggerState::Ready | DebuggerState::Exited | DebuggerState::Failed
)
}
pub const fn can_build(self) -> bool {
matches!(
self,
DebuggerState::Idle
| DebuggerState::Ready
| DebuggerState::Exited
| DebuggerState::Failed
)
}
pub const fn can_stop(self) -> bool {
self.is_session_active()
}
pub const fn can_edit_breakpoints(self) -> bool {
!matches!(self, DebuggerState::Running | DebuggerState::Starting)
}
}
impl fmt::Display for DebuggerState {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.label())
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Transition {
BuildStarted,
BuildSucceeded,
BuildFailed,
LaunchRequested,
LaunchSucceeded,
LaunchFailed,
Stopped,
Resumed,
ProgramExited,
SessionFailed,
Reset,
}
impl Transition {
pub const fn label(self) -> &'static str {
match self {
Transition::BuildStarted => "build started",
Transition::BuildSucceeded => "build succeeded",
Transition::BuildFailed => "build failed",
Transition::LaunchRequested => "launch requested",
Transition::LaunchSucceeded => "launch succeeded",
Transition::LaunchFailed => "launch failed",
Transition::Stopped => "program stopped",
Transition::Resumed => "program resumed",
Transition::ProgramExited => "program exited",
Transition::SessionFailed => "session failed",
Transition::Reset => "reset",
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
#[error("cannot apply '{transition}' while {from}", transition = transition.label())]
pub struct InvalidTransition {
pub from: DebuggerState,
pub transition: Transition,
}
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct StateMachine {
state: DebuggerState,
failure: Option<String>,
exit_code: Option<i32>,
}
impl StateMachine {
pub fn new() -> Self {
Self::default()
}
pub fn state(&self) -> DebuggerState {
self.state
}
pub fn failure(&self) -> Option<&str> {
self.failure.as_deref()
}
pub fn exit_code(&self) -> Option<i32> {
self.exit_code
}
pub fn allows(&self, transition: Transition) -> bool {
next_state(self.state, transition).is_some()
}
pub fn apply(&mut self, transition: Transition) -> Result<DebuggerState, InvalidTransition> {
let next = next_state(self.state, transition).ok_or(InvalidTransition {
from: self.state,
transition,
})?;
match transition {
Transition::BuildStarted | Transition::LaunchRequested | Transition::Reset => {
self.failure = None;
self.exit_code = None;
}
Transition::ProgramExited => self.failure = None,
_ => {}
}
self.state = next;
Ok(next)
}
pub fn fail(
&mut self,
transition: Transition,
reason: impl Into<String>,
) -> Result<DebuggerState, InvalidTransition> {
let next = self.apply(transition)?;
self.failure = Some(reason.into());
Ok(next)
}
pub fn exited(&mut self, code: Option<i32>) -> Result<DebuggerState, InvalidTransition> {
let next = self.apply(Transition::ProgramExited)?;
self.exit_code = code;
Ok(next)
}
pub fn force_failed(&mut self, reason: impl Into<String>) {
self.state = DebuggerState::Failed;
self.failure = Some(reason.into());
}
}
fn next_state(from: DebuggerState, transition: Transition) -> Option<DebuggerState> {
use DebuggerState as S;
use Transition as T;
match (from, transition) {
(state, T::BuildStarted) if state.can_build() => Some(S::Building),
(S::Building, T::BuildSucceeded) => Some(S::Ready),
(S::Building, T::BuildFailed) => Some(S::Failed),
(state, T::LaunchRequested) if state.can_launch() => Some(S::Starting),
(S::Starting, T::LaunchSucceeded) => Some(S::Running),
(S::Starting, T::LaunchFailed) => Some(S::Failed),
(S::Starting | S::Running, T::Stopped) => Some(S::Paused),
(S::Paused, T::Resumed) => Some(S::Running),
(S::Starting | S::Running | S::Paused, T::ProgramExited) => Some(S::Exited),
(state, T::SessionFailed) if state.is_session_active() => Some(S::Failed),
(S::Exited | S::Failed, T::Reset) => Some(S::Idle),
_ => None,
}
}
#[cfg(test)]
mod tests {
use super::*;
use DebuggerState as S;
use Transition as T;
fn machine_in(state: S) -> StateMachine {
StateMachine {
state,
failure: None,
exit_code: None,
}
}
#[test]
fn a_new_machine_is_idle() {
let machine = StateMachine::new();
assert_eq!(machine.state(), S::Idle);
assert!(machine.failure().is_none());
assert!(machine.exit_code().is_none());
}
#[test]
fn the_happy_path_runs_end_to_end() {
let mut machine = StateMachine::new();
assert_eq!(machine.apply(T::BuildStarted), Ok(S::Building));
assert_eq!(machine.apply(T::BuildSucceeded), Ok(S::Ready));
assert_eq!(machine.apply(T::LaunchRequested), Ok(S::Starting));
assert_eq!(machine.apply(T::LaunchSucceeded), Ok(S::Running));
assert_eq!(machine.apply(T::Stopped), Ok(S::Paused));
assert_eq!(machine.apply(T::Resumed), Ok(S::Running));
assert_eq!(machine.exited(Some(0)), Ok(S::Exited));
assert_eq!(machine.exit_code(), Some(0));
}
#[test]
fn stepping_repeatedly_alternates_between_running_and_paused() {
let mut machine = machine_in(S::Paused);
for _ in 0..5 {
assert_eq!(machine.apply(T::Resumed), Ok(S::Running));
assert_eq!(machine.apply(T::Stopped), Ok(S::Paused));
}
}
#[test]
fn a_stop_arriving_during_startup_is_accepted() {
let mut machine = machine_in(S::Starting);
assert_eq!(machine.apply(T::Stopped), Ok(S::Paused));
}
#[test]
fn stepping_a_program_that_is_not_paused_is_refused() {
for state in [S::Idle, S::Building, S::Ready, S::Running, S::Exited] {
assert!(!state.can_step(), "{state} must not allow stepping");
let mut machine = machine_in(state);
assert!(machine.apply(T::Resumed).is_err(), "{state}");
}
}
#[test]
fn an_invalid_transition_leaves_the_state_untouched() {
let mut machine = machine_in(S::Idle);
let error = machine.apply(T::Stopped).expect_err("must be refused");
assert_eq!(error.from, S::Idle);
assert_eq!(error.transition, T::Stopped);
assert_eq!(machine.state(), S::Idle, "state must not have moved");
}
#[test]
fn the_error_message_names_the_state_and_the_action() {
let error = InvalidTransition {
from: S::Running,
transition: T::Stopped,
};
let text = error.to_string();
assert!(text.contains("running"), "{text}");
assert!(text.contains("program stopped"), "{text}");
}
#[test]
fn building_is_refused_while_a_session_holds_the_executable() {
for state in [S::Starting, S::Running, S::Paused] {
assert!(!state.can_build(), "{state} must not allow a build");
let mut machine = machine_in(state);
assert!(machine.apply(T::BuildStarted).is_err(), "{state}");
}
}
#[test]
fn building_is_allowed_once_a_session_has_finished() {
for state in [S::Idle, S::Ready, S::Exited, S::Failed] {
assert!(state.can_build(), "{state} should allow a build");
let mut machine = machine_in(state);
assert_eq!(machine.apply(T::BuildStarted), Ok(S::Building));
}
}
#[test]
fn a_failed_build_records_its_reason() {
let mut machine = StateMachine::new();
machine.apply(T::BuildStarted).expect("build starts");
machine
.fail(T::BuildFailed, "nasm: 3 errors")
.expect("build fails");
assert_eq!(machine.state(), S::Failed);
assert_eq!(machine.failure(), Some("nasm: 3 errors"));
}
#[test]
fn starting_a_new_build_clears_the_previous_failure() {
let mut machine = StateMachine::new();
machine.apply(T::BuildStarted).expect("start");
machine.fail(T::BuildFailed, "old error").expect("fail");
machine.apply(T::BuildStarted).expect("rebuild");
assert!(machine.failure().is_none(), "stale failure must be cleared");
}
#[test]
fn a_failed_session_can_be_relaunched_after_a_reset() {
let mut machine = machine_in(S::Failed);
assert_eq!(machine.apply(T::Reset), Ok(S::Idle));
assert_eq!(machine.apply(T::BuildStarted), Ok(S::Building));
}
#[test]
fn a_finished_program_can_be_relaunched_without_rebuilding() {
let mut machine = machine_in(S::Exited);
assert!(machine.state().can_launch());
assert_eq!(machine.apply(T::LaunchRequested), Ok(S::Starting));
}
#[test]
fn the_program_can_exit_from_any_live_state() {
for state in [S::Starting, S::Running, S::Paused] {
let mut machine = machine_in(state);
assert_eq!(machine.exited(Some(1)), Ok(S::Exited), "{state}");
}
}
#[test]
fn a_session_failure_is_accepted_only_while_a_session_exists() {
for state in [S::Starting, S::Running, S::Paused] {
let mut machine = machine_in(state);
assert_eq!(machine.apply(T::SessionFailed), Ok(S::Failed), "{state}");
}
for state in [S::Idle, S::Ready, S::Building, S::Exited] {
let mut machine = machine_in(state);
assert!(machine.apply(T::SessionFailed).is_err(), "{state}");
}
}
#[test]
fn a_dead_debugger_can_always_be_recorded() {
for state in S::ALL {
let mut machine = machine_in(state);
machine.force_failed("gdb exited unexpectedly");
assert_eq!(machine.state(), S::Failed, "from {state}");
assert_eq!(machine.failure(), Some("gdb exited unexpectedly"));
}
}
#[test]
fn inspection_is_only_possible_while_paused() {
for state in S::ALL {
assert_eq!(
state.can_inspect(),
state == S::Paused,
"{state} reported the wrong inspectability"
);
}
}
#[test]
fn interruption_is_only_possible_while_running() {
for state in S::ALL {
assert_eq!(state.can_interrupt(), state == S::Running, "{state}");
}
}
#[test]
fn breakpoints_can_be_edited_except_while_the_program_is_moving() {
assert!(S::Idle.can_edit_breakpoints(), "before a session");
assert!(S::Paused.can_edit_breakpoints(), "while stopped");
assert!(!S::Running.can_edit_breakpoints(), "while running");
assert!(!S::Starting.can_edit_breakpoints(), "while starting");
}
#[test]
fn allows_agrees_with_apply_for_every_pair() {
let transitions = [
T::BuildStarted,
T::BuildSucceeded,
T::BuildFailed,
T::LaunchRequested,
T::LaunchSucceeded,
T::LaunchFailed,
T::Stopped,
T::Resumed,
T::ProgramExited,
T::SessionFailed,
T::Reset,
];
for state in S::ALL {
for transition in transitions {
let machine = machine_in(state);
let allowed = machine.allows(transition);
let mut probe = machine_in(state);
assert_eq!(
allowed,
probe.apply(transition).is_ok(),
"{state} + {transition:?} disagreed"
);
}
}
}
#[test]
fn every_state_is_reachable_from_idle() {
let mut reached = vec![S::Idle];
let transitions = [
T::BuildStarted,
T::BuildSucceeded,
T::BuildFailed,
T::LaunchRequested,
T::LaunchSucceeded,
T::LaunchFailed,
T::Stopped,
T::Resumed,
T::ProgramExited,
T::SessionFailed,
T::Reset,
];
let mut changed = true;
while changed {
changed = false;
for state in reached.clone() {
for transition in transitions {
if let Some(next) = next_state(state, transition) {
if !reached.contains(&next) {
reached.push(next);
changed = true;
}
}
}
}
}
for state in S::ALL {
assert!(reached.contains(&state), "{state} is unreachable");
}
}
#[test]
fn state_labels_are_unique() {
let mut labels: Vec<&str> = S::ALL.iter().map(|state| state.label()).collect();
labels.sort_unstable();
let count = labels.len();
labels.dedup();
assert_eq!(labels.len(), count);
}
}