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