Ok

Dependencies:   mbed_rtos_types Mutex mbed_rtos_storage mbed Semaphore

Embed: (wiki syntax)

« Back to documentation index

Show/hide line numbers ThisThread.h Source File

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