infinite_state_machine.c

Go to the documentation of this file.

/*
 * SPDX-FileCopyrightText: 2025, Roy Ratcliffe, Northumberland, United Kingdom
 * SPDX-License-Identifier: MIT
 */
#include "infinite_state_machine.h"
 
#include <string.h>
#include <errno.h>
 
static int infinite_state_machine_enter(struct infinite_state_machine *machine, struct infinite_state *state);
 
static int infinite_state_machine_exit(struct infinite_state_machine *machine);
 
static int infinite_state_machine_push(struct infinite_state_machine *machine, struct infinite_state *state);
 
static struct infinite_state *infinite_state_machine_pop(struct infinite_state_machine *machine);
 
void infinite_state_machine_init(struct infinite_state_machine *machine)
{
    machine->depth = 0;
    (void)memset(machine->states, 0, sizeof(machine->states));
}
 
void infinite_state_machine_goto(struct infinite_state_machine *machine, struct infinite_state *state)
{
    /*
     * If the target state is the same as the current top state, do nothing.
     * This is a quick optimisation to avoid unnecessary state topology computation.
     */
    if (state == infinite_state_machine_top(machine))
    {
        return;
    }
    struct infinite_state_machine jump;
    infinite_state_machine_jump(&jump, state);
    int depth = 0;
    while (depth < machine->depth && depth < jump.depth && machine->states[depth] == jump.states[depth])
    {
        depth++;
    }
    while (machine->depth > depth)
    {
        infinite_state_machine_exit(machine);
    }
    while (jump.depth > depth)
    {
        infinite_state_machine_enter(machine, jump.states[depth++]);
    }
}
 
void infinite_state_machine_jump(struct infinite_state_machine *machine, struct infinite_state *state)
{
    infinite_state_machine_init(machine);
    machine->depth = infinite_state_topology(state, INFINITE_STATE_MACHINE_MAX_DEPTH, machine->states) - machine->states;
}
 
int infinite_state_machine_in(struct infinite_state_machine *machine, struct infinite_state *state)
{
    if (machine == NULL || state == NULL)
    {
        return -EINVAL;
    }
    for (int depth = 0; depth < machine->depth; depth++)
    {
        if (machine->states[depth] == state)
        {
            return 1;
        }
    }
    return 0;
}
 
int infinite_state_machine_enter(struct infinite_state_machine *machine, struct infinite_state *state)
{
    int err;
    if ((err = infinite_state_machine_push(machine, state)) < 0)
    {
        return err;
    }
    /*
     * Run the enter actions *after* the machine stack adds the state.
     * Technically, nothing prevents the action from applying yet another
     * state transition, although higher-level code must be designed for
     * reentrancy.
     */
    if (state->enter != NULL)
    {
        state->enter(state, machine);
    }
    return 0;
}
 
int infinite_state_machine_exit(struct infinite_state_machine *machine)
{
    struct infinite_state *state = infinite_state_machine_pop(machine);
    if (state == NULL)
    {
        return -EINVAL;
    }
    /*
     * Run the exit actions *after* the machine stack removes the state. This is
     * by design, as it allows the exit actions to mutate the state of the
     * machine after the state is removed. It might seem counterintuitive, but
     * it allows for more flexible state management. The argument to the exit
     * function is the state being exited, and the machine itself, allowing for
     * context-aware exit actions.
     */
    if (state->exit != NULL)
    {
        state->exit(state, machine);
    }
    return 0;
}
 
struct infinite_state *infinite_state_machine_top(const struct infinite_state_machine *machine)
{
    return machine->depth == 0 ? NULL : machine->states[machine->depth - 1];
}
 
int infinite_state_machine_push(struct infinite_state_machine *machine, struct infinite_state *state)
{
    if (machine->depth == INFINITE_STATE_MACHINE_MAX_DEPTH)
    {
        return -ENOMEM;
    }
    machine->states[machine->depth++] = state;
    return 0;
}
 
struct infinite_state *infinite_state_machine_pop(struct infinite_state_machine *machine)
{
    if (machine->depth == 0)
    {
        return NULL;
    }
    struct infinite_state *pop = machine->states[--machine->depth];
    /*
     * Clear the popped state from the stack. This is not strictly necessary,
     * but it can help catch use-after-free bugs.
     */
    machine->states[machine->depth] = NULL;
    return pop;
}