File syn_fsm.h¶

FileList > src > syntropic > util > syn_fsm.h

Lightweight table-driven finite state machine. More...

#include "../common/syn_defs.h"
#include <stdbool.h>
#include <stdint.h>

Classes¶

Type	Name
struct	SYN_FSM FSM instance — transition table, state descriptors, current state.
struct	SYN_FSM_StateDesc Per-state entry/exit actions.
struct	SYN_FSM_Transition Transition descriptor — (from, event) → to, with optional guard/action.

Public Types¶

Type	Name
typedef void(*	SYN_FSM_Action Action function — called when a transition fires.
typedef int16_t	SYN_FSM_Event
typedef bool(*	SYN_FSM_Guard Guard function — return true to allow the transition.
typedef int16_t	SYN_FSM_State

Public Functions¶

Type	Name
bool	syn_fsm_dispatch (SYN_FSM * fsm, SYN_FSM_Event event) Dispatch an event.
void	syn_fsm_init (SYN_FSM * fsm, const SYN_FSM_Transition * transitions, SYN_FSM_State initial, const char * tag) Initialize the FSM.
void	syn_fsm_set_context (SYN_FSM * fsm, void * ctx) Set the user context pointer passed to guards and actions.
void	syn_fsm_set_state (SYN_FSM * fsm, SYN_FSM_State state) Force-set the FSM to a specific state.
void	syn_fsm_set_state_descs (SYN_FSM * fsm, const SYN_FSM_StateDesc * descs) Set optional state descriptors (entry/exit actions).
void	syn_fsm_set_state_names (SYN_FSM * fsm, const char const names) Set optional state name strings for debug/logging.

Public Static Functions¶

Type	Name
bool	syn_fsm_in_state (const SYN_FSM * fsm, SYN_FSM_State st) Check if the FSM is in a specific state.
SYN_FSM_State	syn_fsm_state (const SYN_FSM * fsm) Get the current state.

Macros¶

Type	Name
define	SYN_FSM_END `{[SYN\_FSM\_STATE\_NONE](syn__fsm_8h.md#define-syn_fsm_state_none), 0, 0, NULL, NULL}`
define	SYN_FSM_STATE_END `{[SYN\_FSM\_STATE\_NONE](syn__fsm_8h.md#define-syn_fsm_state_none), NULL, NULL}`
define	SYN_FSM_STATE_NONE `(([SYN\_FSM\_State](syn__fsm_8h.md#typedef-syn_fsm_state)) - 1)`

Detailed Description¶

Define states and events as enums, then describe transitions in a const table. The FSM dispatches events, calls transition actions, and optionally logs every transition via the logging module.

** **

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

void on_start(void *ctx) { motor_enable(); }
void on_stop(void *ctx)  { motor_disable(); }

static const SYN_FSM_Transition table[] = {
    { ST_IDLE,    EV_START, ST_RUNNING, NULL, on_start },
    { ST_RUNNING, EV_STOP,  ST_IDLE,    NULL, on_stop  },
    { ST_RUNNING, EV_FAULT, ST_ERROR,   NULL, NULL     },
    SYN_FSM_END
};

static SYN_FSM fsm;
syn_fsm_init(&fsm, table, ST_IDLE, "motor");
syn_fsm_dispatch(&fsm, EV_START);

Public Types Documentation¶

typedef SYN_FSM_Action¶

Action function — called when a transition fires.

typedef void(* SYN_FSM_Action) (void *ctx);

Parameters:

ctx User context.

typedef SYN_FSM_Event¶

typedef int16_t SYN_FSM_Event;

FSM event type.

typedef SYN_FSM_Guard¶

Guard function — return true to allow the transition.

typedef bool(* SYN_FSM_Guard) (void *ctx);

Parameters:

ctx User context.

Returns:

true to allow, false to block.

typedef SYN_FSM_State¶

typedef int16_t SYN_FSM_State;

FSM state type.

Public Functions Documentation¶

function syn_fsm_dispatch¶

Dispatch an event.

bool syn_fsm_dispatch (
    SYN_FSM * fsm,
    SYN_FSM_Event event
)

Scans the transition table for a matching (current_state, event) pair. If a guard exists and returns false, the transition is skipped and the next matching row is tried. On a successful match: * Exit action for the current state (if state_descs set) * Transition action * State change * Entry action for the new state (if state_descs set)

Parameters:

fsm FSM instance.
event Event to dispatch.

Returns:

true if a transition was taken, false if no match found.

function syn_fsm_init¶

Initialize the FSM.

void syn_fsm_init (
    SYN_FSM * fsm,
    const SYN_FSM_Transition * transitions,
    SYN_FSM_State initial,
    const char * tag
)

Parameters:

fsm FSM instance.
transitions Transition table (terminated by SYN_FSM_END).
initial Initial state.
tag Log tag for transition logging (e.g., "motor").

function syn_fsm_set_context¶

Set the user context pointer passed to guards and actions.

void syn_fsm_set_context (
    SYN_FSM * fsm,
    void * ctx
)

Parameters:

fsm FSM instance.
ctx User context.

function syn_fsm_set_state¶

Force-set the FSM to a specific state.

void syn_fsm_set_state (
    SYN_FSM * fsm,
    SYN_FSM_State state
)

Fires exit action for the old state and entry action for the new state (if state_descs are set). No transition action is called.

Parameters:

fsm FSM instance.
state New state.

function syn_fsm_set_state_descs¶

Set optional state descriptors (entry/exit actions).

void syn_fsm_set_state_descs (
    SYN_FSM * fsm,
    const SYN_FSM_StateDesc * descs
)

Parameters:

fsm FSM instance.
descs State descriptor table (terminated by SYN_FSM_STATE_END).

function syn_fsm_set_state_names¶

Set optional state name strings for debug/logging.

void syn_fsm_set_state_names (
    SYN_FSM * fsm,
    const char *const * names
)

Parameters:

fsm FSM instance.
names Array of state name strings, indexed by state value. Must cover all state values used in the transition table.

Public Static Functions Documentation¶

function syn_fsm_in_state¶

Check if the FSM is in a specific state.

static inline bool syn_fsm_in_state (
    const SYN_FSM * fsm,
    SYN_FSM_State st
)

Parameters:

fsm FSM instance.
st State to check.

Returns:

true if in that state.

function syn_fsm_state¶

Get the current state.

static inline SYN_FSM_State syn_fsm_state (
    const SYN_FSM * fsm
)

Parameters:

fsm FSM instance.

Returns:

Current state.

Macro Definition Documentation¶

define SYN_FSM_END¶

#define SYN_FSM_END `{ SYN_FSM_STATE_NONE , 0, 0, NULL, NULL}`

Table terminator. Place at the end of your transition array.

define SYN_FSM_STATE_END¶

#define SYN_FSM_STATE_END `{ SYN_FSM_STATE_NONE , NULL, NULL}`

State descriptor table terminator.

define SYN_FSM_STATE_NONE¶

#define SYN_FSM_STATE_NONE `(( SYN_FSM_State ) - 1)`

Sentinel value marking the end of a transition table.

The documentation for this class was generated from the following file src/syntropic/util/syn_fsm.h