simplehsm/simplehsm.h File Reference

Go to the source code of this file.

Data Structures
struct	simplehsm_t
Defines
#define	FALSE   0
#define	TRUE   1
#define	stnone   NULL
#define	stdeephist   NULL
#define	MAX_HISTORY   10
Typedefs
typedef int	BOOL
typedef void *	stnext
typedef stnext(*	stfunc )(int, void *)
Enumerations
enum	simplehsm_signals_t {   SIG_NULL = 0, SIG_INIT = 1, SIG_ENTRY = 2, SIG_DEEPHIST = 3,   SIG_EXIT = 4, SIG_USER = 5 }
Functions
void	simplehsm_initialize (simplehsm_t *hsm, stfunc top_state)
void	simplehsm_transition_state_ex (simplehsm_t *hsm, stfunc new_state, BOOL to_deep_hist)
void	simplehsm_transition_state (simplehsm_t *hsm, stfunc new_state)
void	simplehsm_init_transition_state (simplehsm_t *hsm, stfunc new_state)
void	simplehsm_signal_current_state (simplehsm_t *hsm, int signal, void *param)
BOOL	simplehsm_is_in_state (simplehsm_t *hsm, stfunc state)
void	simplehsm_record_deephist (simplehsm_t *hsm, stfunc history_parent, stfunc history_state)
stfunc	simplehsm_retrieve_deephist (simplehsm_t *hsm, stfunc history_parent)

---

Detailed Description

Author:

Daniel Newton <djpnewton@gmail.com>

Version:

1.0

LICENSE

Copyright (c) 2009 Daniel Newton

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

DESCRIPTION

The simplehsm C implementation header

---

Define Documentation

#define MAX_HISTORY   10

The maximum number of deep history psuedostates supported in a single simplehsm instance

#define stdeephist   NULL

Used by a state function when it handles a SIG_DEEPHIST signal (which represents that the state has a child deep history psuedostate).

#define stnone   NULL

Used by a state function when it returns no parent state (either because it is the top state or because the signal is handled).

---

Typedef Documentation

typedef stnext(* stfunc)(int, void *)

A state function

Todo:

make this definition better (simplehsm_state_t)?

typedef void* stnext

A generic pointer that points to a state function

---

Enumeration Type Documentation

enum simplehsm_signals_t

The base state machine signals

Enumerator:

SIG_NULL	Null signal, all state functions should ignore this signal and return their parent state (or stnone if the top level state)
SIG_INIT	Initialisation signal, a state function should transition to a default substate (simplehsm_init_transition_state()) if it has substates
SIG_ENTRY	Entry signal, a state function should perform its entry actions (if any)
SIG_DEEPHIST	Record deep history signal, a state function should return 'stdeephist' if it contains a deep history psuedostate
SIG_EXIT	Exit signal, a state function should perform its exit actions (if any)
SIG_USER	User signals should start from this index

---

Function Documentation

void simplehsm_init_transition_state	(	simplehsm_t *	hsm,
		stfunc	new_state
	)

Initiate an initial transition to a new state (this function should only be used from a SIG_INIT state event).

Parameters:

	hsm	The state machine to transition
	new_state	The state to transition to

void simplehsm_initialize	(	simplehsm_t *	hsm,
		stfunc	top_state
	)

Initialise a simplehsm state machine.

Parameters:

	hsm	The state machine to initialise
	top_state	The topmost (and initial) state of the hierarchy

BOOL simplehsm_is_in_state	(	simplehsm_t *	hsm,
		stfunc	state
	)

Check if a state machine is currently in a certain state.

Parameters:

	hsm	The state machine to check
	state	The state to check

Returns:

True if the state machine is currently in the specified state

void simplehsm_record_deephist	(	simplehsm_t *	hsm,
		stfunc	history_parent,
		stfunc	history_state
	)

Record deep history psuedostate.

Parameters:

	hsm	The state machine
	history_parent	The parent state of the deep history psuedostate
	history_state	The state to return to if transitioning to the deep history psuedostate

stfunc simplehsm_retrieve_deephist	(	simplehsm_t *	hsm,
		stfunc	history_parent
	)

Retrive deep history psuedostate.

Parameters:

	hsm	The state machine
	history_parent	The parent state of the deep history psuedostate

Returns:

The state to transition to via the deep history psuedostate

void simplehsm_signal_current_state	(	simplehsm_t *	hsm,
		int	signal,
		void *	param
	)

Send a signal to the state machine.

Parameters:

	hsm	The state machine to signal
	signal	The signal flag
	param	An optional parameter to accompany the signal

void simplehsm_transition_state	(	simplehsm_t *	hsm,
		stfunc	new_state
	)

Initiate a transition to a new state.

Parameters:

	hsm	The state machine to transition
	new_state	The state to transition to

void simplehsm_transition_state_ex	(	simplehsm_t *	hsm,
		stfunc	new_state,
		BOOL	to_deep_hist
	)

Initiate a transition to a new state.

This function will:

• replace the target state with the deep history target if required
• store a deep history target state if exiting a composite state with a deep history child
• perform the exit/entry chain from the current state to the target state

Parameters:

	hsm	The state machine to transition
	new_state	The state to transition to
	to_deep_hist	Whether to transition to the states internal deep history psuedostate