ThisThread.h

00001 /* mbed Microcontroller Library
00002  * Copyright (c) 2006-2018 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 THIS_THREAD_H
00023 #define THIS_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_ThisThread ThisThread namespace
00040  * @{
00041  */
00042 
00043 /** The ThisThread namespace allows controlling the current thread.
00044  *
00045  *  Example:
00046  *  @code
00047  *  #include "mbed.h"
00048  *  #include "rtos.h"
00049  *
00050  *  Thread thread;
00051  *  DigitalOut led1(LED1);
00052  *
00053  *  #define STOP_FLAG 1
00054  *
00055  *  // Blink function toggles the led in a long running loop
00056  *  void blink(DigitalOut *led) {
00057  *      while (!ThisThread::flags_wait_any_for(STOP_FLAG, 1000)) {
00058  *          *led = !*led;
00059  *      }
00060  *  }
00061  *
00062  *  // Spawns a thread to run blink for 5 seconds
00063  *  int main() {
00064  *      thread.start(callback(blink, &led1));
00065  *      ThisThread::sleep_for(5000);
00066  *      thread.signal_set(STOP_FLAG);
00067  *      thread.join();
00068  *  }
00069  *  @endcode
00070  *
00071  */
00072 namespace ThisThread {
00073 /** Clears the specified Thread Flags of the currently running thread.
00074   @param   flags  specifies the flags of the thread that should be cleared.
00075   @return  thread flags before clearing.
00076   @note You cannot call this function from ISR context.
00077   @see Thread::flags_set
00078 */
00079 uint32_t flags_clear(uint32_t flags);
00080 
00081 /** Returns the Thread Flags currently set for the currently running thread.
00082   @return  current thread flags or 0 if not in a valid thread.
00083   @note You cannot call this function from ISR context.
00084   @see Thread::flags_set
00085 */
00086 uint32_t flags_get();
00087 
00088 /** Wait for all of the specified Thread Flags to become signaled for the current thread.
00089   @param   flags     specifies the flags to wait for
00090   @param   clear     whether to clear the specified flags after waiting for them. (default: true)
00091   @return  actual thread flags before clearing, which will satisfy the wait
00092   @note You cannot call this function from ISR context.
00093   @see Thread::flags_set
00094 */
00095 uint32_t flags_wait_all(uint32_t flags, bool clear = true);
00096 
00097 /** Wait for any of the specified Thread Flags to become signaled for the current thread.
00098   @param   flags     specifies the flags to wait for
00099   @param   clear     whether to clear the specified flags after waiting for them. (default: true)
00100   @return  actual thread flags before clearing, which will satisfy the wait
00101   @note You cannot call this function from ISR context.
00102   @see Thread::flags_set
00103 */
00104 uint32_t flags_wait_any(uint32_t flags, bool clear = true);
00105 
00106 /** Wait for all of the specified Thread Flags to become signaled for the current thread.
00107   @param   flags     specifies the flags to wait for
00108   @param   millisec  timeout value or 0 in case of no time-out.
00109   @param   clear     whether to clear the specified flags after waiting for them. (default: true)
00110   @return  actual thread flags before clearing, which may not satisfy the wait
00111   @note You cannot call this function from ISR context.
00112   @see Thread::flags_set
00113 */
00114 uint32_t flags_wait_all_for(uint32_t flags, uint32_t millisec, bool clear = true);
00115 
00116 /** Wait for all of the specified Thread Flags to become signaled for the current thread.
00117   @param   flags     specifies the flags to wait for
00118   @param   millisec  absolute timeout time, referenced to Kernel::get_ms_count()
00119   @param   clear     whether to clear the specified flags after waiting for them. (default: true)
00120   @return  actual thread flags before clearing, which may not satisfy the wait
00121   @note You cannot call this function from ISR context.
00122   @note the underlying RTOS may have a limit to the maximum wait time
00123         due to internal 32-bit computations, but this is guaranteed to work if the
00124         wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
00125         the wait will time out earlier than specified.
00126   @see Thread::flags_set
00127 */
00128 uint32_t flags_wait_all_until(uint32_t flags, uint64_t millisec, bool clear = true);
00129 
00130 /** Wait for any of the specified Thread Flags to become signaled for the current thread.
00131   @param   flags     specifies the flags to wait for
00132   @param   millisec  timeout value or 0 in case of no time-out.
00133   @param   clear     whether to clear the specified flags after waiting for them. (default: true)
00134   @return  actual thread flags before clearing, which may not satisfy the wait
00135   @note You cannot call this function from ISR context.
00136   @see Thread::flags_set
00137 */
00138 uint32_t flags_wait_any_for(uint32_t flags, uint32_t millisec, bool clear = true);
00139 
00140 /** Wait for any of the specified Thread Flags to become signaled for the current thread.
00141   @param   flags     specifies the flags to wait for
00142   @param   millisec  absolute timeout time, referenced to Kernel::get_ms_count()
00143   @param   clear     whether to clear the specified flags after waiting for them. (default: true)
00144   @return  actual thread flags before clearing, which may not satisfy the wait
00145   @note You cannot call this function from ISR context.
00146   @note the underlying RTOS may have a limit to the maximum wait time
00147         due to internal 32-bit computations, but this is guaranteed to work if the
00148           wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
00149           the wait will time out earlier than specified.
00150   @see Thread::flags_set
00151 */
00152 uint32_t flags_wait_any_until(uint32_t flags, uint64_t millisec, bool clear = true);
00153 
00154 /** Sleep for a specified time period in millisec:
00155   @param   millisec  time delay value
00156   @note You cannot call this function from ISR context.
00157 */
00158 void sleep_for(uint32_t millisec);
00159 
00160 /** Sleep until a specified time in millisec
00161   The specified time is according to Kernel::get_ms_count().
00162   @param   millisec absolute time in millisec
00163   @note You cannot call this function from ISR context.
00164   @note if millisec is equal to or lower than the current tick count, this
00165         returns immediately.
00166 */
00167 void sleep_until(uint64_t millisec);
00168 
00169 /** Pass control to next equal-priority thread that is in state READY.
00170     (Higher-priority READY threads would prevent us from running; this
00171     will not enable lower-priority threads to run, as we remain READY).
00172     @note You cannot call this function from ISR context.
00173 */
00174 void yield();
00175 
00176 /** Get the thread id of the current running thread.
00177   @return  thread ID for reference by other functions or NULL in case of error or in ISR context.
00178   @note You may call this function from ISR context.
00179 */
00180 osThreadId_t get_id();
00181 
00182 };
00183 /** @}*/
00184 /** @}*/
00185 }
00186 #endif
00187 
00188