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  * SPDX-License-Identifier: MIT
4  *
5  * Permission is hereby granted, free of charge, to any person obtaining a copy
6  * of this software and associated documentation files (the "Software"), to deal
7  * in the Software without restriction, including without limitation the rights
8  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9  * copies of the Software, and to permit persons to whom the Software is
10  * furnished to do so, subject to the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included in
13  * all copies or substantial portions of the Software.
14  *
15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21  * SOFTWARE.
22  */
23 #ifndef THIS_THREAD_H
24 #define THIS_THREAD_H
25 
26 #include <stdint.h>
27 #include "platform/mbed_toolchain.h"
28 #include "rtos/Kernel.h"
29 #include "rtos/mbed_rtos_types.h"
30 
31 namespace rtos {
32 /** \addtogroup rtos-public-api */
33 /** @{*/
34 
35 /**
36  * \defgroup rtos_ThisThread ThisThread namespace
37  * @{
38  */
39 
40 /** The ThisThread namespace allows controlling the current thread.
41  *
42  * Example:
43  * @code
44  * #include "mbed.h"
45  * #include "rtos.h"
46  *
47  * Thread thread;
48  * DigitalOut led1(LED1);
49  *
50  * #define STOP_FLAG 1
51  *
52  * // Blink function toggles the led in a long running loop
53  * void blink(DigitalOut *led) {
54  * while (!ThisThread::flags_wait_any_for(STOP_FLAG, 1000)) {
55  * *led = !*led;
56  * }
57  * }
58  *
59  * // Spawns a thread to run blink for 5 seconds
60  * int main() {
61  * thread.start(callback(blink, &led1));
62  * ThisThread::sleep_for(5000);
63  * thread.signal_set(STOP_FLAG);
64  * thread.join();
65  * }
66  * @endcode
67  *
68  */
69 namespace ThisThread {
70 /** Clears the specified Thread Flags of the currently running thread.
71  @param flags specifies the flags of the thread that should be cleared.
72  @return thread flags before clearing.
73  @note You cannot call this function from ISR context.
74  @see Thread::flags_set
75 */
76 uint32_t flags_clear(uint32_t flags);
77 
78 /** Returns the Thread Flags currently set for the currently running thread.
79  @return current thread flags or 0 if not in a valid thread.
80  @note You cannot call this function from ISR context.
81  @see Thread::flags_set
82 */
83 uint32_t flags_get();
84 
85 /** Wait for all of the specified Thread Flags to become signaled for the current thread.
86  @param flags specifies the flags to wait for
87  @param clear whether to clear the specified flags after waiting for them. (default: true)
88  @return actual thread flags before clearing, which will satisfy the wait
89  @note You cannot call this function from ISR context.
90  @see Thread::flags_set
91 */
92 uint32_t flags_wait_all(uint32_t flags, bool clear = true);
93 
94 /** Wait for any of the specified Thread Flags to become signaled for the current thread.
95  @param flags specifies the flags to wait for
96  @param clear whether to clear the specified flags after waiting for them. (default: true)
97  @return actual thread flags before clearing, which will satisfy the wait
98  @note You cannot call this function from ISR context.
99  @see Thread::flags_set
100 */
101 uint32_t flags_wait_any(uint32_t flags, bool clear = true);
102 
103 /** Wait for all of the specified Thread Flags to become signaled for the current thread.
104  @param flags specifies the flags to wait for
105  @param millisec timeout value.
106  @param clear whether to clear the specified flags after waiting for them. (default: true)
107  @return actual thread flags before clearing, which may not satisfy the wait
108  @note You cannot call this function from ISR context.
109  @see Thread::flags_set
110  @deprecated Pass a chrono duration, not an integer millisecond count. For example use `5s` rather than `5000`.
111 */
112 MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono duration, not an integer millisecond count. For example use `5s` rather than `5000`.")
113 uint32_t flags_wait_all_for(uint32_t flags, uint32_t millisec, bool clear = true);
114 
115 /** Wait for all of the specified Thread Flags to become signaled for the current thread.
116  @param flags specifies the flags to wait for
117  @param rel_time timeout value.
118  @param clear whether to clear the specified flags after waiting for them. (default: true)
119  @return actual thread flags before clearing, which may not satisfy the wait
120  @note You cannot call this function from ISR context.
121  @see Thread::flags_set
122 */
123 uint32_t flags_wait_all_for(uint32_t flags, Kernel::Clock::duration_u32 rel_time, bool clear = true);
124 
125 /** Wait for all of the specified Thread Flags to become signaled for the current thread.
126  @param flags specifies the flags to wait for
127  @param millisec absolute timeout time, referenced to Kernel::get_ms_count()
128  @param clear whether to clear the specified flags after waiting for them. (default: true)
129  @return actual thread flags before clearing, which may not satisfy the wait
130  @note You cannot call this function from ISR context.
131  @note the underlying RTOS may have a limit to the maximum wait time
132  due to internal 32-bit computations, but this is guaranteed to work if the
133  wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
134  the wait will time out earlier than specified.
135  @see Thread::flags_set
136  @deprecated Pass a chrono time_point, not an integer millisecond count. For example use `Kernel::Clock::now() + 5s`
137  rather than `Kernel::get_ms_count() + 5000`.
138 */
139 MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono time_point, not an integer millisecond count. For example use `Kernel::Clock::now() + 5s` rather than `Kernel::get_ms_count() + 5000`.")
140 uint32_t flags_wait_all_until(uint32_t flags, uint64_t millisec, bool clear = true);
141 
142 /** Wait for all of the specified Thread Flags to become signaled for the current thread.
143  @param flags specifies the flags to wait for
144  @param abs_time absolute timeout time, referenced to Kernel::Clock
145  @param clear whether to clear the specified flags after waiting for them. (default: true)
146  @return actual thread flags before clearing, which may not satisfy the wait
147  @note You cannot call this function from ISR context.
148  @note the underlying RTOS may have a limit to the maximum wait time
149  due to internal 32-bit computations, but this is guaranteed to work if the
150  wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
151  the wait will time out earlier than specified.
152  @see Thread::flags_set
153 */
154 uint32_t flags_wait_all_until(uint32_t flags, Kernel::Clock::time_point abs_time, bool clear = true);
155 
156 /** Wait for any of the specified Thread Flags to become signaled for the current thread.
157  @param flags specifies the flags to wait for
158  @param millisec timeout value.
159  @param clear whether to clear the specified flags after waiting for them. (default: true)
160  @return actual thread flags before clearing, which may not satisfy the wait
161  @note You cannot call this function from ISR context.
162  @see Thread::flags_set
163  @deprecated Pass a chrono duration, not an integer millisecond count. For example use `5s` rather than `5000`.
164 */
165 MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono duration, not an integer millisecond count. For example use `5s` rather than `5000`.")
166 uint32_t flags_wait_any_for(uint32_t flags, uint32_t millisec, bool clear = true);
167 
168 /** Wait for any of the specified Thread Flags to become signaled for the current thread.
169  @param flags specifies the flags to wait for
170  @param rel_time timeout value.
171  @param clear whether to clear the specified flags after waiting for them. (default: true)
172  @return actual thread flags before clearing, which may not satisfy the wait
173  @note You cannot call this function from ISR context.
174  @see Thread::flags_set
175 */
176 uint32_t flags_wait_any_for(uint32_t flags, Kernel::Clock::duration_u32 rel_time, bool clear = true);
177 
178 /** Wait for any of the specified Thread Flags to become signaled for the current thread.
179  @param flags specifies the flags to wait for
180  @param millisec absolute timeout time, referenced to Kernel::get_ms_count()
181  @param clear whether to clear the specified flags after waiting for them. (default: true)
182  @return actual thread flags before clearing, which may not satisfy the wait
183  @note You cannot call this function from ISR context.
184  @note the underlying RTOS may have a limit to the maximum wait time
185  due to internal 32-bit computations, but this is guaranteed to work if the
186  wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
187  the wait will time out earlier than specified.
188  @see Thread::flags_set
189  @deprecated Pass a chrono time_point, not an integer millisecond count. For example use `Kernel::Clock::now() + 5s`
190  rather than `Kernel::get_ms_count() + 5000`.
191 */
192 MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono time_point, not an integer millisecond count. For example use `Kernel::Clock::now() + 5s` rather than `Kernel::get_ms_count() + 5000`.")
193 uint32_t flags_wait_any_until(uint32_t flags, uint64_t millisec, bool clear = true);
194 
195 /** Wait for any of the specified Thread Flags to become signaled for the current thread.
196  @param flags specifies the flags to wait for
197  @param abs_time absolute timeout time, referenced to Kernel::Clock
198  @param clear whether to clear the specified flags after waiting for them. (default: true)
199  @return actual thread flags before clearing, which may not satisfy the wait
200  @note You cannot call this function from ISR context.
201  @note the underlying RTOS may have a limit to the maximum wait time
202  due to internal 32-bit computations, but this is guaranteed to work if the
203  wait is <= 0x7fffffff milliseconds (~24 days). If the limit is exceeded,
204  the wait will time out earlier than specified.
205  @see Thread::flags_set
206 */
207 uint32_t flags_wait_any_until(uint32_t flags, Kernel::Clock::time_point abs_time, bool clear = true);
208 
209 /** Sleep for a specified time period in millisec:
210  @param millisec time delay value
211  @note You cannot call this function from ISR context.
212  @note The equivalent functionality is accessible in C via thread_sleep_for.
213  @deprecated Pass a chrono duration, not an integer millisecond count. For example use `5s` rather than `5000`.
214 */
215 MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono duration, not an integer millisecond count. For example use `5s` rather than `5000`.")
216 void sleep_for(uint32_t millisec);
217 
218 /** Sleep for a specified time period:
219  @param rel_time time delay value
220  @note You cannot call this function from ISR context.
221  @note The equivalent functionality is accessible in C via thread_sleep_for.
222 */
223 void sleep_for(Kernel::Clock::duration_u32 rel_time);
224 
225 
226 /** Sleep until a specified time in millisec
227  The specified time is according to Kernel::get_ms_count().
228  @param millisec absolute time in millisec
229  @note You cannot call this function from ISR context.
230  @note if millisec is equal to or lower than the current tick count, this
231  returns immediately.
232  @note The equivalent functionality is accessible in C via thread_sleep_until.
233  @deprecated Pass a chrono time_point, not an integer millisecond count. For example use
234  `Kernel::Clock::now() + 5s` rather than `Kernel::get_ms_count() + 5000`.
235 */
236 MBED_DEPRECATED_SINCE("mbed-os-6.0.0", "Pass a chrono time_point, not an integer millisecond count. For example use `Kernel::Clock::now() + 5s` rather than `Kernel::get_ms_count() + 5000`.")
237 void sleep_until(uint64_t millisec);
238 
239 /** Sleep until a specified time in millisec
240  The specified time is according to Kernel::Clock.
241  @param abs_time absolute time
242  @note You cannot call this function from ISR context.
243  @note if abs_time is equal to or lower than Kernel::Clock::now(), this
244  returns immediately.
245  @note The equivalent functionality is accessible in C via thread_sleep_until.
246 */
247 void sleep_until(Kernel::Clock::time_point abs_time);
248 
249 /** Pass control to next equal-priority thread that is in state READY.
250  (Higher-priority READY threads would prevent us from running; this
251  will not enable lower-priority threads to run, as we remain READY).
252  @note You cannot call this function from ISR context.
253 */
254 void yield();
255 
256 /** Get the thread id of the current running thread.
257  @return thread ID for reference by other functions or nullptr in case of error or in ISR context.
258  @note You may call this function from ISR context.
259 */
260 osThreadId_t get_id();
261 
262 /** Get the thread name of the current running thread.
263  @return thread name pointer or nullptr if thread has no name or in case of error.
264  @note You cannot call this function from ISR context.
265 */
266 const char *get_name();
267 
268 };
269 /** @}*/
270 /** @}*/
271 
272 
273 namespace internal {
274 /** \addtogroup rtos-internal-api */
275 /** @{*/
276 
278  uint32_t *flags;
279  uint32_t options;
280  uint32_t flags_wanted;
281  uint32_t result;
282  bool match;
283 };
284 
285 bool non_rtos_check_flags(void *handle);
286 
287 }
288 /** @}*/
289 }
290 #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.
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
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.