Statemachine

A table-driven finite state machine with guards, entry and exit callbacks, and transition actions.

Usage

Define the states and transitions, then initialize a StateMachine handle. The machine borrows both tables and the optional context pointer; keep them alive while the machine is in use. It performs no allocation and needs no destroy call.

enum { ST_IDLE, ST_RUNNING };
enum { EV_START, EV_STOP };

const SmState states[] = {
    { ST_IDLE, NULL, NULL },
    { ST_RUNNING, NULL, NULL },
};
const SmTransition transitions[] = {
    { ST_IDLE, EV_START, ST_RUNNING, NULL, NULL },
    { ST_RUNNING, EV_STOP, ST_IDLE, NULL, NULL },
};

StateMachine sm;
if (sm_init(&sm, states, 2, ST_IDLE, transitions, 2, NULL) == 0) {
    sm_handle_event(&sm, EV_START);
    /* sm_current_state(&sm) == ST_RUNNING */
}

Add callbacks to the tables when states need entry or exit work, or when a transition needs a guard or action. Callbacks receive the context pointer and the event passed to sm_handle_event. They must not call sm_handle_event on the same machine.

Structs

SmState

Describes a single state and its optional entry/exit callbacks.

typedef struct {
    int id;
    void (*entry)(void *ctx, int event);
    void (*exit)(void *ctx, int event);
} SmState;

Members:

• id: Integer identifying this state. Typically an enum value
• entry: Optional callback invoked when the machine enters this state. Receives the user context and the event that caused the transition
• exit: Optional callback invoked when the machine leaves this state. Receives the user context and the event that caused the transition

SmTransition

One row of the transition table. Defines what happens when a specific event occurs in a specific state.

typedef struct {
    int source;
    int event;
    int destination;
    int (*guard)(void *ctx, int event);
    void (*action)(void *ctx, int event);
} SmTransition;

Members:

• source: The state this transition applies to
• event: The event that triggers this transition
• destination: The state to move to
• guard: Optional function that must return nonzero for the transition to proceed. If NULL, the transition is unconditional
• action: Optional function called during the transition, after the source state's exit callback and before the destination state's entry callback

StateMachine

The state machine instance.

typedef struct {
    const SmState *state_table;
    size_t state_table_count;

    const SmTransition *transition_table;
    size_t transition_table_count;

    int current_state;
    void *ctx;
} StateMachine;

Members:

• state_table: Pointer to an array of SmState definitions
• state_table_count: Number of entries in state_table
• transition_table: Pointer to an array of SmTransition definitions
• transition_table_count: Number of entries in transition_table
• current_state: The ID of the current state
• ctx: User-provided context pointer passed to all callbacks

Functions

sm_init

Initializes the state machine with the given state and transition tables. The initial_state must match the id of a state in the states array. States are looked up by ID, not by array index; IDs need not be contiguous. State IDs must be unique and cannot be SM_ANY_STATE. Every transition source must be a state id or SM_ANY_STATE. Every destination must name a real state; SM_ANY_STATE is not a valid destination. Validation runs before any write. A failed sm_init leaves sm untouched. The initial state's entry callback is not invoked. Returns 0 on success, -1 on error (NULL machine or table pointers, zero counts, duplicate or reserved state IDs, or unknown state IDs).

int sm_init(
    StateMachine *sm,
    const SmState *states,
    size_t state_count,
    int initial_state,
    const SmTransition *transitions,
    size_t transition_count,
    void *ctx
);

sm_handle_event

Processes an event. Scans the transition table for the first entry matching the current state and event whose guard (if any) returns nonzero. SM_ANY_STATE matches any current state. SM_ANY_EVENT matches any event. Put specific rows before wildcards; the first match wins. When a match is found, the machine runs:

1. Source state's exit callback
2. Transition's action callback
3. State change to destination
4. Destination state's entry callback

Self-transitions also run exit, action, and entry callbacks. The machine must have been initialized successfully before handling an event.

Returns 0 if a transition was taken, 1 if no matching transition was found (state unchanged), -1 if sm is NULL.

int sm_handle_event(StateMachine *sm, int event);

/* Usage: typical super-loop */
while (1) {
    int event = poll_events();
    sm_handle_event(&sm, event);
}

Macros

SM_ANY_STATE / SM_ANY_EVENT

Wildcard source and event. Destination cannot be SM_ANY_STATE. Values are INT_MIN; do not use that as a real state or event id.

#define SM_ANY_STATE INT_MIN
#define SM_ANY_EVENT INT_MIN

/* Usage: one FAULT row instead of one per state */
{ SM_ANY_STATE, EV_FAULT, ST_ERROR, NULL, log_fault },

sm_current_state

Returns the current state ID.

#define sm_current_state(sm) ((sm)->current_state)