Lines Matching full:thread
16 A :dfn:`thread` is a kernel object that is used for application processing
20 available RAM). Each thread is referenced by a :dfn:`thread id` that is assigned
21 when the thread is spawned.
23 A thread has the following key properties:
25 * A **stack area**, which is a region of memory used for the thread's stack.
27 of the thread's processing. Special macros exist to create and work with
30 * A **thread control block** for private kernel bookkeeping of the thread's
33 * An **entry point function**, which is invoked when the thread is started.
37 allocate CPU time to the thread. (See :ref:`scheduling_v2`.)
39 * A set of **thread options**, which allow the thread to receive special
44 starting the thread.
59 Thread Creation
62 A thread must be created before it can be used. The kernel initializes
63 the thread control block as well as one end of the stack portion. The remainder
64 of the thread's stack is typically left uninitialized.
67 to start thread execution immediately. Alternatively, the kernel can be
68 instructed to delay execution of the thread by specifying a timeout
69 value -- for example, to allow device hardware used by the thread
72 The kernel allows a delayed start to be canceled before the thread begins
73 executing. A cancellation request has no effect if the thread has already
74 started. A thread whose delayed start was successfully canceled must be
77 Thread Termination
80 Once a thread is started it typically executes forever. However, a thread may
84 A thread that terminates is responsible for releasing any shared resources
88 In some cases a thread may want to sleep until another thread terminates.
90 will block the calling thread until either the timeout expires, the target
91 thread self-exits, or the target thread aborts (either due to a
94 Once a thread has terminated, the kernel guarantees that no use will
95 be made of the thread struct. The memory of such a struct can then be
96 re-used for any purpose, including spawning a new thread. Note that
97 the thread must be fully terminated, which presents race conditions
98 where a thread's own logic signals completion which is seen by another
99 thread before the kernel processing is complete. Under normal
101 :c:func:`k_thread_abort` to synchronize on thread termination state
104 Thread Aborting
107 A thread may asynchronously end its execution by **aborting**. The kernel
108 automatically aborts a thread if the thread triggers a fatal error condition,
111 A thread can also be aborted by another thread (or by itself)
113 to signal a thread to terminate itself gracefully, rather than aborting it.
115 As with thread termination, the kernel does not reclaim shared resources
116 owned by an aborted thread.
120 ability to respawn a thread that aborts.
122 Thread Suspension
125 A thread can be prevented from executing for an indefinite period of time
127 can be used to suspend any thread, including the calling thread.
128 Suspending a thread that is already suspended has no additional effect.
130 Once suspended, a thread cannot be scheduled until another thread calls
134 A thread can prevent itself from executing for a specified period of time
136 a thread since a sleeping thread becomes executable automatically when the
141 Thread States
144 A thread that has no factors that prevent its execution is deemed
145 to be **ready**, and is eligible to be selected as the current thread.
147 A thread that has one or more factors that prevent its execution
148 is deemed to be **unready**, and cannot be selected as the current thread.
150 The following factors make a thread unready:
152 * The thread has not been started.
153 * The thread is waiting for a kernel object to complete an operation.
154 (For example, the thread is taking a semaphore that is unavailable.)
155 * The thread is waiting for a timeout to occur.
156 * The thread has been suspended.
157 * The thread has terminated or aborted.
165 **Running** are distinct thread states, that is not the correct
166 interpretation. **Ready** is a thread state, and **Running** is a
169 Thread Stack objects
172 Every thread requires its own stack buffer for the CPU to push context.
183 - If userspace is enabled, the thread's stack buffer must be appropriately
198 If it is known that a thread will never run in user mode, or the stack is
213 Thread stacks
226 Thread Priorities
229 A thread's priority is an integer value, and can be either negative or
232 For example, the scheduler gives thread A of priority 4 *higher* priority
233 over thread B of priority 7; likewise thread C of priority -2 has higher
234 priority than both thread A and thread B.
237 based on each thread's priority.
239 * A :dfn:`cooperative thread` has a negative priority value.
240 Once it becomes the current thread, a cooperative thread remains
241 the current thread until it performs an action that makes it unready.
243 * A :dfn:`preemptible thread` has a non-negative priority value.
244 Once it becomes the current thread, a preemptible thread may be supplanted
245 at any time if a cooperative thread, or a preemptible thread of higher
249 A thread's initial priority value can be altered up or down after the thread
250 has been started. Thus it is possible for a preemptible thread to become
251 a cooperative thread, and vice versa, by changing its priority.
255 Thread priorities are set and changed only at the application's request.
257 The kernel supports a virtually unlimited number of thread priority levels.
260 levels for each class of thread, resulting in the following usable priority
286 This behavior makes the act of unblocking a meta-IRQ thread (by any
289 priority thread, or an ARM-like "pended IRQ" when done from true
292 in driver subsystems. The thread, once woken, will be guaranteed to
302 thread until the current thread deliberately blocks), it should be
308 Thread Options
311 The kernel supports a small set of :dfn:`thread options` that allow a thread
313 associated with a thread are specified when the thread is spawned.
315 A thread that does not require any thread option has an option value of zero.
316 A thread that requires a thread option specifies it by name, using the
320 The following thread options are supported.
323 This option tags the thread as an :dfn:`essential thread`. This instructs
324 the kernel to treat the termination or aborting of the thread as a fatal
327 By default, the thread is not considered to be an essential thread.
330 This x86-specific option indicate that the thread uses the CPU's
334 of these registers when scheduling the thread.
337 This option indicate that the thread uses the CPU's floating point
339 and restore the contents of these registers when scheduling the thread.
343 of this register when scheduling the thread.
346 If :kconfig:option:`CONFIG_USERSPACE` is enabled, this thread will be created in
351 If :kconfig:option:`CONFIG_USERSPACE` is enabled, this thread will inherit all
352 kernel object permissions that the parent thread had, except the parent
353 thread object. See :ref:`usermode_api`.
358 Thread Custom Data
361 Every thread has a 32-bit :dfn:`custom data` area, accessible only by
362 the thread itself, and may be used by the application for any purpose
363 it chooses. The default custom data value for a thread is zero.
369 By default, thread custom data support is disabled. The configuration option
374 a thread's custom data, respectively. A thread can only access its own
375 custom data, and not that of another thread.
378 each thread calls a specific routine.
402 Use thread custom data to allow a routine to access thread-specific information,
403 by using the custom data as a pointer to a data structure owned by the thread.
408 Spawning a Thread
411 A thread is spawned by defining its stack area and its thread control block,
429 The thread spawning function returns its thread id, which can be used
430 to reference the thread.
432 The following code spawns a thread that starts immediately.
450 Alternatively, a thread can be declared at compile time by calling
452 the stack area, control block, and thread id variables automatically.
470 thread immediately. The corresponding parameter to :c:macro:`K_THREAD_DEFINE`
477 thread tries to create a new thread. The :c:func:`k_thread_create` API is
479 calling thread will be terminated:
481 * The calling thread must have permissions granted on both the child thread
484 * The child thread and stack objects must be in an uninitialized state,
496 * The priority of the child thread must be a valid priority value, and equal to
497 or lower than the parent thread.
502 If :kconfig:option:`CONFIG_USERSPACE` is enabled, a thread running in supervisor mode
505 will reset and zero the thread's stack memory. The thread will be marked
508 Terminating a Thread
511 A thread terminates itself by returning from its entry point function.
513 The following code illustrates the ways a thread can terminate.
522 return; /* thread terminates from mid-entry point function */
527 /* thread terminates at end of entry point function */
530 If :kconfig:option:`CONFIG_USERSPACE` is enabled, aborting a thread will additionally
531 mark the thread and stack objects as uninitialized so that they may be re-used.
536 Thread runtime statistics can be gathered and retrieved if
538 execution cycles of a thread.