2 * @copyright Copyright (c) 2016-2020 TOYOTA MOTOR CORPORATION.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 ///////////////////////////////////////////////////////////////////////////////
18 /// \ingroup tag_NSFramework
19 /// \~english \brief Application framework's core structures and data types.
23 ///////////////////////////////////////////////////////////////////////////////
26 * @file frameworkunified_sm_multithreading.h
27 * @brief \~english Application framework's core structures and data types.
30 /** @addtogroup BaseSystem
33 /** @addtogroup native_service
37 /** @addtogroup framework_unified
38 * @ingroup native_service
41 /** @addtogroup framework
42 * @ingroup framework_unified
45 /** @addtogroup statemachine
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__
53 #include <native_service/frameworkunified_framework_types.h>
55 ////////////////////////////////////////////////////////////////////////////////////////////
56 /// \ingroup FrameworkunifiedCreateHSMChildThread
57 /// \~english @par Brief
58 /// Start a subordinate dispatcher in a separate thread
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
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
97 /// \~english @par Type
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.
105 ////////////////////////////////////////////////////////////////////////////////////////////
106 HANDLE FrameworkunifiedCreateHSMChildThread(HANDLE hApp, PCSTR childName, CbFuncPtr CbInitialize, CbFuncPtr
107 CbShutdown, CbFuncPtr CbCreateStateMachine);
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
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
153 /// \~english @par Type
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.
161 ////////////////////////////////////////////////////////////////////////////////////
162 HANDLE FrameworkunifiedCreateHSMChildThreadWithPriority(HANDLE hApp, PCSTR childName, CbFuncPtr CbInitialize,
163 CbFuncPtr CbShutdown, CbFuncPtr CbCreateStateMachine, SI_32 schedPrio);
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
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
208 /// \~english @par Type
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.
216 ////////////////////////////////////////////////////////////////////////////////////
217 HANDLE FrameworkunifiedCreateHSMChildThreadWithAttribute(HANDLE hApp, PCSTR childName, CbFuncPtr CbInitialize,
218 CbFuncPtr CbShutdown, CbFuncPtr CbCreateStateMachine,
219 const FrameworkunifiedChildThreadAttr *attr);
221 #endif /* __FRAMEWORKUNIFIED_NATIVESERVICES_NATIVESERVICES_INC_FRAMEWORK_STATEMACHINE_FRAMEWORKUNIFIED_SM_MULTITHREADING_H__ */ // NOLINT (build/header_guard)