src/session/gfsm.h

   1 /*finite state machine
   2  *
   3  * Copyright (c) 2011 - 2013 Samsung Electronics Co., Ltd. All rights reserved.
   4  *
   5  * Contact: Hojeen Jee <hojeen.jee@samsung.com>, Jaejun Sim <jj.sim@samsung.com>,
   6  * Jinho Ha <jinho89.ha@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  */
  21
  22 #ifndef _GFSM_
  23 #define _GFSM_
  24
  25 /*****************************************************************************
  26  * constants and Typedefs
  27  *****************************************************************************/
  28
  29 typedef unsigned int gfsm_state_id_t;
  30 typedef unsigned int gfsm_event_id_t;
  31
  32 typedef struct gfsm_event gfsm_event_s;
  33 typedef struct gfsm_state gfsm_state_s;
  34 typedef struct gfsm gfsm_s;
  35 typedef struct gfsm_context gfsm_context_s;
  36
  37 typedef void (*gfsm_entry_action_cb)(void *p_context_data);
  38 typedef void (*gfsm_exit_action_cb)(void *p_context_data);
  39 typedef gfsm_state_id_t(*gfsm_reaction_cb)(void *p_context_data,
  40                 void *p_event_data);
  41 typedef void (*gfsm_event_data_destructor_cb)(void *p_event_data);
  42 typedef void (*gfsm_context_termination_notifier_cb)(void *p_context_data);
  43
  44 typedef const char *(*gfsm_get_state_name_cb)(gfsm_state_id_t state_id);
  45 typedef const char *(*gfsm_get_event_name_cb)(gfsm_event_id_t event_id);
  46 typedef int (*gfsm_log_func)(const char *format, ...);
  47
  48 static const gfsm_state_id_t GFSM_DISCARD_EVENT = 0xFFFFFFFF;
  49 static const gfsm_state_id_t GFSM_DEFER_EVENT = 0xFFFFFFFE;
  50
  51 /**
  52  * @brief This function creates a generic fsm object
  53  * @param [in] max_state        maximum num of state
  54  * @param [in] max_event        maximum num of event
  55  * @param [in] init_state       state id of initial state
  56  * @return a pointer of gfsm object
  57 */
  58 gfsm_s *gfsm_create_fsm(gfsm_state_id_t max_state, gfsm_event_id_t max_event,
  59                         gfsm_state_id_t init_state);
  60
  61 /**
  62  * @brief This function destroys a generic fsm object
  63  * @param [in] a pointer of gfsm object
  64  * @return void
  65 */
  66 void gfsm_destroy_fsm(gfsm_s *p_fsm);
  67
  68 /**
  69  * @brief This function add a state on a gfsm object
  70  * @param [in] p_fsm a pointer of a gfsm
  71  * @param [in] p_state a pointer of a gfsm_state
  72  * @return void
  73 */
  74 void gfsm_add_state(gfsm_s *p_fsm, gfsm_state_s *p_state);
  75
  76 /**
  77  * @brief This function create a state object
  78  * @param [in] state_id state id of this state
  79  * @param [in] p_fsm a pointer of gfsm
  80  * @param [in] entry_action callback function that will be called when entering into this state.
  81  * @param [in] exit_action callback function that will be called when exiting from this state.
  82  * @return a pointer of state object
  83 */
  84 gfsm_state_s *gfsm_create_state(gfsm_state_id_t state_id, gfsm_s *p_fsm,
  85                                 gfsm_entry_action_cb entry_action, gfsm_exit_action_cb exit_action);
  86
  87 /**
  88  * @brief This function destroys a state object
  89  * @param [in] p_state a pointer of state object
  90  * @return void
  91 */
  92 void gfsm_destroy_state(gfsm_state_s *p_state);
  93
  94 /**
  95  * @brief This function set parent state of this state
  96  * @param [in] p_state a pointer of child state
  97  * @param [in] p_parent_state a pointer of parent state
  98  * @return void
  99 */
 100 void gfsm_set_parent_state(gfsm_state_s *p_state, gfsm_state_s *p_parent_state);
 101
 102 /**
 103  * @brief This function add reaction of event on a state
 104  * @param [in] p_state a pointer of state
 105  * @param [in] event_id ID of event that will be processed on this state
 106  * @param [in] reacton_cb callback function that will be called when event is received.
 107  * @return void
 108 */
 109 void gfsm_add_reaction(gfsm_state_s *p_state, gfsm_event_id_t event_id,
 110                        gfsm_reaction_cb reaction_cb);
 111
 112 /**
 113  * @brief This function will return a pointer of fsm that has this state.
 114  * @param [in] p_state a pointer of state
 115  * @return a pointer of fsm that possess this state
 116 */
 117 gfsm_s *gfsm_get_fsm_of_state(gfsm_state_s *p_state);
 118
 119 /**
 120  * @brief This function create a context object.
 121  * @param [in] p_fsm a pointer of fsm
 122  * @param [in] termination_notifier callback function that will be called when context is destroyed
 123  * @param [in] p_context_data user data that will be passed to reaction action, entry action, exit action
 124  * @return a pointer of context
 125 */
 126 gfsm_context_s *gfsm_create_context(gfsm_s *p_fsm,
 127                                     gfsm_context_termination_notifier_cb termination_notifier,
 128                                     void *p_context_data);
 129
 130 /**
 131  * @brief This function detroy a context object.
 132  * @param [in] p_context a pointer of context
 133  * @return void
 134 */
 135 void gfsm_destroy_context(gfsm_context_s *p_context);
 136
 137 /**
 138  * @brief this function process event
 139  * @param [in] pp_context a pointer of pointer of context
 140  * @param [in] p_event a pointer of event that will be processed
 141  * @return void
 142 */
 143 void gfsm_process_event(gfsm_context_s **pp_context, gfsm_event_s *p_event);
 144
 145 /**
 146  * @brief this function return a current state id
 147  * @param [in] p_context a pointer of context
 148  * @return current state id
 149 */
 150 gfsm_state_id_t gfsm_get_current_state_id(gfsm_context_s *p_context);
 151
 152 /**
 153  * @brief This function will return a pointer of fsm that has this context.
 154  * @param [in] p_context a pointer of context
 155  * @return a pointer of fsm that possess this context
 156 */
 157 gfsm_s *gfsm_get_fsm_of_context(gfsm_context_s *p_context);
 158
 159 /**
 160  * @brief this function create event object
 161  * @param       [in] event_id id of event that will be created
 162  * @param       [in] p_event_data user data that will be delivered to reaction functions
 163  * @param       [in] destructor callback function that will be called in order to destroy p_event_data
 164  * @return a pointer of event
 165 */
 166 gfsm_event_s *gfsm_create_event(gfsm_event_id_t event_id, void *p_event_data,
 167                                 gfsm_event_data_destructor_cb destructor);
 168
 169 /**
 170  * @brief predefined reaction function to defer event
 171  * @param [in] p_context_data user data of context
 172  * @param [in] p_event_data user data of event
 173  * @return a next state id
 174  *
 175  * @verbatim
 176  * gfsm_add_reaction(state1,event1,gfsm_deferral_reaction);
 177  * @endverbatim
 178 */
 179 gfsm_state_id_t gfsm_deferral_reaction(void *p_context_data,
 180                                        void *p_event_data);
 181
 182 /**
 183  * @brief this function will set logger function to help debugging
 184  * @param [in] p_fsm a pointer of fsm object
 185  * @param [in] log_func a function pointer to print log
 186  * @param [in] header a string that will be shown at the head of every log
 187  * @param [in] state_name_cb callback function that will pass string of state name
 188  * @param [in] event_name_cb callback function that will pass string of event name
 189  * @return void
 190  *
 191 */
 192 void gfsm_set_logger(gfsm_s *p_fsm, gfsm_log_func log_func, const char *header,
 193                      gfsm_get_state_name_cb state_name_cb, gfsm_get_event_name_cb event_name_cb);
 194
 195 #endif