src/framework/engine-controller/task.h

   1 /*
   2  * sync-agent
   3  * Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the License);
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17
  18 #ifndef TASK_H_
  19 #define TASK_H_
  20
  21 #include <sys/time.h>
  22 #include <glib.h>
  23 #include "engine-controller/param.h"
  24 #include "engine-controller/param_internal.h"
  25 #include "engine-controller/task_spec.h"
  26 #include "engine-controller/task_cancel_info.h"
  27 #include "engine-controller/message.h"
  28 #include "engine-controller/task_info_pool.h"
  29 #include "utility/fw_ref.h"
  30
  31 /**
  32  * @file                task.h
  33  * @brief       Defines engine controller task APIs
  34  */
  35
  36 /** @addtogroup engine_controller
  37  *      @{
  38  */
  39
  40 /**
  41  * @brief Structure for task
  42  */
  43 typedef struct ec_task_s ec_task_t;
  44
  45 /**
  46  * @brief Structure for task
  47  */
  48 struct ec_task_s {
  49         sync_agent_ec_int ref_count;            /**< Reference count */
  50
  51         sync_agent_ec_task_error_e task_error;          /**< Task error */
  52
  53         ec_task_info_t *task_info;                                      /**< Task information */
  54         GSList *progress_blocking_realized_entity_list; /**< containing ec_progress_blocking_realized_entity_t* */
  55         GSList *current_node_in_progress_blocking_entity_list;  /**< containing ec_n_ary_tree_node_with_flag_t* */
  56
  57         sync_agent_ec_task_spec_s *task_spec;           /**< Task spec */
  58         sync_agent_util_ref_object_s *request_msg;      /**< Request message(containing ec_request_msg_t*) */
  59
  60         ec_task_cancel_info_t *cancel_information;              /**< Cancel information */
  61         sync_agent_ec_param_param_s **param_array;              /**< Parameter array */
  62
  63         /* information of dynamic case */
  64         sync_agent_ec_int dynamic_case;                 /**< dynamic case(only use when task spec is dynamic) */
  65
  66         /* information of parent link */
  67         ec_task_t *parent_task;                                 /**< Parent task */
  68         sync_agent_ec_int child_task_index_in_parent_task;                      /**< Child task index in parent task */
  69
  70         /* information of child link */
  71         ec_task_t **child_task_array;                   /**< Child task array */
  72
  73         sync_agent_ec_uint cnt_left_child_task_to_finish;                       /**< Left child task count to finish */
  74
  75         sync_agent_ec_uint *current_child_task_control_flow_in_degree_array;            /**< Current child task control flow in degree array */
  76
  77         struct timeval create_time;                     /**< Create time */
  78         struct timeval run_time;                        /**< Run time */
  79         struct timeval finish_time;                     /**< Finish time */
  80 };
  81
  82 /**
  83  * @brief Construct progress_blocking_realized_entity_list
  84  * @param[in] task_info ec_task_info_t
  85  * @return progress_blocking_realized_entity_list on success, NULL on fail
  86  * @retval progress_blocking_realized_entity_list Successful
  87  * @retval NULL Fail
  88  */
  89 GSList *ec_task_construct_progress_blocking_realized_entity_list(ec_task_info_t * task_info);
  90
  91 /**
  92  * @brief Allocate root task
  93  * @param[in] task_spec sync_agent_ec_task_spec_s
  94  * @param[in] request_msg ec_request_msg_t
  95  * @param[in] task_info_pool ec_task_info_pool_t
  96  * @return ec_task_t on success, NULL on fail
  97  * @retval root task Successful
  98  * @retval NULL Fail
  99  */
 100 ec_task_t *ec_task_alloc_root_task(sync_agent_ec_task_spec_s * task_spec, ec_request_msg_t * request_msg, ec_task_info_pool_t * task_info_pool);
 101
 102 /**
 103  * @brief Allocate child task
 104  * @param[in] parent_task ec_task_t
 105  * @param[in] child_index sync_agent_ec_int
 106  * @return ec_task_t on success, NULL on fail
 107  * @retval child task Successful
 108  * @retval NULL Fail
 109  */
 110 ec_task_t *ec_task_alloc_child_task(ec_task_t * parent_task, sync_agent_ec_int child_index);
 111
 112 /**
 113  * @brief Increase task reference count
 114  * @param[in] task ec_task_t
 115  * @return ec_task_t on success, NULL on fail
 116  * @retval task Successful
 117  */
 118 ec_task_t *ec_task_ref_task(ec_task_t * task);
 119
 120 /**
 121  * @brief Decrease task reference count
 122  * @param[in] task ec_task_t
 123  */
 124 void ec_task_unref_task(ec_task_t * task);
 125
 126 /**
 127  * @brief Check that inputted task is simple task or not
 128  * @param[in] task ec_task_t
 129  * @return true on success, false on fail
 130  * @retval true Simple task
 131  * @retval false Others
 132  */
 133 sync_agent_ec_boolean ec_task_is_simple_task(ec_task_t * task);
 134
 135 /**
 136  * @brief Check that inputted task is container task or not
 137  * @param[in] task ec_task_t
 138  * @return true on success, false on fail
 139  * @retval true Container task
 140  * @retval false Others
 141  */
 142 sync_agent_ec_boolean ec_task_is_container_task(ec_task_t * task);
 143
 144 /**
 145  * @brief Check that inputted task is root task or not
 146  * @param[in] task ec_task_t
 147  * @return true on success, false on fail
 148  * @retval true Root task
 149  * @retval false Others
 150  */
 151 sync_agent_ec_boolean ec_task_is_root_task(ec_task_t * task);
 152
 153 /**
 154  * @brief Get parameter count
 155  * @param[in] task ec_task_t
 156  * @return Parameter count
 157  */
 158 sync_agent_ec_int ec_task_get_param_cnt(ec_task_t * task);
 159
 160 /**
 161  * @brief Get output parameter information
 162  * @param[in] task ec_task_t
 163  * @param[out] pOutput_param_cnt output parameter count
 164  * @param[out] pOutput_param_index_array output parameter index array
 165  * @return true on success, false on fail
 166  * @retval true Successful
 167  * @retval false Fail
 168  */
 169 sync_agent_ec_int ec_task_get_output_param_info(ec_task_t * task, sync_agent_ec_int * pOutput_param_cnt, sync_agent_ec_int ** pOutput_param_index_array);
 170
 171 /**
 172  * @brief Get child task count
 173  * @param[in] task ec_task_t
 174  * @return Child task count
 175  */
 176 sync_agent_ec_uint ec_task_get_child_task_cnt(ec_task_t * task);
 177
 178 /**
 179  * @brief Get parent task
 180  * @param[in] task ec_task_t
 181  * @return parent task on success, NULL on fail
 182  * @retval parent task Successful
 183  * @retval NULL Fail
 184  */
 185 ec_task_t *ec_task_get_parent_task(ec_task_t * task);
 186
 187 /**
 188  * @brief Get child index in parent task
 189  * @param[in] task ec_task_t
 190  * @return child index
 191  */
 192 sync_agent_ec_int ec_task_get_child_index_in_parent_task(ec_task_t * task);
 193
 194 /**
 195  * @brief Set task error
 196  * @param[in] task ec_task_t
 197  * @param[in] task_error sync_agent_ec_task_error_e
 198  */
 199 void ec_task_set_task_error(ec_task_t * task, sync_agent_ec_task_error_e task_error);
 200
 201 /**
 202  * @brief Check same task error
 203  * @param[in] task ec_task_t
 204  * @param[in] task_error sync_agent_ec_task_error_e
 205  * @return true on success, false on fail
 206  * @retval true same task
 207  * @retval false not same task
 208  */
 209 sync_agent_ec_boolean ec_task_check_same_task_error(ec_task_t * task, sync_agent_ec_task_error_e task_error);
 210
 211 /**
 212  * @brief Check inputted task is not yet run
 213  * @param[in] task ec_task_t
 214  * @return true on success, false on fail
 215  * @retval true not run
 216  * @retval false already run
 217  */
 218 sync_agent_ec_boolean ec_task_is_not_yet_run(ec_task_t * task);
 219
 220 /**
 221  * @brief Request cancel
 222  * @param[in] task ec_task_t
 223  */
 224 void ec_task_do_cancellation(ec_task_t * task);
 225
 226 /**
 227  * @brief Call task finish callback
 228  * @param[in] task ec_task_t
 229  */
 230 void ec_task_call_task_finish_callback(ec_task_t * task);
 231
 232 /**
 233  * @brief Remove control flow
 234  * @param[in] parent_task ec_task_t
 235  * @param[in] from_task_index from index
 236  * @param[in] to_task_index to index
 237  */
 238 void ec_task_remove_control_flow(ec_task_t * parent_task, sync_agent_ec_int from_task_index, sync_agent_ec_int to_task_index);
 239
 240 /**
 241  * @brief Set left child to run
 242  * @param[in] parent_task ec_task_t
 243  * @param[in] number left child count
 244  */
 245 void ec_task_set_left_child_to_run(ec_task_t * parent_task, sync_agent_ec_uint number);
 246
 247 /**
 248  * @brief Check inputted parent task has no more left child to run
 249  * @param[in] parent_task ec_task_t
 250  * @return true on success, false on fail
 251  * @retval true no more child to run
 252  * @retval false child task left
 253  */
 254 sync_agent_ec_boolean ec_task_is_left_child_to_run_zero(ec_task_t * parent_task);
 255
 256 /**
 257  * @brief Decrease left child to run
 258  * @param[in] parent_task ec_task_t
 259  */
 260 void ec_task_decrease_left_child_to_run(ec_task_t * parent_task);
 261
 262 /**
 263  * @brief check inputted parent task is EC_TASK_DONE
 264  * @param[in] parent_task ec_task_t
 265  * @return true on success, false on fail
 266  * @retval true EC_TASK_DONE
 267  * @retval false others
 268  */
 269 sync_agent_ec_boolean ec_task_is_parent_EC_TASK_DONE(ec_task_t * parent_task);
 270
 271 /**
 272  * @brief Collect parent task output parameter
 273  * @param[in] parent_task ec_task_t
 274  */
 275 void ec_task_collect_parent_task_output_parameter(ec_task_t * parent_task);
 276
 277 /**
 278  * @brief Collect firstly runnable child tasks
 279  * @param[in] parent_task ec_task_t
 280  * @return runnable child tasks on success, false on fail
 281  * @retval runnable child tasks Successful
 282  * @retval NULL Fail
 283  */
 284 GSList *ec_collect_firstly_runnable_child_tasks(ec_task_t * parent_task);
 285
 286 /**
 287  * @brief Collect become runnable child tasks by remove control flow
 288  * @param[in] parent_task ec_task_t
 289  * @param[in] from_child_task_index child task index
 290  * @return runnable child tasks on success, false on fail
 291  * @retval runnable child tasks Successful
 292  * @retval NULL Fail
 293  */
 294 GSList *ec_collect_become_runnable_child_tasks_by_remove_control_flow(ec_task_t * parent_task, sync_agent_ec_int from_child_task_index);
 295
 296 /**
 297  * @brief Run simple task
 298  * @param[in] pSimple_task ec_task_t
 299  * @return SYNC_AGENT_EC_TASK_ERROR_RUN_SUCCESS on success, otherwise error value
 300  * @retval SYNC_AGENT_EC_TASK_ERROR_RUN_SUCCESS Successful
 301  * @retval SYNC_AGENT_EC_TASK_ERROR_CANCELED Fail
 302  */
 303 sync_agent_ec_task_error_e ec_task_run_simple_task(ec_task_t * pSimple_task);
 304
 305 /**
 306  * @brief Add pending task list of first progress blocking realized entity
 307  * @remarks return true if pending is done
 308  * @param[in] task ec_task_t
 309  * @return true on success, false on fail
 310  * @retval true Successful
 311  * @retval false Fail
 312  */
 313 sync_agent_ec_boolean ec_task_add_pending_task_list_of_first_progress_blocking_realized_entity(ec_task_t * task);
 314
 315 /**
 316  * @brief Update progress blocking realized entity and pop if possible
 317  * @param[in] task ec_task_t
 318  */
 319 void ec_task_update_progress_blocking_realized_entity_and_pop_if_possible(ec_task_t * task);
 320
 321 /**
 322  * @brief Structure for progress blocking realized entity
 323  */
 324 typedef struct ec_progress_blocking_realized_entity_s ec_progress_blocking_realized_entity_t;
 325
 326 /**
 327  * @brief Structure for progress blocking realized entity
 328  */
 329 struct ec_progress_blocking_realized_entity_s {
 330         sync_agent_ec_uint left_progress_blocking_element_cnt;                  /**< Left progress blocking element count */
 331
 332         ec_progress_blocking_entity_t *entity;                                          /**< Blocking entity */
 333         GSList *pending_task_list;                                                                      /**< Pending task list(containing ec_task_t*) */
 334 };
 335
 336 /**
 337  * @brief Create ec_progress_blocking_realized_entity_t
 338  * @param[in] entity ec_progress_blocking_entity_t
 339  * @return progress blocking realized entity on success, NULL on fail
 340  * @retval ec_progress_blocking_realized_entity_t Successful
 341  * @retval NULL Fail
 342  */
 343 ec_progress_blocking_realized_entity_t *ec_progress_blocking_realized_entity_new(ec_progress_blocking_entity_t * entity);
 344
 345 /**
 346  * @brief Free ec_progress_blocking_realized_entity_t
 347  * @param[in] realized_entity ec_progress_blocking_realized_entity_t
 348  */
 349 void ec_progress_blocking_realized_entity_free(ec_progress_blocking_realized_entity_t * realized_entity);
 350
 351 /**
 352  * @brief Restart pending task
 353  * @param[in] realized_entity ec_progress_blocking_realized_entity_t
 354  */
 355 void ec_progress_blocking_realized_entity_restart_pending_task(ec_progress_blocking_realized_entity_t * realized_entity);
 356
 357 /**
 358  * @brief Add pending task
 359  * @param[in] entity ec_progress_blocking_realized_entity_t
 360  * @param[in] pending_task ec_task_t
 361  */
 362 void ec_progress_blocking_realized_entity_add_pending_task(ec_progress_blocking_realized_entity_t * entity, ec_task_t * pending_task);
 363
 364 /**
 365  * @brief Update progress blocking realized entity and test left progress blocking element count
 366  * @remarks return true when left_progress_blocking_element_cnt are updated and become zero
 367  * @param[in] realized_entity ec_progress_blocking_realized_entity_t
 368  * @param[in] current_node ec_n_ary_tree_node_with_flag_t
 369  * @param[in] task ec_task_t
 370  * @return true on success, false on fail
 371  * @retval true Successful
 372  * @retval false Fail
 373  */
 374 sync_agent_ec_boolean ec_progress_blocking_realized_entity_update_and_test_left_progress_blocking_element_cnt(ec_progress_blocking_realized_entity_t * realized_entity, ec_n_ary_tree_node_with_flag_t * current_node, ec_task_t * task);
 375
 376 /**
 377  * @brief Check left progress blocking element count
 378  * @remarks return true when left_progress_blocking_element_cnt are updated and become zero
 379  * @param[in] realized_entity ec_progress_blocking_realized_entity_t
 380  * @return true on success, false on fail
 381  * @retval true Successful
 382  * @retval false Fail
 383  */
 384 sync_agent_ec_boolean ec_progress_blocking_realized_entity_is_zero_left_progress_blocking_element_cnt(ec_progress_blocking_realized_entity_t * realized_entity);
 385
 386 /**
 387  *      @}
 388  */
 389
 390 #endif                          /* TASK_H_ */