Mistake on this page?
Report an issue in GitHub or email us
Thread.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 THREAD_H
24 #define THREAD_H
25 
26 #include <stdint.h>
27 #include "rtos/mbed_rtos_types.h"
28 #include "rtos/internal/mbed_rtos1_types.h"
29 #include "rtos/internal/mbed_rtos_storage.h"
30 #include "platform/Callback.h"
31 #include "platform/mbed_toolchain.h"
32 #include "platform/NonCopyable.h"
33 #include "rtos/Semaphore.h"
34 #include "rtos/Mutex.h"
35 
36 #if MBED_CONF_RTOS_PRESENT || defined(DOXYGEN_ONLY)
37 
38 namespace rtos {
39 /** \addtogroup rtos-public-api */
40 /** @{*/
41 
42 /**
43  * \defgroup rtos_Thread Thread class
44  * @{
45  */
46 
47 /** The Thread class allow defining, creating, and controlling thread functions in the system.
48  *
49  * Example:
50  * @code
51  * #include "mbed.h"
52  * #include "rtos.h"
53  *
54  * Thread thread;
55  * DigitalOut led1(LED1);
56  * volatile bool running = true;
57  *
58  * // Blink function toggles the led in a long running loop
59  * void blink(DigitalOut *led) {
60  * while (running) {
61  * *led = !*led;
62  * ThisThread::sleep_for(1000);
63  * }
64  * }
65  *
66  * // Spawns a thread to run blink for 5 seconds
67  * int main() {
68  * thread.start(callback(blink, &led1));
69  * ThisThread::sleep_for(5000);
70  * running = false;
71  * thread.join();
72  * }
73  * @endcode
74  *
75  * @note
76  * Memory considerations: The thread control structures will be created on current thread's stack, both for the mbed OS
77  * and underlying RTOS objects (static or dynamic RTOS memory pools are not being used).
78  * Additionally the stack memory for this thread will be allocated on the heap, if it wasn't supplied to the constructor.
79  *
80  * @note
81  * MBED_TZ_DEFAULT_ACCESS (default:0) flag can be used to change the default access of all user threads in non-secure mode.
82  * MBED_TZ_DEFAULT_ACCESS set to 1, means all non-secure user threads have access to call secure functions.
83  * MBED_TZ_DEFAULT_ACCESS set to 0, means none of the non-secure user thread have access to call secure functions,
84  * to give access to particular thread used overloaded constructor with `tz_module` as argument during thread creation.
85  *
86  * MBED_TZ_DEFAULT_ACCESS is target specific define, should be set in targets.json file for Cortex-M23/M33 devices.
87  *
88  * @note
89  * Bare metal profile: This class is not supported.
90  */
91 
92 class Thread : private mbed::NonCopyable<Thread> {
93 public:
94  /** Allocate a new thread without starting execution
95  @param priority initial priority of the thread function. (default: osPriorityNormal).
96  @param stack_size stack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE).
97  @param stack_mem pointer to the stack area to be used by this thread (default: nullptr).
98  @param name name to be used for this thread. It has to stay allocated for the lifetime of the thread (default: nullptr)
99 
100  @note Default value of tz_module will be MBED_TZ_DEFAULT_ACCESS
101  @note You cannot call this function from ISR context.
102  */
103 
104  Thread(osPriority priority = osPriorityNormal,
105  uint32_t stack_size = OS_STACK_SIZE,
106  unsigned char *stack_mem = nullptr, const char *name = nullptr)
107  {
108  constructor(priority, stack_size, stack_mem, name);
109  }
110 
111  /** Allocate a new thread without starting execution
112  @param tz_module trustzone thread identifier (osThreadAttr_t::tz_module)
113  Context of RTOS threads in non-secure state must be saved when calling secure functions.
114  tz_module ID is used to allocate context memory for threads, and it can be safely set to zero for
115  threads not using secure calls at all. See "TrustZone RTOS Context Management" for more details.
116  @param priority initial priority of the thread function. (default: osPriorityNormal).
117  @param stack_size stack size (in bytes) requirements for the thread function. (default: OS_STACK_SIZE).
118  @param stack_mem pointer to the stack area to be used by this thread (default: nullptr).
119  @param name name to be used for this thread. It has to stay allocated for the lifetime of the thread (default: nullptr)
120 
121  @note You cannot call this function from ISR context.
122  */
123 
124  Thread(uint32_t tz_module, osPriority priority = osPriorityNormal,
125  uint32_t stack_size = OS_STACK_SIZE,
126  unsigned char *stack_mem = nullptr, const char *name = nullptr)
127  {
128  constructor(tz_module, priority, stack_size, stack_mem, name);
129  }
130 
131 
132  /** Starts a thread executing the specified function.
133  @param task function to be executed by this thread.
134  @return status code that indicates the execution status of the function.
135  @note a thread can only be started once
136 
137  @note You cannot call this function ISR context.
138  */
139  osStatus start(mbed::Callback<void()> task);
140 
141  /** Wait for thread to terminate
142  @return status code that indicates the execution status of the function.
143 
144  @note You cannot call this function from ISR context.
145  */
146  osStatus join();
147 
148  /** Terminate execution of a thread and remove it from Active Threads
149  @return status code that indicates the execution status of the function.
150 
151  @note You cannot call this function from ISR context.
152  */
153  osStatus terminate();
154 
155  /** Set priority of an active thread
156  @param priority new priority value for the thread function.
157  @return status code that indicates the execution status of the function.
158 
159  @note You cannot call this function from ISR context.
160  */
161  osStatus set_priority(osPriority priority);
162 
163  /** Get priority of an active thread
164  @return current priority value of the thread function.
165 
166  @note You cannot call this function from ISR context.
167  */
168  osPriority get_priority() const;
169 
170  /** Set the specified Thread Flags for the thread.
171  @param flags specifies the flags of the thread that should be set.
172  @return thread flags after setting or osFlagsError in case of incorrect parameters.
173 
174  @note You may call this function from ISR context.
175  */
176  uint32_t flags_set(uint32_t flags);
177 
178  /** State of the Thread */
179  enum State {
180  Inactive, /**< NOT USED */
181  Ready, /**< Ready to run */
182  Running, /**< Running */
183  WaitingDelay, /**< Waiting for a delay to occur */
184  WaitingJoin, /**< Waiting for thread to join. Only happens when using RTX directly. */
185  WaitingThreadFlag, /**< Waiting for a thread flag to be set */
186  WaitingEventFlag, /**< Waiting for a event flag to be set */
187  WaitingMutex, /**< Waiting for a mutex event to occur */
188  WaitingSemaphore, /**< Waiting for a semaphore event to occur */
189  WaitingMemoryPool, /**< Waiting for a memory pool */
190  WaitingMessageGet, /**< Waiting for message to arrive */
191  WaitingMessagePut, /**< Waiting for message to be send */
192  WaitingInterval, /**< NOT USED */
193  WaitingOr, /**< NOT USED */
194  WaitingAnd, /**< NOT USED */
195  WaitingMailbox, /**< NOT USED (Mail is implemented as MemoryPool and Queue) */
196 
197  /* Not in sync with RTX below here */
198  Deleted, /**< The task has been deleted or not started */
199  };
200 
201  /** State of this Thread
202  @return the State of this Thread
203 
204  @note You cannot call this function from ISR context.
205  */
206  State get_state() const;
207 
208  /** Get the total stack memory size for this Thread
209  @return the total stack memory size in bytes
210 
211  @note You cannot call this function from ISR context.
212  */
213  uint32_t stack_size() const;
214 
215  /** Get the currently unused stack memory for this Thread
216  @return the currently unused stack memory in bytes
217 
218  @note You cannot call this function from ISR context.
219  */
220  uint32_t free_stack() const;
221 
222  /** Get the currently used stack memory for this Thread
223  @return the currently used stack memory in bytes
224 
225  @note You cannot call this function from ISR context.
226  */
227  uint32_t used_stack() const;
228 
229  /** Get the maximum stack memory usage to date for this Thread
230  @return the maximum stack memory usage to date in bytes
231 
232  @note You cannot call this function from ISR context.
233  */
234  uint32_t max_stack() const;
235 
236  /** Get thread name
237  @return thread name or nullptr if the name was not set.
238 
239  @note You may call this function from ISR context.
240  */
241  const char *get_name() const;
242 
243  /** Get thread id
244  @return thread ID for reference by other functions.
245 
246  @note You may call this function from ISR context.
247  */
248  osThreadId_t get_id() const;
249 
250  /** Thread destructor
251  *
252  * @note You cannot call this function from ISR context.
253  */
254  virtual ~Thread();
255 
256 private:
257  // Required to share definitions without
258  // delegated constructors
259  void constructor(osPriority priority = osPriorityNormal,
260  uint32_t stack_size = OS_STACK_SIZE,
261  unsigned char *stack_mem = nullptr,
262  const char *name = nullptr);
263  void constructor(uint32_t tz_module,
264  osPriority priority = osPriorityNormal,
265  uint32_t stack_size = OS_STACK_SIZE,
266  unsigned char *stack_mem = nullptr,
267  const char *name = nullptr);
268  static void _thunk(void *thread_ptr);
269 
271  osThreadId_t _tid;
272  osThreadAttr_t _attr;
273  bool _dynamic_stack;
274  bool _finished;
275  Semaphore _join_sem;
276  mutable Mutex _mutex;
277  mbed_rtos_storage_thread_t _obj_mem;
278 };
279 /** @}*/
280 /** @}*/
281 }
282 #endif
283 
284 #endif
The Thread class allow defining, creating, and controlling thread functions in the system...
Definition: Thread.h:92
uint32_t flags_set(uint32_t flags)
Set the specified Thread Flags for the thread.
Waiting for a memory pool.
Definition: Thread.h:189
The Semaphore class is used to manage and protect access to a set of shared resources.
Definition: Semaphore.h:50
osStatus terminate()
Terminate execution of a thread and remove it from Active Threads.
osStatus set_priority(osPriority priority)
Set priority of an active thread.
Thread(uint32_t tz_module, osPriority priority=osPriorityNormal, uint32_t stack_size=OS_STACK_SIZE, unsigned char *stack_mem=nullptr, const char *name=nullptr)
Allocate a new thread without starting execution.
Definition: Thread.h:124
NOT USED (Mail is implemented as MemoryPool and Queue)
Definition: Thread.h:195
uint32_t free_stack() const
Get the currently unused stack memory for this Thread.
Waiting for a mutex event to occur.
Definition: Thread.h:187
Prevents generation of copy constructor and copy assignment operator in derived classes.
Definition: NonCopyable.h:162
Waiting for message to be send.
Definition: Thread.h:191
Thread(osPriority priority=osPriorityNormal, uint32_t stack_size=OS_STACK_SIZE, unsigned char *stack_mem=nullptr, const char *name=nullptr)
Allocate a new thread without starting execution.
Definition: Thread.h:104
Waiting for message to arrive.
Definition: Thread.h:190
State
State of the Thread.
Definition: Thread.h:179
Waiting for a thread flag to be set.
Definition: Thread.h:185
osStatus join()
Wait for thread to terminate.
Waiting for a event flag to be set.
Definition: Thread.h:186
Waiting for thread to join.
Definition: Thread.h:184
osPriority get_priority() const
Get priority of an active thread.
The Mutex class is used to synchronize the execution of threads.
Definition: Mutex.h:70
uint32_t used_stack() const
Get the currently used stack memory for this Thread.
State get_state() const
State of this Thread.
Ready to run.
Definition: Thread.h:181
Waiting for a delay to occur.
Definition: Thread.h:183
const char * get_name() const
Get thread name.
Waiting for a semaphore event to occur.
Definition: Thread.h:188
virtual ~Thread()
Thread destructor.
osStatus start(mbed::Callback< void()> task)
Starts a thread executing the specified function.
Definition: TaskBase.h:25
osThreadId_t get_id() const
Get thread id.
Callback class based on template specialization.
Definition: Callback.h:53
The task has been deleted or not started.
Definition: Thread.h:198
uint32_t max_stack() const
Get the maximum stack memory usage to date for this Thread.
uint32_t stack_size() const
Get the total stack memory size for this 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.