Struct bl602_sdk::wifi::state

#[repr(C)]
pub struct state {
    pub parentState: *const state,
    pub entryState: *const state,
    pub transitions: *mut transition,
    pub numTransitions: size_t,
    pub data: *mut c_void,
    pub entryAction: Option<unsafe extern "C" fn(stateData: *mut c_void, event: *mut event)>,
    pub exitAction: Option<unsafe extern "C" fn(stateData: *mut c_void, event: *mut event)>,
}

\brief State

The current state in a state machine moves to a new state when one of the #transitions in the current state triggers on an event. An optional \ref #exitAction “exit action” is called when the state is left, and an \ref #entryAction “entry action” is called when the state machine enters a new state. If a state returns to itself, neither #exitAction nor #entryAction will be called. An optional \ref transition::action “transition action” is called in either case.

States may be organised in a hierarchy by setting \ref #parentState “parent states”. When a group/parent state is entered, the state machine is redirected to the group state’s \ref #entryState “entry state” (if non-NULL). If an event does not trigger a transition in a state and if the state has a parent state, the event will be passed to the parent state. This behaviour is repeated for all parents. Thus all children of a state have a set of common #transitions. A parent state’s #entryAction will not be called if an event is passed on to a child state.

The following lists the different types of states that may be created, and how to create them:

Normal state

struct state normalState = {
   .parentState = &groupState,
   .entryState = NULL,
   .transition = (struct transition[]){
      { Event_keyboard, (void *)(intptr_t)'\n', &compareKeyboardChar,
         NULL, &msgReceivedState },
   },
   .numTransitions = 1,
   .data = normalStateData,
   .entryAction = &doSomething,
   .exitAction = &cleanUp,
};

In this example, normalState is a child of groupState, but the #parentState value may also be NULL to indicate that it is not a child of any group state.

Group/parent state

A state becomes a group/parent state when it is linked to by child states by using #parentState. No members in the group state need to be set in a particular way. A parent state may also have a parent.

struct state groupState = {
   .entryState = &normalState,
   .entryAction = NULL,

If there are any transitions in the state machine that lead to a group state, it makes sense to define an entry state in the group. This can be done by using #entryState, but it is not mandatory. If the #entryState state has children, the chain of children will be traversed until a child with its #entryState set to NULL is found.

\note If #entryState is defined for a group state, the group state’s #entryAction will not be called (the state pointed to by #entryState (after following the chain of children), however, will have its #entryAction called).

\warning The state machine cannot detect cycles in parent chains and children chains. If such cycles are present, stateM_handleEvent() will never finish due to never-ending loops.

Final state

A final state is a state that terminates the state machine. A state is considered as a final state if its #numTransitions is 0:

struct state finalState = {
   .transitions = NULL,
   .numTransitions = 0,

The error state used by the state machine to indicate errors should be a final state. Any calls to stateM_handleEvent() when the current state is a final state will return #stateM_noStateChange.

\sa event \sa transition

Fields

parentState: *const state

\brief If the state has a parent state, this pointer must be non-NULL.

entryState: *const state

\brief If this state is a parent state, this pointer may point to a child state that serves as an entry point.

transitions: *mut transition

\brief An array of transitions for the state.

numTransitions: size_t

\brief Number of transitions in the #transitions array.

data: *mut c_void

\brief Data that will be available for the state in its #entryAction and #exitAction, and in any \ref transition::action “transition action”

entryAction: Option<unsafe extern "C" fn(stateData: *mut c_void, event: *mut event)>

\brief This function is called whenever the state is being entered. May be NULL.

\note If a state returns to itself through a transition (either directly or through a parent/group sate), its #entryAction will not be called.

\note A group/parent state with its #entryState defined will not have its #entryAction called.

\param stateData the state’s #data will be passed. \param event the event that triggered the transition will be passed.

exitAction: Option<unsafe extern "C" fn(stateData: *mut c_void, event: *mut event)>

\brief This function is called whenever the state is being left. May be NULL.

\note If a state returns to itself through a transition (either directly or through a parent/group sate), its #exitAction will not be called.

\param stateData the state’s #data will be passed. \param event the event that triggered a transition will be passed.

Trait Implementations

impl Clone for state

fn clone(&self) -> state

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for state

fn default() -> Self

Returns the “default value” for a type.

impl Copy for state