State machine functions. More...

#include "machine.h"

Include dependency graph for machine.c:

Data Structures
struct	fr_machine_defer_t

struct	fr_machine_hook_t

struct	fr_machine_s
	Hooks. More...

struct	fr_machine_state_inst_t

Macros
#define	POST (1)

#define	PRE (0)

Functions
static int	_machine_free (fr_machine_t *m)
	Free a state machine. More...

static int	_machine_hook_free (fr_machine_hook_t *hook)

static void	call_hook (fr_machine_t m, fr_dlist_head_t head, int state1, int state2)
	Call the hook with the current state machine, and the hooks context. More...

fr_machine_t *	fr_machine_alloc (TALLOC_CTX ctx, fr_machine_def_t const def, void *uctx)
	Instantiate a state machine. More...

int	fr_machine_current (fr_machine_t *m)
	Get the current state. More...

void *	fr_machine_hook (fr_machine_t m, TALLOC_CTX ctx, int state_to_hook, fr_machine_hook_type_t type, fr_machine_hook_sense_t sense, bool oneshot, fr_machine_hook_func_t func, void *uctx)
	Add a hook to a state, with an optional talloc_ctx. More...

void	fr_machine_pause (fr_machine_t *m)
	Pause any transitions. More...

int	fr_machine_process (fr_machine_t *m)
	Process the state machine. More...

void	fr_machine_resume (fr_machine_t *m)
	Resume transitions. More...

int	fr_machine_signal (fr_machine_t *m, int signal)
	Send an async signal to the state machine. More...

char const *	fr_machine_state_name (fr_machine_t *m, int state)
	Get the name of a particular state. More...

int	fr_machine_transition (fr_machine_t *m, int state)
	Transition to a new state. More...

static int	state_post (fr_machine_t *m, int state)
	Post the new state to the state machine. More...

static void	state_transition (fr_machine_t m, int state, void in_handler)
	Transition from one state to another. More...

Detailed Description

State machine functions.

Copyright: 2021 Network RADIUS SAS (legal.nosp@m.@net.nosp@m.workr.nosp@m.adiu.nosp@m.s.com)

Definition in file machine.c.

Data Structure Documentation

◆ fr_machine_defer_t

struct fr_machine_defer_t

Definition at line 35 of file machine.c.

Collaboration diagram for fr_machine_defer_t:

Data Fields
fr_dlist_t	dlist	linked list of deferred signals
int	state	state transition to defer

◆ fr_machine_hook_t

struct fr_machine_hook_t

Definition at line 56 of file machine.c.

Collaboration diagram for fr_machine_hook_t:

Data Fields
fr_dlist_t	dlist	linked list of hooks
fr_machine_hook_func_t	func	function to call for the hook
fr_dlist_head_t *	head	where the hook is stored
bool	oneshot	is this a one-shot callback?
void *	uctx	to pass back to the function

◆ fr_machine_s

struct fr_machine_s

Hooks.

Definition at line 43 of file machine.c.

Collaboration diagram for fr_machine_s:

Data Fields
fr_machine_state_inst_t *	current	current state we are in
bool	dead	we were asked to exit, but aren't yet done cleaning up
fr_machine_def_t const *	def	static definition of states, names, callbacks for the state machine
fr_dlist_head_t	deferred	list of deferred entries
void const *	in_handler	which handler we are in
int	paused	are transitions paused?
fr_machine_state_inst_t	state[]	all of the state transitions
void *	uctx	to pass to the various handlers

◆ fr_machine_state_inst_t

struct fr_machine_state_inst_t

Definition at line 27 of file machine.c.

Collaboration diagram for fr_machine_state_inst_t:

Data Fields
fr_machine_state_t const *	def	static definition of names, callbacks for this particular state
fr_dlist_head_t	enter[2]	pre/post enter hooks
fr_dlist_head_t	exit[2]	pre/post exit hooks
fr_dlist_head_t	process[2]	pre/post process hooks
fr_dlist_head_t	signal[2]	pre/post signal hooks

Macro Definition Documentation

◆ POST

#define POST (1)

Definition at line 67 of file machine.c.

◆ PRE

#define PRE (0)

Definition at line 65 of file machine.c.

Function Documentation

◆ _machine_free()

static int _machine_free ( fr_machine_t * m )

static

Free a state machine.

When a state machine is freed, it will first transition to the "free" state. That state is presumed to do all appropriate cleanups.

Definition at line 137 of file machine.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ _machine_hook_free()

static int _machine_hook_free ( fr_machine_hook_t * hook )

static

Definition at line 501 of file machine.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ call_hook()

static void call_hook	(	fr_machine_t *	m,
		fr_dlist_head_t *	head,
		int	state1,
		int	state2
	)

inlinestatic

Call the hook with the current state machine, and the hooks context.

Note that in most cases, the hook will have saved it's own state machine in uctx, and will not need the current state machine.

Definition at line 74 of file machine.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_machine_alloc()

fr_machine_t* fr_machine_alloc	(	TALLOC_CTX *	ctx,
		fr_machine_def_t const *	def,
		void *	uctx
	)

Instantiate a state machine.

Parameters

ctx	the talloc ctx
def	the definition of the state machine
uctx	the context passed to the callbacks

Returns

NULL on error
!NULL state machine which can be used.

Definition at line 175 of file machine.c.

Here is the call graph for this function:

◆ fr_machine_current()

int fr_machine_current ( fr_machine_t * m )

Get the current state.

Parameters

m	The state machine

Returns: The current state, or 0 for "not in any state"

Definition at line 467 of file machine.c.

Here is the call graph for this function:

◆ fr_machine_hook()

void* fr_machine_hook	(	fr_machine_t *	m,
		TALLOC_CTX *	ctx,
		int	state_to_hook,
		fr_machine_hook_type_t	type,
		fr_machine_hook_sense_t	sense,
		bool	oneshot,
		fr_machine_hook_func_t	func,
		void *	uctx
	)

Add a hook to a state, with an optional talloc_ctx.

The hook is removed when the talloc ctx is freed.

You can also remove the hook by freeing the returned pointer.

Definition at line 515 of file machine.c.

Here is the call graph for this function:

◆ fr_machine_pause()

void fr_machine_pause ( fr_machine_t * m )

Pause any transitions.

Definition at line 565 of file machine.c.

Here is the call graph for this function:

◆ fr_machine_process()

int fr_machine_process ( fr_machine_t * m )

Process the state machine.

Parameters

m	The state machine

Returns

0 for "no transition has occurred"
>0 for "we are in a new state". -<0 for "error, you should tear down the state machine".

This function should be called by the user of the machine.

In general, the caller doesn't really care about the return code of this function. The only real utility is >=0 for "continue calling the state machine as necessary", or <0 for "shut down the state machine".

Definition at line 304 of file machine.c.

Here is the call graph for this function:

◆ fr_machine_resume()

void fr_machine_resume ( fr_machine_t * m )

Resume transitions.

Definition at line 575 of file machine.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ fr_machine_signal()

int fr_machine_signal	(	fr_machine_t *	m,
		int	signal
	)

Send an async signal to the state machine.

Parameters

m	The state machine
signal	the signal to send to the state machne

Returns

0 for "no transition has occurred"
>0 for "we are in a new state". -<0 for "error, you should tear down the state machine".

The signal function can return a new state. i.e. some signals get ignored, and others cause transitions.

Definition at line 619 of file machine.c.

Here is the call graph for this function:

◆ fr_machine_state_name()

char const* fr_machine_state_name	(	fr_machine_t *	m,
		int	state
	)

Get the name of a particular state.

Parameters

m	The state machine
state	The state to query

Returns: the name

Definition at line 483 of file machine.c.

Here is the call graph for this function:

◆ fr_machine_transition()

int fr_machine_transition	(	fr_machine_t *	m,
		int	state
	)

Transition to a new state.

Parameters

m	The state machine
state	the state to transition to

Returns

<0 for error
0 for the transition was made (or deferred)

The transition MAY be deferred. Note that only one transition at a time can be deferred.

This function MUST NOT be called from any "hook", or from any enter/exit/process function. It should ONLY be called from the "parent" of the state machine, when it decides that the state machine needs to change.

i.e. from a timer, or an IO callback

Definition at line 394 of file machine.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ state_post()

static int state_post	(	fr_machine_t *	m,
		int	state
	)

static

Post the new state to the state machine.

Definition at line 257 of file machine.c.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ state_transition()

static void state_transition	(	fr_machine_t *	m,
		int	state,
		void *	in_handler
	)

static

Transition from one state to another.

Including calling pre/post hooks.

None of the functions called from here are allowed to perform a state transition.

Definition at line 93 of file machine.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Data Structures

Macros

Functions

Detailed Description

Data Structure Documentation

◆ fr_machine_defer_t

◆ fr_machine_hook_t

◆ fr_machine_s

◆ fr_machine_state_inst_t

Macro Definition Documentation

◆ POST

◆ PRE

Function Documentation

◆ _machine_free()

◆ _machine_hook_free()

◆ call_hook()

◆ fr_machine_alloc()

◆ fr_machine_current()

◆ fr_machine_hook()

◆ fr_machine_pause()

◆ fr_machine_process()

◆ fr_machine_resume()

◆ fr_machine_signal()

◆ fr_machine_state_name()

◆ fr_machine_transition()

◆ state_post()

◆ state_transition()