video_in_hal/nsframework/framework_unified/client/include/native_service/frameworkunified_sm_multithreading.h

   1 /*
   2  * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 ///////////////////////////////////////////////////////////////////////////////
  18 /// \ingroup  tag_NSFramework
  19 /// \~english \brief    Application framework's core structures and data types.
  20 ///
  21 ///
  22 ///
  23 ///////////////////////////////////////////////////////////////////////////////
  24 //@{
  25 /**
  26  * @file frameworkunified_sm_multithreading.h
  27  * @brief \~english Application framework's core structures and data types.
  28  *
  29  */
  30 /** @addtogroup BaseSystem
  31  *  @{
  32  */
  33 /** @addtogroup native_service
  34  *  @ingroup BaseSystem
  35  *  @{
  36  */
  37 /** @addtogroup framework_unified
  38  *  @ingroup native_service
  39  *  @{
  40  */
  41 /** @addtogroup framework
  42  *  @ingroup framework_unified
  43  *  @{
  44  */
  45 /** @addtogroup statemachine
  46  *  @ingroup framework
  47  *  @{
  48  */
  49
  50 #ifndef __FRAMEWORKUNIFIED_NATIVESERVICES_NATIVESERVICES_INC_FRAMEWORK_STATEMACHINE_FRAMEWORKUNIFIED_SM_MULTITHREADING_H__  // NOLINT  (build/header_guard)
  51 #define __FRAMEWORKUNIFIED_NATIVESERVICES_NATIVESERVICES_INC_FRAMEWORK_STATEMACHINE_FRAMEWORKUNIFIED_SM_MULTITHREADING_H__
  52
  53 #include <native_service/frameworkunified_framework_types.h>
  54
  55 ////////////////////////////////////////////////////////////////////////////////////////////
  56 /// \ingroup FrameworkunifiedCreateHSMChildThread
  57 /// \~english @par Brief
  58 /// Start a subordinate dispatcher in a separate thread
  59 ///
  60 /// \~english \param [in] hApp
  61 ///         HANDLE - parent framework HANDLE
  62 /// \~english \param [in] childName
  63 ///     PCSTR - Name to give to the child object
  64 /// \~english \param [in] CbInitialize
  65 ///          CbFuncPtr -  Initialization callback - use this to initialize and configure
  66 ///             the child's dispatcher.
  67 /// \~english \param [in] CbShutdown
  68 ///      CbFuncPtr -  Shutdown callback - use this to shutdown and close the child
  69 ///             The correct way for child to exit dispatch loop is to return eFrameworkunifiedStatusExit
  70 ///                       directly from this callback, or from some other interaction triggered by this
  71 ///                       callback
  72 ///
  73 /// \~english \param [in] CbCreateStateMachine
  74 ///      CbFuncPtr -  StateMachine callback - use this to add new states, events and reactions
  75 ///             in the Thread statemachine.
  76 /// \~english @retval HANDLE    create thread with Priority success
  77 /// \~english @retval NULL    create thread with Priority failed
  78 /// \~english @par Preconditions
  79 ///        - Generation/Initialization of Dispatcher for the Application
  80 ///          (FrameworkunifiedCreateDispatcherWithoutLoop, etc.) has been done.
  81 /// \~english @par Change of the internal state
  82 ///       - Change of internal state according to the API does not occur.
  83 /// \~english @par Conditions of processing failure
  84 ///        - HANDLE specified in the argument (hApp) is NULL. [NULL]
  85 ///        - HANDLE specified in the argument (hApp) is not appropriate (which is invalid). [NULL]
  86 ///        - Message queue name specified in the argument (childName) is not appropriate (NULL, over 16byte). [NULL]
  87 ///        - Callback function pointer specified in the argument (CbInitialize,CbShutdown) is NULL. [NULL]
  88 ///        - Thread attribute specified in the argument (attr) is NULL. [NULL]
  89 ///        - Failed to set the inherit-scheduler attribute (pthread_attr_setinheritsched) of the child thread. [NULL]
  90 ///        - Failed to initialize barrier object (pthread_barrier_init) for thread synchronization. [NULL]
  91 ///        - Failed to create child thread (pthread_create). [NULL]
  92 ///        - Failed to wait thread synchronization (pthread_barrier_wait). [NULL]
  93 ///        - Can not be acquired memory for message queue name(malloc). [NULL]
  94 ///        - Failed to open message queue(mq_open). [NULL]
  95 /// \~english @par Classification
  96 ///       Public
  97 /// \~english @par Type
  98 ///       sync only
  99 /// \~english @par Detail
 100 ///       Start a subordinate dispatcher in a separate thread
 101 ///       This API creates a child thread and returns a handle for communication with the child thread.\n
 102 ///       After creating/initializing the Dispatcher for the child thread, the child thread receives requests
 103 ///       and notifications to the Dispatcher and starts a main loop that executes the registered callback.
 104 /// \~english @see
 105 ////////////////////////////////////////////////////////////////////////////////////////////
 106 HANDLE FrameworkunifiedCreateHSMChildThread(HANDLE hApp, PCSTR childName, CbFuncPtr CbInitialize, CbFuncPtr
 107                                CbShutdown, CbFuncPtr CbCreateStateMachine);
 108
 109
 110   /////////////////////////////////////////////////////////////////////////////////////
 111   /// \ingroup FrameworkunifiedCreateHSMChildThread
 112   /// \~english @par Summary
 113   ///       Start a subordinate dispatcher in a separate thread with given Priority
 114   /// \~english @param [in] hApp
 115   ///         HANDLE - parent framework HANDLE
 116   /// \~english @param [in] childName
 117   ///     PCSTR - Name to give to the child object
 118   /// \~english @param [in] CbInitialize
 119   ///         CbFuncPtr -  Initialization callback - use this to initialize and configure
 120   ///             the child's dispatcher.
 121   /// \~english @param [in] CbShutdown
 122   ///         CbFuncPtr -  Shutdown callback - use this to shutdown and close the child
 123   ///             The correct way for child to exit dispatch loop is to return eFrameworkunifiedStatusExit
 124   ///                       directly from this callback, or from some other interaction triggered by this
 125   ///                       callback
 126   ///
 127   /// \~english @param [in] CbCreateStateMachine
 128   ///         CbFuncPtr -  StateMachine callback - use this to add new states, events and reactions
 129   ///             in the Thread statemachine.
 130   /// \~english @param [in] schedPrio
 131   ///       SI_32 - given Priority for create thread
 132   /// \~english @retval HANDLE    create thread with Priority success
 133   /// \~english @retval NULL    create thread with Priority failed
 134   /// \~english @par Preconditions
 135 ///        - Generation/Initialization of Dispatcher for the Application
 136 ///          (FrameworkunifiedCreateDispatcherWithoutLoop, etc.) has been done.
 137   /// \~english @par Change of the internal state
 138   ///       - Change of internal state according to the API does not occur.
 139 /// \~english @par Conditions of processing failure
 140 ///        - HANDLE specified in the argument (hApp) is NULL. [NULL]
 141 ///        - HANDLE specified in the argument (hApp) is not appropriate (which is invalid). [NULL]
 142 ///        - Message queue name specified in the argument (childName) is not appropriate (NULL, over 16byte). [NULL]
 143 ///        - Callback function pointer specified in the argument (CbInitialize,CbShutdown) is NULL. [NULL]
 144 ///        - Thread attribute specified in the argument (attr) is NULL. [NULL]
 145 ///        - Failed to set the inherit-scheduler attribute (pthread_attr_setinheritsched) of the child thread. [NULL]
 146 ///        - Failed to initialize barrier object (pthread_barrier_init) for thread synchronization. [NULL]
 147 ///        - Failed to create child thread (pthread_create). [NULL]
 148 ///        - Failed to wait thread synchronization (pthread_barrier_wait). [NULL]
 149 ///        - Can not be acquired memory for message queue name(malloc). [NULL]
 150 ///        - Failed to open message queue(mq_open). [NULL]
 151   /// \~english @par Classification
 152   ///       Public
 153   /// \~english @par Type
 154   ///       sync only
 155   /// \~english @par Detail
 156   ///       Start a subordinate dispatcher in a separate thread with given Priority
 157   ///       This API creates a child thread and returns a handle for communication with the child thread.\n
 158   ///       After creating/initializing the Dispatcher for the child thread, the child thread receives requests
 159   ///       and notifications to the Dispatcher and starts a main loop that executes the registered callback.
 160   /// \~english @see
 161   ////////////////////////////////////////////////////////////////////////////////////
 162 HANDLE FrameworkunifiedCreateHSMChildThreadWithPriority(HANDLE hApp, PCSTR childName, CbFuncPtr CbInitialize,
 163                                            CbFuncPtr CbShutdown, CbFuncPtr CbCreateStateMachine, SI_32 schedPrio);
 164
 165   /////////////////////////////////////////////////////////////////////////////////////
 166   /// \ingroup FrameworkunifiedCreateHSMChildThread
 167   /// \~english @par Summary
 168   ///       Start a subordinate dispatcher in a separate thread with given attribute
 169   /// \~english @param [in] hApp
 170   ///         HANDLE - parent framework HANDLE
 171   /// \~english @param [in] childName
 172   ///     PCSTR - Name to give to the child object
 173   /// \~english @param [in] CbInitialize
 174   ///         CbFuncPtr -  Initialization callback - use this to initialize and configure
 175   ///             the child's dispatcher.
 176   /// \~english @param [in] CbShutdown
 177   ///         CbFuncPtr -  Shutdown callback - use this to shutdown and close the child
 178   ///             The correct way for child to exit dispatch loop is to return eFrameworkunifiedStatusExit
 179   ///                       directly from this callback, or from some other interaction triggered by this
 180   ///                       callback
 181   ///
 182   /// \~english @param [in] CbCreateStateMachine
 183   ///         CbFuncPtr -  StateMachine callback - use this to add new states, events and reactions
 184   ///             in the Thread statemachine.
 185   /// \~english @param [in] attr
 186   ///       const FrameworkunifiedChildThreadAttr * -  given attribute to create thread
 187   /// \~english @retval HANDLE    create thread with Priority success
 188   /// \~english @retval NULL    create thread with Priority failed
 189   /// \~english @par Preconditions
 190 ///        - Generation/Initialization of Dispatcher for the Application
 191 ///          (FrameworkunifiedCreateDispatcherWithoutLoop, etc.) has been done.
 192   /// \~english @par Change of the internal state
 193   ///       - Change of internal state according to the API does not occur.
 194 /// \~english @par Conditions of processing failure
 195 ///        - HANDLE specified in the argument (hApp) is NULL. [NULL]
 196 ///        - HANDLE specified in the argument (hApp) is not appropriate (which is invalid). [NULL]
 197 ///        - Message queue name specified in the argument (childName) is not appropriate (NULL, over 16byte). [NULL]
 198 ///        - Callback function pointer specified in the argument (CbInitialize,CbShutdown) is NULL. [NULL]
 199 ///        - Thread attribute specified in the argument (attr) is NULL. [NULL]
 200 ///        - Failed to set the inherit-scheduler attribute (pthread_attr_setinheritsched) of the child thread. [NULL]
 201 ///        - Failed to initialize barrier object (pthread_barrier_init) for thread synchronization. [NULL]
 202 ///        - Failed to create child thread (pthread_create). [NULL]
 203 ///        - Failed to wait thread synchronization (pthread_barrier_wait). [NULL]
 204 ///        - Can not be acquired memory for message queue name(malloc). [NULL]
 205 ///        - Failed to open message queue(mq_open). [NULL]
 206   /// \~english @par Classification
 207   ///       Public
 208   /// \~english @par Type
 209   ///       sync only
 210   /// \~english @par Detail
 211   ///       Start a subordinate dispatcher in a separate thread with given attribute
 212   ///       This API creates a child thread and returns a handle for communication with the child thread.\n
 213   ///       After creating/initializing the Dispatcher for the child thread, the child thread receives requests
 214   ///       and notifications to the Dispatcher and starts a main loop that executes the registered callback.
 215   /// \~english @see
 216   ////////////////////////////////////////////////////////////////////////////////////
 217 HANDLE FrameworkunifiedCreateHSMChildThreadWithAttribute(HANDLE hApp, PCSTR childName, CbFuncPtr CbInitialize,
 218                                             CbFuncPtr CbShutdown, CbFuncPtr CbCreateStateMachine,
 219                                             const FrameworkunifiedChildThreadAttr *attr);
 220
 221 #endif /* __FRAMEWORKUNIFIED_NATIVESERVICES_NATIVESERVICES_INC_FRAMEWORK_STATEMACHINE_FRAMEWORKUNIFIED_SM_MULTITHREADING_H__ */  // NOLINT  (build/header_guard)
 222 /** @}*/
 223 /** @}*/
 224 /** @}*/
 225 /** @}*/
 226 /** @}*/
 227 //@}