Statemachine
A table-driven state machine with optional guards, entry and exit callbacks, and transition actions. It borrows the tables and the context pointer, performs no allocation, and has no destroy.
Usage#
Declare state and transition tables that outlive the machine, then initialize a stack StateMachine. The context pointer may be NULL.
enum { ST_IDLE, ST_RUNNING };
enum { EV_START };
const SmState states[] = {
{ ST_IDLE, NULL, NULL },
{ ST_RUNNING, NULL, NULL },
};
const SmTransition transitions[] = {
{ ST_IDLE, EV_START, ST_RUNNING, NULL, NULL },
};
StateMachine sm;
if (sm_init(&sm, states, 2, ST_IDLE, transitions, 1, NULL) == 0) {
if (sm_handle_event(&sm, EV_START) == 0) {
/* sm_current_state(&sm) == ST_RUNNING */
}
}
sm_init does not run the initial entry callback. The tables are stored by pointer and are not copied. Callbacks must not call sm_handle_event on the same machine.
Structs#
SmState#
typedef struct {
int id;
void (*entry)(void *ctx, int event);
void (*exit)(void *ctx, int event);
} SmState;
id is the state identifier. entry and exit may be NULL. When set, they are called with the context pointer and the event passed to sm_handle_event.
SmTransition#
typedef struct {
int source;
int event;
int destination;
int (*guard)(void *ctx, int event);
void (*action)(void *ctx, int event);
} SmTransition;
source and event select the row. destination is the next state. guard may be NULL, which accepts the row. Otherwise the row is accepted only when guard returns nonzero. action may be NULL. When set, it runs after the source exit and before the destination entry.
StateMachine#
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;
current_state is the active state id. Read it, or call sm_current_state. Do not write current_state or the table pointers and counts. ctx is read from the handle for each callback, so it may be replaced between events.
Functions#
sm_init#
Borrows states, transitions, and ctx. Does not allocate, and does not call the initial state's entry. initial_state must equal some row's id. Rows are found by id, not by index, and ids need not be contiguous. Ids must be unique and must not be SM_ANY_STATE. Every transition source must be a state id or SM_ANY_STATE. Every destination must be a state id. SM_ANY_STATE is not a valid destination.
Those checks finish before any write. Failure leaves sm untouched. The checks are not repeated when an event is handled. Returns 0 on success. Returns -1 if sm, states, or transitions is NULL, if either count is 0, or if a state id is duplicated, reserved, or unknown.
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#
Scans for the first row whose source is the current state or SM_ANY_STATE, whose event is event or SM_ANY_EVENT, and whose guard is NULL or returns nonzero. A guard that returns 0 skips that row and the scan continues. The first accepted row wins, so a specific row has to appear before a wildcard that would also match.
On a match, the machine calls the source exit if it is set, then the row action if it is set, then stores destination, then calls the destination entry if it is set. A self-transition runs that same sequence. Returns 0 when a row is taken. Returns 1 when none is taken, and leaves the state unchanged. Returns -1 if sm is NULL. The machine must already have been initialized. Callbacks must not call sm_handle_event on this machine.
int sm_handle_event(StateMachine *sm, int event);Macros#
SM_ANY_STATE / SM_ANY_EVENT#
SM_ANY_STATE as a source matches every current state. SM_ANY_EVENT matches every event. Both are INT_MIN. Do not use that value as a real state or event id. A destination cannot be SM_ANY_STATE.
#define SM_ANY_STATE INT_MIN
#define SM_ANY_EVENT INT_MINsm_current_state#
Reads the current state id. sm must not be NULL.
#define sm_current_state(sm) ((sm)->current_state)