Mistake on this page?
Report an issue in GitHub or email us
ThisThread.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2006-2019 ARM Limited
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a copy
5  * of this software and associated documentation files (the "Software"), to deal
6  * in the Software without restriction, including without limitation the rights
7  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8  * copies of the Software, and to permit persons to whom the Software is
9  * furnished to do so, subject to the following conditions:
10  *
11  * The above copyright notice and this permission notice shall be included in
12  * all copies or substantial portions of the Software.
13  *
14  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20  * SOFTWARE.
21  */
22 #ifndef THIS_THREAD_H
23 #define THIS_THREAD_H
24 
25 #include <stdint.h>
26 #include "rtos/mbed_rtos_types.h"
27 
28 namespace rtos {
29 /** \addtogroup rtos-public-api */
30 /** @{*/
31 
32 /**
33  * \defgroup rtos_ThisThread ThisThread namespace
34  * @{
35  */
36 
37 /** The ThisThread namespace allows controlling the current thread.
38  *
39  * Example:
40  * @code
41  * #include "mbed.h"
42  * #include "rtos.h"
43  *
44  * Thread thread;
45  * DigitalOut led1(LED1);
46  *
47  * #define STOP_FLAG 1
48  *
49  * // Blink function toggles the led in a long running loop
50  * void blink(DigitalOut *led) {
51  * while (!ThisThread::flags_wait_any_for(STOP_FLAG, 1000)) {
52  * *led = !*led;
53  * }
54  * }
55  *
56  * // Spawns a thread to run blink for 5 seconds
57  * int main() {
58  * thread.start(callback(blink, &led1));
59  * ThisThread::sleep_for(5000);
60  * thread.signal_set(STOP_FLAG);
61  * thread.join();
62  * }
63  * @endcode
64  *
65  */
66 namespace ThisThread {
67 /** Clears the specified Thread Flags of the currently running thread.
68  @param flags specifies the flags of the thread that should be cleared.
69  @return thread flags before clearing.
70  @note You cannot call this function from ISR context.
71  @see Thread::flags_set
72 */
73 uint32_t flags_clear(uint32_t flags);
74 
75 /** Returns the Thread Flags currently set for the currently running thread.
76  @return current thread flags or 0 if not in a valid thread.
77  @note You cannot call this function from ISR context.
78  @see Thread::flags_set
79 */
80 uint32_t flags_get();
81 
82 /** Wait for all of the specified Thread Flags to become signaled for the current thread.
83  @param flags specifies the flags to wait for
84  @param clear whether to clear the specified flags after waiting for them. (default: true)
85  @return actual thread flags before clearing, which will satisfy the wait
86  @note You cannot call this function from ISR context.
87  @see Thread::flags_set
88 */
89 uint32_t flags_wait_all(uint32_t flags, bool clear = true);
90 
91 /** Wait for any of the specified Thread Flags to become signaled for the current thread.
92  @param flags specifies the flags to wait for
93  @param clear whether to clear the specified flags after waiting for them. (default: true)
94  @return actual thread flags before clearing, which will satisfy the wait
95  @note You cannot call this function from ISR context.
96  @see Thread::flags_set
97 */
98 uint32_t flags_wait_any(uint32_t flags, bool clear = true);
99 
100 /** Wait for all of the specified Thread Flags to become signaled for the current thread.
101  @param flags specifies the flags to wait for
102  @param millisec timeout value.
103  @param clear whether to clear the specified flags after waiting for them. (default: true)
104  @return actual thread flags before clearing, which may not satisfy the wait
105  @note You cannot call this function from ISR context.
106  @see Thread::flags_set
107 */
108 uint32_t flags_wait_all_for(uint32_t flags, uint32_t millisec, bool clear = true);
109 
110 /** Wait for all of the specified Thread Flags to become signaled for the current thread.
111  @param flags specifies the flags to wait for
112  @param millisec absolute timeout time, referenced to Kernel::get_ms_count()
113  @param clear whether to clear the specified flags after waiting for them. (default: true)
114  @return actual thread flags before clearing, which may not satisfy the wait
115  @note You cannot call this function from ISR context.
116  @note the underlying RTOS may have a limit to the maximum wait time
117  due to internal 32-bit computations, but this is guaranteed to work if the
118  wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
119  the wait will time out earlier than specified.
120  @see Thread::flags_set
121 */
122 uint32_t flags_wait_all_until(uint32_t flags, uint64_t millisec, bool clear = true);
123 
124 /** Wait for any of the specified Thread Flags to become signaled for the current thread.
125  @param flags specifies the flags to wait for
126  @param millisec timeout value.
127  @param clear whether to clear the specified flags after waiting for them. (default: true)
128  @return actual thread flags before clearing, which may not satisfy the wait
129  @note You cannot call this function from ISR context.
130  @see Thread::flags_set
131 */
132 uint32_t flags_wait_any_for(uint32_t flags, uint32_t millisec, bool clear = true);
133 
134 /** Wait for any of the specified Thread Flags to become signaled for the current thread.
135  @param flags specifies the flags to wait for
136  @param millisec absolute timeout time, referenced to Kernel::get_ms_count()
137  @param clear whether to clear the specified flags after waiting for them. (default: true)
138  @return actual thread flags before clearing, which may not satisfy the wait
139  @note You cannot call this function from ISR context.
140  @note the underlying RTOS may have a limit to the maximum wait time
141  due to internal 32-bit computations, but this is guaranteed to work if the
142  wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
143  the wait will time out earlier than specified.
144  @see Thread::flags_set
145 */
146 uint32_t flags_wait_any_until(uint32_t flags, uint64_t millisec, bool clear = true);
147 
148 /** Sleep for a specified time period in millisec:
149  @param millisec time delay value
150  @note You cannot call this function from ISR context.
151  @note The equivalent functionality is accessible in C via thread_sleep_for.
152 */
153 void sleep_for(uint32_t millisec);
154 
155 /** Sleep until a specified time in millisec
156  The specified time is according to Kernel::get_ms_count().
157  @param millisec absolute time in millisec
158  @note You cannot call this function from ISR context.
159  @note if millisec is equal to or lower than the current tick count, this
160  returns immediately.
161  @note The equivalent functionality is accessible in C via thread_sleep_until.
162 */
163 void sleep_until(uint64_t millisec);
164 
165 /** Pass control to next equal-priority thread that is in state READY.
166  (Higher-priority READY threads would prevent us from running; this
167  will not enable lower-priority threads to run, as we remain READY).
168  @note You cannot call this function from ISR context.
169 */
170 void yield();
171 
172 /** Get the thread id of the current running thread.
173  @return thread ID for reference by other functions or nullptr in case of error or in ISR context.
174  @note You may call this function from ISR context.
175 */
176 osThreadId_t get_id();
177 
178 /** Get the thread name of the current running thread.
179  @return thread name pointer or nullptr if thread has no name or in case of error.
180  @note You cannot call this function from ISR context.
181 */
182 const char *get_name();
183 
184 };
185 /** @}*/
186 /** @}*/
187 
188 
189 namespace internal {
190 /** \addtogroup rtos-internal-api */
191 /** @{*/
192 
194  uint32_t *flags;
195  uint32_t options;
196  uint32_t flags_wanted;
197  uint32_t result;
198  bool match;
199 };
200 
201 bool non_rtos_check_flags(void *handle);
202 
203 }
204 /** @}*/
205 }
206 #endif
uint32_t flags_wait_all_until(uint32_t flags, uint64_t millisec, bool clear=true)
Wait for all of the specified Thread Flags to become signaled for the current thread.
uint32_t flags_clear(uint32_t flags)
Clears the specified Thread Flags of the currently running thread.
osThreadId_t get_id()
Get the thread id of the current running thread.
uint32_t flags_get()
Returns the Thread Flags currently set for the currently running thread.
uint32_t flags_wait_any_for(uint32_t flags, uint32_t millisec, bool clear=true)
Wait for any of the specified Thread Flags to become signaled for the current thread.
uint32_t flags_wait_all_for(uint32_t flags, uint32_t millisec, bool clear=true)
Wait for all of the specified Thread Flags to become signaled for the current thread.
uint32_t flags_wait_any(uint32_t flags, bool clear=true)
Wait for any of the specified Thread Flags to become signaled for the current thread.
void sleep_until(uint64_t millisec)
Sleep until a specified time in millisec The specified time is according to Kernel::get_ms_count().
uint32_t flags_wait_any_until(uint32_t flags, uint64_t millisec, bool clear=true)
Wait for any of the specified Thread Flags to become signaled for the current thread.
void yield()
Pass control to next equal-priority thread that is in state READY.
const char * get_name()
Get the thread name of the current running thread.
Definition: TaskBase.h:25
void sleep_for(uint32_t millisec)
Sleep for a specified time period in millisec:
uint32_t flags_wait_all(uint32_t flags, bool clear=true)
Wait for all of the specified Thread Flags to become signaled for the current thread.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.