Nathan Yonkee
init
Embed:
(wiki syntax)
Show/hide line numbers
Thread.h
00001 /* mbed Microcontroller Library 00002 * Copyright (c) 2006-2012 ARM Limited 00003 * 00004 * Permission is hereby granted, free of charge, to any person obtaining a copy 00005 * of this software and associated documentation files (the "Software"), to deal 00006 * in the Software without restriction, including without limitation the rights 00007 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 00008 * copies of the Software, and to permit persons to whom the Software is 00009 * furnished to do so, subject to the following conditions: 00010 * 00011 * The above copyright notice and this permission notice shall be included in 00012 * all copies or substantial portions of the Software. 00013 * 00014 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 00015 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 00016 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 00017 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 00018 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 00019 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 00020 * SOFTWARE. 00021 */ 00022 #ifndef THREAD_H 00023 #define THREAD_H 00024 00025 #include <stdint.h> 00026 #include "cmsis_os2.h" 00027 #include "mbed_rtos1_types.h" 00028 #include "mbed_rtos_storage.h" 00029 #include "platform/Callback.h" 00030 #include "platform/mbed_toolchain.h" 00031 #include "platform/NonCopyable.h" 00032 #include "rtos/Semaphore.h" 00033 #include "rtos/Mutex.h" 00034 00035 namespace rtos { 00036 /** \addtogroup rtos */ 00037 /** @{*/ 00038 /** 00039 * \defgroup rtos_Thread Thread class 00040 * @{ 00041 */ 00042 00043 /** The Thread class allow defining, creating, and controlling thread functions in the system. 00044 * 00045 * Example: 00046 * @code 00047 * #include "mbed.h" 00048 * #include "rtos.h" 00049 * 00050 * Thread thread; 00051 * DigitalOut led1(LED1); 00052 * volatile bool running = true; 00053 * 00054 * // Blink function toggles the led in a long running loop 00055 * void blink(DigitalOut *led) { 00056 * while (running) { 00057 * *led = !*led; 00058 * wait(1); 00059 * } 00060 * } 00061 * 00062 * // Spawns a thread to run blink for 5 seconds 00063 * int main() { 00064 * thread.start(callback(blink, &led1)); 00065 * wait(5); 00066 * running = false; 00067 * thread.join(); 00068 * } 00069 * @endcode 00070 * 00071 * @note 00072 * Memory considerations: The thread control structures will be created on current thread's stack, both for the mbed OS 00073 * and underlying RTOS objects (static or dynamic RTOS memory pools are not being used). 00074 * Additionally the stack memory for this thread will be allocated on the heap, if it wasn't supplied to the constructor. 00075 */ 00076 class Thread : private mbed::NonCopyable<Thread> { 00077 public: 00078 /** Allocate a new thread without starting execution 00079 @param priority initial priority of the thread function. (default: osPriorityNormal). 00080 @param stack_size stack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE). 00081 @param stack_mem pointer to the stack area to be used by this thread (default: NULL). 00082 @param name name to be used for this thread. It has to stay allocated for the lifetime of the thread (default: NULL) 00083 00084 @note You cannot call this function from ISR context. 00085 */ 00086 Thread(osPriority priority=osPriorityNormal, 00087 uint32_t stack_size=OS_STACK_SIZE, 00088 unsigned char *stack_mem=NULL, const char *name=NULL) { 00089 constructor(priority, stack_size, stack_mem, name); 00090 } 00091 00092 /** Create a new thread, and start it executing the specified function. 00093 @param task function to be executed by this thread. 00094 @param priority initial priority of the thread function. (default: osPriorityNormal). 00095 @param stack_size stack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE). 00096 @param stack_mem pointer to the stack area to be used by this thread (default: NULL). 00097 @deprecated 00098 Thread-spawning constructors hide errors. Replaced by thread.start(task). 00099 00100 @code 00101 Thread thread(priority, stack_size, stack_mem); 00102 00103 osStatus status = thread.start(task); 00104 if (status != osOK) { 00105 error("oh no!"); 00106 } 00107 @endcode 00108 00109 @note You cannot call this function from ISR context. 00110 */ 00111 MBED_DEPRECATED_SINCE("mbed-os-5.1", 00112 "Thread-spawning constructors hide errors. " 00113 "Replaced by thread.start(task).") 00114 Thread(mbed::Callback<void()> task, 00115 osPriority priority=osPriorityNormal, 00116 uint32_t stack_size=OS_STACK_SIZE, 00117 unsigned char *stack_mem=NULL) { 00118 constructor(task, priority, stack_size, stack_mem); 00119 } 00120 00121 /** Create a new thread, and start it executing the specified function. 00122 @param argument pointer that is passed to the thread function as start argument. (default: NULL). 00123 @param task argument to task. 00124 @param priority initial priority of the thread function. (default: osPriorityNormal). 00125 @param stack_size stack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE). 00126 @param stack_mem pointer to the stack area to be used by this thread (default: NULL). 00127 @deprecated 00128 Thread-spawning constructors hide errors. Replaced by thread.start(callback(task, argument)). 00129 00130 @code 00131 Thread thread(priority, stack_size, stack_mem); 00132 00133 osStatus status = thread.start(callback(task, argument)); 00134 if (status != osOK) { 00135 error("oh no!"); 00136 } 00137 @endcode 00138 00139 @note You cannot call this function from ISR context. 00140 */ 00141 template <typename T> 00142 MBED_DEPRECATED_SINCE("mbed-os-5.1", 00143 "Thread-spawning constructors hide errors. " 00144 "Replaced by thread.start(callback(task, argument)).") 00145 Thread(T *argument, void (T::*task)(), 00146 osPriority priority=osPriorityNormal, 00147 uint32_t stack_size=OS_STACK_SIZE, 00148 unsigned char *stack_mem=NULL) { 00149 constructor(mbed::callback(task, argument), 00150 priority, stack_size, stack_mem); 00151 } 00152 00153 /** Create a new thread, and start it executing the specified function. 00154 @param argument pointer that is passed to the thread function as start argument. (default: NULL). 00155 @param task argument to task. 00156 @param priority initial priority of the thread function. (default: osPriorityNormal). 00157 @param stack_size stack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE). 00158 @param stack_mem pointer to the stack area to be used by this thread (default: NULL). 00159 @deprecated 00160 Thread-spawning constructors hide errors. Replaced by thread.start(callback(task, argument)). 00161 00162 @code 00163 Thread thread(priority, stack_size, stack_mem); 00164 00165 osStatus status = thread.start(callback(task, argument)); 00166 if (status != osOK) { 00167 error("oh no!"); 00168 } 00169 @endcode 00170 00171 @note You cannot call this function from ISR context. 00172 */ 00173 template <typename T> 00174 MBED_DEPRECATED_SINCE("mbed-os-5.1", 00175 "Thread-spawning constructors hide errors. " 00176 "Replaced by thread.start(callback(task, argument)).") 00177 Thread(T *argument, void (*task)(T *), 00178 osPriority priority=osPriorityNormal, 00179 uint32_t stack_size=OS_STACK_SIZE, 00180 unsigned char *stack_mem=NULL) { 00181 constructor(mbed::callback(task, argument), 00182 priority, stack_size, stack_mem); 00183 } 00184 00185 /** Create a new thread, and start it executing the specified function. 00186 Provided for backwards compatibility 00187 @param task function to be executed by this thread. 00188 @param argument pointer that is passed to the thread function as start argument. (default: NULL). 00189 @param priority initial priority of the thread function. (default: osPriorityNormal). 00190 @param stack_size stack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE). 00191 @param stack_mem pointer to the stack area to be used by this thread (default: NULL). 00192 @deprecated 00193 Thread-spawning constructors hide errors. Replaced by thread.start(callback(task, argument)). 00194 00195 @code 00196 Thread thread(priority, stack_size, stack_mem); 00197 00198 osStatus status = thread.start(callback(task, argument)); 00199 if (status != osOK) { 00200 error("oh no!"); 00201 } 00202 @endcode 00203 00204 @note You cannot call this function from ISR context. 00205 */ 00206 MBED_DEPRECATED_SINCE("mbed-os-5.1", 00207 "Thread-spawning constructors hide errors. " 00208 "Replaced by thread.start(callback(task, argument)).") 00209 Thread(void (*task)(void const *argument), void *argument=NULL, 00210 osPriority priority=osPriorityNormal, 00211 uint32_t stack_size=OS_STACK_SIZE, 00212 unsigned char *stack_mem=NULL) { 00213 constructor(mbed::callback((void (*)(void *))task, argument), 00214 priority, stack_size, stack_mem); 00215 } 00216 00217 /** Starts a thread executing the specified function. 00218 @param task function to be executed by this thread. 00219 @return status code that indicates the execution status of the function. 00220 @note a thread can only be started once 00221 00222 @note You cannot call this function ISR context. 00223 */ 00224 osStatus start(mbed::Callback<void()> task); 00225 00226 /** Starts a thread executing the specified function. 00227 @param obj argument to task 00228 @param method function to be executed by this thread. 00229 @return status code that indicates the execution status of the function. 00230 @deprecated 00231 The start function does not support cv-qualifiers. Replaced by start(callback(obj, method)). 00232 00233 @note You cannot call this function from ISR context. 00234 */ 00235 template <typename T, typename M> 00236 MBED_DEPRECATED_SINCE("mbed-os-5.1", 00237 "The start function does not support cv-qualifiers. " 00238 "Replaced by thread.start(callback(obj, method)).") 00239 osStatus start(T *obj, M method) { 00240 return start(mbed::callback(obj, method)); 00241 } 00242 00243 /** Wait for thread to terminate 00244 @return status code that indicates the execution status of the function. 00245 @note not callable from interrupt 00246 00247 @note You cannot call this function from ISR context. 00248 */ 00249 osStatus join(); 00250 00251 /** Terminate execution of a thread and remove it from Active Threads 00252 @return status code that indicates the execution status of the function. 00253 00254 @note You cannot call this function from ISR context. 00255 */ 00256 osStatus terminate(); 00257 00258 /** Set priority of an active thread 00259 @param priority new priority value for the thread function. 00260 @return status code that indicates the execution status of the function. 00261 00262 @note You cannot call this function from ISR context. 00263 */ 00264 osStatus set_priority(osPriority priority); 00265 00266 /** Get priority of an active thread 00267 @return current priority value of the thread function. 00268 00269 @note You cannot call this function from ISR context. 00270 */ 00271 osPriority get_priority(); 00272 00273 /** Set the specified Thread Flags for the thread. 00274 @param signals specifies the signal flags of the thread that should be set. 00275 @return signal flags after setting or osFlagsError in case of incorrect parameters. 00276 00277 @note You may call this function from ISR context. 00278 */ 00279 int32_t signal_set(int32_t signals); 00280 00281 /** State of the Thread */ 00282 enum State { 00283 Inactive, /**< NOT USED */ 00284 Ready, /**< Ready to run */ 00285 Running, /**< Running */ 00286 WaitingDelay, /**< Waiting for a delay to occur */ 00287 WaitingJoin, /**< Waiting for thread to join. Only happens when using RTX directly. */ 00288 WaitingThreadFlag, /**< Waiting for a thread flag to be set */ 00289 WaitingEventFlag, /**< Waiting for a event flag to be set */ 00290 WaitingMutex, /**< Waiting for a mutex event to occur */ 00291 WaitingSemaphore, /**< Waiting for a semaphore event to occur */ 00292 WaitingMemoryPool, /**< Waiting for a memory pool */ 00293 WaitingMessageGet, /**< Waiting for message to arrive */ 00294 WaitingMessagePut, /**< Waiting for message to be send */ 00295 WaitingInterval, /**< NOT USED */ 00296 WaitingOr, /**< NOT USED */ 00297 WaitingAnd, /**< NOT USED */ 00298 WaitingMailbox, /**< NOT USED (Mail is implemented as MemoryPool and Queue) */ 00299 00300 /* Not in sync with RTX below here */ 00301 Deleted, /**< The task has been deleted or not started */ 00302 }; 00303 00304 /** State of this Thread 00305 @return the State of this Thread 00306 00307 @note You cannot call this function from ISR context. 00308 */ 00309 State get_state(); 00310 00311 /** Get the total stack memory size for this Thread 00312 @return the total stack memory size in bytes 00313 00314 @note You cannot call this function from ISR context. 00315 */ 00316 uint32_t stack_size(); 00317 00318 /** Get the currently unused stack memory for this Thread 00319 @return the currently unused stack memory in bytes 00320 00321 @note You cannot call this function from ISR context. 00322 */ 00323 uint32_t free_stack(); 00324 00325 /** Get the currently used stack memory for this Thread 00326 @return the currently used stack memory in bytes 00327 00328 @note You cannot call this function from ISR context. 00329 */ 00330 uint32_t used_stack(); 00331 00332 /** Get the maximum stack memory usage to date for this Thread 00333 @return the maximum stack memory usage to date in bytes 00334 00335 @note You cannot call this function from ISR context. 00336 */ 00337 uint32_t max_stack(); 00338 00339 /** Get thread name 00340 @return thread name or NULL if the name was not set. 00341 00342 @note You may call this function from ISR context. 00343 */ 00344 const char *get_name(); 00345 00346 /** Clears the specified Thread Flags of the currently running thread. 00347 @param signals specifies the signal flags of the thread that should be cleared. 00348 @return signal flags before clearing or osFlagsError in case of incorrect parameters. 00349 00350 @note You cannot call this function from ISR context. 00351 */ 00352 static int32_t signal_clr(int32_t signals); 00353 00354 /** Wait for one or more Thread Flags to become signaled for the current RUNNING thread. 00355 @param signals wait until all specified signal flags are set or 0 for any single signal flag. 00356 @param millisec timeout value or 0 in case of no time-out. (default: osWaitForever). 00357 @return event flag information or error code. @note if @a millisec is set to 0 and flag is no set the event carries osOK value. 00358 00359 @note You cannot call this function from ISR context. 00360 */ 00361 static osEvent signal_wait(int32_t signals, uint32_t millisec=osWaitForever); 00362 00363 /** Wait for a specified time period in milliseconds 00364 Being tick-based, the delay will be up to the specified time - eg for 00365 a value of 1 the system waits until the next millisecond tick occurs, 00366 leading to a delay of 0-1 milliseconds. 00367 @param millisec time delay value 00368 @return status code that indicates the execution status of the function. 00369 00370 @note You cannot call this function from ISR context. 00371 */ 00372 static osStatus wait(uint32_t millisec); 00373 00374 /** Wait until a specified time in millisec 00375 The specified time is according to Kernel::get_ms_count(). 00376 @param millisec absolute time in millisec 00377 @return status code that indicates the execution status of the function. 00378 @note not callable from interrupt 00379 @note if millisec is equal to or lower than the current tick count, this 00380 returns immediately, either with an error or "osOK". 00381 @note the underlying RTOS may have a limit to the maximum wait time 00382 due to internal 32-bit computations, but this is guaranteed to work if the 00383 delay is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded, 00384 it may return with an immediate error, or wait for the maximum delay. 00385 00386 @note You cannot call this function from ISR context. 00387 */ 00388 static osStatus wait_until(uint64_t millisec); 00389 00390 /** Pass control to next thread that is in state READY. 00391 @return status code that indicates the execution status of the function. 00392 00393 @note You cannot call this function from ISR context. 00394 */ 00395 static osStatus yield(); 00396 00397 /** Get the thread id of the current running thread. 00398 @return thread ID for reference by other functions or NULL in case of error. 00399 00400 @note You may call this function from ISR context. 00401 */ 00402 static osThreadId gettid(); 00403 00404 /** Attach a function to be called by the RTOS idle task 00405 @param fptr pointer to the function to be called 00406 00407 @note You may call this function from ISR context. 00408 */ 00409 static void attach_idle_hook(void (*fptr)(void)); 00410 00411 /** Attach a function to be called when a task is killed 00412 @param fptr pointer to the function to be called 00413 00414 @note You may call this function from ISR context. 00415 */ 00416 static void attach_terminate_hook(void (*fptr)(osThreadId id)); 00417 00418 /** Thread destructor 00419 * 00420 * @note You cannot call this function from ISR context. 00421 */ 00422 virtual ~Thread(); 00423 00424 private: 00425 // Required to share definitions without 00426 // delegated constructors 00427 void constructor(osPriority priority=osPriorityNormal, 00428 uint32_t stack_size=OS_STACK_SIZE, 00429 unsigned char *stack_mem=NULL, 00430 const char *name=NULL); 00431 void constructor(mbed::Callback<void()> task, 00432 osPriority priority=osPriorityNormal, 00433 uint32_t stack_size=OS_STACK_SIZE, 00434 unsigned char *stack_mem=NULL, 00435 const char *name=NULL); 00436 static void _thunk(void * thread_ptr); 00437 00438 mbed::Callback<void()> _task; 00439 osThreadId_t _tid; 00440 osThreadAttr_t _attr; 00441 bool _dynamic_stack; 00442 Semaphore _join_sem; 00443 Mutex _mutex; 00444 mbed_rtos_storage_thread_t _obj_mem; 00445 bool _finished; 00446 }; 00447 /** @}*/ 00448 /** @}*/ 00449 } 00450 #endif 00451 00452
Generated on Tue Jul 12 2022 13:25:15 by
1.7.2