infinite_state_machine.h File Reference

Public API for the infinite state machine. Provides functions to initialise, perform hierarchical transitions (goto and jump), query whether a state is active, and get the current top state. More...

#include "infinite_state.h"

Include dependency graph for infinite_state_machine.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	infinite_state_machine
	Represents an infinite state machine. This structure holds the current state hierarchy and allows for transitions between states. More...

Macros
#define	INFINITE_STATE_MACHINE_MAX_DEPTH   7
	Maximum depth of any infinite state machine. Defaults to 7 unless already defined before the inclusion point of this header.

Functions
void	infinite_state_machine_init (struct infinite_state_machine *machine)
	Initialises the infinite state machine. The machine is reset to its initial state. It has an initial depth of 0. All its states are cleared to NULL for safety.
void	infinite_state_machine_goto (struct infinite_state_machine *machine, struct infinite_state *state)
	Goes to a state in the infinite state machine.
void	infinite_state_machine_jump (struct infinite_state_machine *machine, struct infinite_state *state)
	Jumps to a state in the infinite state machine.
int	infinite_state_machine_in (struct infinite_state_machine *machine, struct infinite_state *state)
	Checks if a state is currently active in the infinite state machine.
struct infinite_state *	infinite_state_machine_top (const struct infinite_state_machine *machine)
	Gets the top state of the infinite state machine.

Detailed Description

Public API for the infinite state machine. Provides functions to initialise, perform hierarchical transitions (goto and jump), query whether a state is active, and get the current top state.

The machine keeps a stack (array) of active states up to INFINITE_STATE_MACHINE_MAX_DEPTH states deep. Not thread-safe; external synchronisation is required for concurrent use.

Definition in file infinite_state_machine.h.

Macro Definition Documentation

INFINITE_STATE_MACHINE_MAX_DEPTH

#define INFINITE_STATE_MACHINE_MAX_DEPTH   7

Maximum depth of any infinite state machine. Defaults to 7 unless already defined before the inclusion point of this header.

Why 7? There is method in the choice a maximum depth of 7. Pointers and integers are 32 bits wide on a 32-bit machine. Seven pointers and one integer occupy 8 words, or 32 bytes. If a single machine requires more than seven levels of nesting, better to refactor the design to reduce complexity.

Definition at line 31 of file infinite_state_machine.h.

Function Documentation

infinite_state_machine_goto()

void infinite_state_machine_goto	(	struct infinite_state_machine *	machine,
		struct infinite_state *	state
	)

Goes to a state in the infinite state machine.

Parameters

machine	The infinite state machine.
state	The state to enter.

Going to a state in the infinite state machine transitions the machine to the new state. This will push the current state onto the stack and transition to the new state. If the new state is the same as the current state, no action is taken; likewise, if the new state is a NULL pointer, no action is taken. Otherwise, all the exit actions for the current state are run, and the new state is entered by running all enter actions.

Note

O(n) time complexity applies, where n is the depth of the state machine.

Definition at line 66 of file infinite_state_machine.c.

infinite_state_machine_in()

int infinite_state_machine_in	(	struct infinite_state_machine *	machine,
		struct infinite_state *	state
	)

Checks if a state is currently active in the infinite state machine.

Parameters

machine	The infinite state machine.
state	The state to check.

Returns

1 if the state is active, 0 if it is not, or a negative error code on failure.

Definition at line 99 of file infinite_state_machine.c.

infinite_state_machine_init()

void infinite_state_machine_init

(

struct infinite_state_machine *

machine

)

Initialises the infinite state machine. The machine is reset to its initial state. It has an initial depth of 0. All its states are cleared to NULL for safety.

Parameters

machine

The infinite state machine to initialise.

Definition at line 60 of file infinite_state_machine.c.

infinite_state_machine_jump()

void infinite_state_machine_jump	(	struct infinite_state_machine *	machine,
		struct infinite_state *	state
	)

Jumps to a state in the infinite state machine.

Parameters

machine	The infinite state machine.
state	The state to jump to.

Jumping to a state in the infinite state machine resets the machine to its initial state and then transitions to the specified state. This is useful for resetting the machine to a known state without going through the normal entry and exit actions.

Note

O(n) time complexity applies, where n is the depth of the state machine.

Definition at line 93 of file infinite_state_machine.c.

infinite_state_machine_top()

struct infinite_state * infinite_state_machine_top

(

const struct infinite_state_machine *

machine

)

Gets the top state of the infinite state machine.

Parameters

machine

The infinite state machine.

Returns

The top state, or NULL if the machine is empty.

Definition at line 157 of file infinite_state_machine.c.