ChibiOS  21.6.0
Collaboration diagram for Threads:

Detailed Description

Threads related APIs and services.

Operation mode

A thread is an abstraction of an independent instructions flow. In ChibiOS/RT a thread is represented by a "C" function owning a processor context, state informations and a dedicated stack area. In this scenario static variables are shared among all threads while automatic variables are local to the thread.
Operations defined for threads:

Threads queues

#define __THREADS_QUEUE_DATA(name)   {__CH_QUEUE_DATA(name)}
 Data part of a static threads queue object initializer. More...
 
#define THREADS_QUEUE_DECL(name)   threads_queue_t name = __THREADS_QUEUE_DATA(name)
 Static threads queue object initializer. More...
 

Working Areas

#define THD_WORKING_AREA_SIZE(n)   MEM_ALIGN_NEXT(sizeof(thread_t) + PORT_WA_SIZE(n), PORT_STACK_ALIGN)
 Calculates the total Working Area size. More...
 
#define THD_WORKING_AREA(s, n)   PORT_WORKING_AREA(s, n)
 Static working area allocation. More...
 
#define THD_WORKING_AREA_BASE(s)   ((stkalign_t *)(s))
 Base of a working area casted to the correct type. More...
 
#define THD_WORKING_AREA_END(s)
 End of a working area casted to the correct type. More...
 

Threads abstraction macros

#define THD_FUNCTION(tname, arg)   PORT_THD_FUNCTION(tname, arg)
 Thread declaration macro. More...
 

Threads initializers

#define THD_DESCRIPTOR(name, wbase, wend, prio, funcp, arg)
 Thread descriptor initializer with no affinity. More...
 
#define THD_DESCRIPTOR_AFFINITY(name, wbase, wend, prio, funcp, arg, oip)
 Thread descriptor initializer with no affinity. More...
 

Macro Functions

#define chThdSleepSeconds(sec)   chThdSleep(TIME_S2I(sec))
 Delays the invoking thread for the specified number of seconds. More...
 
#define chThdSleepMilliseconds(msec)   chThdSleep(TIME_MS2I(msec))
 Delays the invoking thread for the specified number of milliseconds. More...
 
#define chThdSleepMicroseconds(usec)   chThdSleep(TIME_US2I(usec))
 Delays the invoking thread for the specified number of microseconds. More...
 

Typedefs

typedef void(* tfunc_t) (void *p)
 Thread function. More...
 

Data Structures

struct  thread_descriptor_t
 Type of a thread descriptor. More...
 

Functions

thread_t__thd_object_init (os_instance_t *oip, thread_t *tp, const char *name, tprio_t prio)
 Initializes a thread structure. More...
 
void __thd_memfill (uint8_t *startp, uint8_t *endp, uint8_t v)
 Memory fill utility. More...
 
thread_tchThdCreateSuspendedI (const thread_descriptor_t *tdp)
 Creates a new thread into a static memory area. More...
 
thread_tchThdCreateSuspended (const thread_descriptor_t *tdp)
 Creates a new thread into a static memory area. More...
 
thread_tchThdCreateI (const thread_descriptor_t *tdp)
 Creates a new thread into a static memory area. More...
 
thread_tchThdCreate (const thread_descriptor_t *tdp)
 Creates a new thread into a static memory area. More...
 
thread_tchThdCreateStatic (void *wsp, size_t size, tprio_t prio, tfunc_t pf, void *arg)
 Creates a new thread into a static memory area. More...
 
thread_tchThdStart (thread_t *tp)
 Resumes a thread created with chThdCreateI(). More...
 
thread_tchThdAddRef (thread_t *tp)
 Adds a reference to a thread object. More...
 
void chThdRelease (thread_t *tp)
 Releases a reference to a thread object. More...
 
void chThdExit (msg_t msg)
 Terminates the current thread. More...
 
void chThdExitS (msg_t msg)
 Terminates the current thread. More...
 
msg_t chThdWait (thread_t *tp)
 Blocks the execution of the invoking thread until the specified thread terminates then the exit code is returned. More...
 
tprio_t chThdSetPriority (tprio_t newprio)
 Changes the running thread priority level then reschedules if necessary. More...
 
void chThdTerminate (thread_t *tp)
 Requests a thread termination. More...
 
void chThdSleep (sysinterval_t time)
 Suspends the invoking thread for the specified time. More...
 
void chThdSleepUntil (systime_t time)
 Suspends the invoking thread until the system time arrives to the specified value. More...
 
systime_t chThdSleepUntilWindowed (systime_t prev, systime_t next)
 Suspends the invoking thread until the system time arrives to the specified value. More...
 
void chThdYield (void)
 Yields the time slot. More...
 
msg_t chThdSuspendS (thread_reference_t *trp)
 Sends the current thread sleeping and sets a reference variable. More...
 
msg_t chThdSuspendTimeoutS (thread_reference_t *trp, sysinterval_t timeout)
 Sends the current thread sleeping and sets a reference variable. More...
 
void chThdResumeI (thread_reference_t *trp, msg_t msg)
 Wakes up a thread waiting on a thread reference object. More...
 
void chThdResumeS (thread_reference_t *trp, msg_t msg)
 Wakes up a thread waiting on a thread reference object. More...
 
void chThdResume (thread_reference_t *trp, msg_t msg)
 Wakes up a thread waiting on a thread reference object. More...
 
msg_t chThdEnqueueTimeoutS (threads_queue_t *tqp, sysinterval_t timeout)
 Enqueues the caller thread on a threads queue object. More...
 
void chThdDequeueNextI (threads_queue_t *tqp, msg_t msg)
 Dequeues and wakes up one thread from the threads queue object, if any. More...
 
void chThdDequeueAllI (threads_queue_t *tqp, msg_t msg)
 Dequeues and wakes up all threads from the threads queue object. More...
 
static thread_tchThdGetSelfX (void)
 Returns a pointer to the current thread_t. More...
 
static tprio_t chThdGetPriorityX (void)
 Returns the current thread priority. More...
 
static systime_t chThdGetTicksX (thread_t *tp)
 Returns the number of ticks consumed by the specified thread. More...
 
static stkalign_tchThdGetWorkingAreaX (thread_t *tp)
 Returns the working area base of the specified thread. More...
 
static bool chThdTerminatedX (thread_t *tp)
 Verifies if the specified thread is in the CH_STATE_FINAL state. More...
 
static bool chThdShouldTerminateX (void)
 Verifies if the current thread has a termination request pending. More...
 
static thread_tchThdStartI (thread_t *tp)
 Resumes a thread created with chThdCreateI(). More...
 
static void chThdSleepS (sysinterval_t ticks)
 Suspends the invoking thread for the specified number of ticks. More...
 
static void chThdQueueObjectInit (threads_queue_t *tqp)
 Initializes a threads queue object. More...
 
static bool chThdQueueIsEmptyI (threads_queue_t *tqp)
 Evaluates to true if the specified queue is empty. More...
 
static void chThdDoDequeueNextI (threads_queue_t *tqp, msg_t msg)
 Dequeues and wakes up one thread from the threads queue object. More...
 

Macro Definition Documentation

◆ __THREADS_QUEUE_DATA

#define __THREADS_QUEUE_DATA (   name)    {__CH_QUEUE_DATA(name)}

Data part of a static threads queue object initializer.

This macro should be used when statically initializing a threads queue that is part of a bigger structure.

Parameters
[in]namethe name of the threads queue variable

Definition at line 105 of file chthreads.h.

◆ THREADS_QUEUE_DECL

#define THREADS_QUEUE_DECL (   name)    threads_queue_t name = __THREADS_QUEUE_DATA(name)

Static threads queue object initializer.

Statically initialized threads queues require no explicit initialization using queue_init().

Parameters
[in]namethe name of the threads queue variable

Definition at line 114 of file chthreads.h.

◆ THD_WORKING_AREA_SIZE

#define THD_WORKING_AREA_SIZE (   n)    MEM_ALIGN_NEXT(sizeof(thread_t) + PORT_WA_SIZE(n), PORT_STACK_ALIGN)

Calculates the total Working Area size.

Parameters
[in]nthe stack size to be assigned to the thread
Returns
The total used memory in bytes.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 130 of file chthreads.h.

◆ THD_WORKING_AREA

#define THD_WORKING_AREA (   s,
 
)    PORT_WORKING_AREA(s, n)

Static working area allocation.

This macro is used to allocate a static thread working area aligned as both position and size.

Parameters
[in]sthe name to be assigned to the stack array
[in]nthe stack size to be assigned to the thread
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 143 of file chthreads.h.

◆ THD_WORKING_AREA_BASE

#define THD_WORKING_AREA_BASE (   s)    ((stkalign_t *)(s))

Base of a working area casted to the correct type.

Parameters
[in]sname of the working area

Definition at line 150 of file chthreads.h.

◆ THD_WORKING_AREA_END

#define THD_WORKING_AREA_END (   s)
Value:
(sizeof (s) / sizeof (stkalign_t)))

End of a working area casted to the correct type.

Parameters
[in]sname of the working area

Definition at line 157 of file chthreads.h.

◆ THD_FUNCTION

#define THD_FUNCTION (   tname,
  arg 
)    PORT_THD_FUNCTION(tname, arg)

Thread declaration macro.

Note
Thread declarations should be performed using this macro because the port layer could define optimizations for thread functions.

Definition at line 170 of file chthreads.h.

◆ THD_DESCRIPTOR

#define THD_DESCRIPTOR (   name,
  wbase,
  wend,
  prio,
  funcp,
  arg 
)
Value:
{ \
(name), \
(wbase), \
(wend), \
(prio), \
(funcp), \
(arg), \
NULL \
}

Thread descriptor initializer with no affinity.

Parameters
[in]namethread name
[in]wbasepointer to the working area base
[in]wendpointer to the working area end
[in]priothread priority
[in]funcpthread function pointer
[in]argthread argument

Definition at line 188 of file chthreads.h.

◆ THD_DESCRIPTOR_AFFINITY

#define THD_DESCRIPTOR_AFFINITY (   name,
  wbase,
  wend,
  prio,
  funcp,
  arg,
  oip 
)
Value:
{ \
(name), \
(wbase), \
(wend), \
(prio), \
(funcp), \
(arg), \
(oip) \
}

Thread descriptor initializer with no affinity.

Parameters
[in]namethread name
[in]wbasepointer to the working area base
[in]wendpointer to the working area end
[in]priothread priority
[in]funcpthread function pointer
[in]argthread argument
[in]oipinstance affinity

Definition at line 219 of file chthreads.h.

◆ chThdSleepSeconds

#define chThdSleepSeconds (   sec)    chThdSleep(TIME_S2I(sec))

Delays the invoking thread for the specified number of seconds.

Note
The specified time is rounded up to a value allowed by the real system tick clock.
The maximum specifiable value is implementation dependent.
Use of this macro for large values is not secure because integer overflows, make sure your value can be correctly converted.
Parameters
[in]sectime in seconds, must be different from zero
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 247 of file chthreads.h.

◆ chThdSleepMilliseconds

#define chThdSleepMilliseconds (   msec)    chThdSleep(TIME_MS2I(msec))

Delays the invoking thread for the specified number of milliseconds.

Note
The specified time is rounded up to a value allowed by the real system tick clock.
The maximum specifiable value is implementation dependent.
Use of this macro for large values is not secure because integer overflows, make sure your value can be correctly converted.
Parameters
[in]msectime in milliseconds, must be different from zero
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 263 of file chthreads.h.

◆ chThdSleepMicroseconds

#define chThdSleepMicroseconds (   usec)    chThdSleep(TIME_US2I(usec))

Delays the invoking thread for the specified number of microseconds.

Note
The specified time is rounded up to a value allowed by the real system tick clock.
The maximum specifiable value is implementation dependent.
Use of this macro for large values is not secure because integer overflows, make sure your value can be correctly converted.
Parameters
[in]usectime in microseconds, must be different from zero
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 279 of file chthreads.h.

Typedef Documentation

◆ tfunc_t

typedef void(* tfunc_t) (void *p)

Thread function.

Definition at line 52 of file chthreads.h.

Function Documentation

◆ __thd_object_init()

thread_t * __thd_object_init ( os_instance_t oip,
thread_t tp,
const char *  name,
tprio_t  prio 
)

Initializes a thread structure.

Note
This is an internal functions, do not use it in application code.
Parameters
[in]oippointer to the OS instance
[in]tppointer to the thread
[in]namethread name
[in]priothe priority level for the new thread
Returns
The same thread pointer passed as parameter.
Function Class:
Not an API, this function is for internal use only.

Definition at line 89 of file chthreads.c.

References CH_CFG_THREAD_INIT_HOOK, CH_CFG_TIME_QUANTUM, CH_FLAG_MODE_STATIC, ch_list_init(), ch_queue_init(), CH_STATE_WTSTART, chTMObjectInit(), ch_thread::epending, ch_thread::flags, ch_thread::hdr, ch_thread::msgqueue, ch_thread::mtxlist, ch_thread::name, ch_thread::owner, ch_thread::pqueue, ch_priority_queue::prio, ch_thread::realprio, ch_thread::refs, REG_INSERT, ch_thread::state, ch_thread::stats, ch_thread::ticks, ch_thread::time, and ch_thread::waiting.

Referenced by chInstanceObjectInit(), and chThdCreateStatic().

Here is the call graph for this function:

◆ __thd_memfill()

void __thd_memfill ( uint8_t *  startp,
uint8_t *  endp,
uint8_t  v 
)

Memory fill utility.

Parameters
[in]startpfirst address to fill
[in]endplast address to fill +1
[in]vfiller value
Function Class:
Not an API, this function is for internal use only.

Definition at line 141 of file chthreads.c.

Referenced by chThdCreate(), chThdCreateFromHeap(), chThdCreateFromMemoryPool(), chThdCreateStatic(), and chThdCreateSuspended().

◆ chThdCreateSuspendedI()

thread_t * chThdCreateSuspendedI ( const thread_descriptor_t tdp)

Creates a new thread into a static memory area.

The new thread is initialized but not inserted in the ready list, the initial state is CH_STATE_WTSTART.

Postcondition
The created thread has a reference counter set to one, it is caller responsibility to call chThdRelease() or chthdWait() in order to release the reference. The thread persists in the registry until its reference counter reaches zero.
The initialized thread can be subsequently started by invoking chThdStart(), chThdStartI() or chSchWakeupS() depending on the execution context.
Note
A thread can terminate by calling chThdExit() or by simply returning from its main function.
Threads created using this function do not obey to the CH_DBG_FILL_THREADS debug option because it would keep the kernel locked for too much time.
Parameters
[out]tdppointer to the thread descriptor
Returns
The pointer to the thread_t structure allocated for the thread into the working space area.
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 172 of file chthreads.c.

Referenced by chThdCreate(), chThdCreateFromHeap(), chThdCreateFromMemoryPool(), chThdCreateI(), and chThdCreateSuspended().

◆ chThdCreateSuspended()

thread_t * chThdCreateSuspended ( const thread_descriptor_t tdp)

Creates a new thread into a static memory area.

The new thread is initialized but not inserted in the ready list, the initial state is CH_STATE_WTSTART.

Postcondition
The created thread has a reference counter set to one, it is caller responsibility to call chThdRelease() or chthdWait() in order to release the reference. The thread persists in the registry until its reference counter reaches zero.
The initialized thread can be subsequently started by invoking chThdStart(), chThdStartI() or chSchWakeupS() depending on the execution context.
Note
A thread can terminate by calling chThdExit() or by simply returning from its main function.
Parameters
[out]tdppointer to the thread descriptor
Returns
The pointer to the thread_t structure allocated for the thread into the working space area.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 227 of file chthreads.c.

References __thd_memfill(), CH_DBG_STACK_FILL_VALUE, chDbgAssert, chRegFindThreadByWorkingArea(), chSysLock, chSysUnlock, chThdCreateSuspendedI(), thread_descriptor_t::wbase, and thread_descriptor_t::wend.

Here is the call graph for this function:

◆ chThdCreateI()

thread_t * chThdCreateI ( const thread_descriptor_t tdp)

Creates a new thread into a static memory area.

The new thread is initialized and make ready to execute.

Postcondition
The created thread has a reference counter set to one, it is caller responsibility to call chThdRelease() or chthdWait() in order to release the reference. The thread persists in the registry until its reference counter reaches zero.
The initialized thread can be subsequently started by invoking chThdStart(), chThdStartI() or chSchWakeupS() depending on the execution context.
Note
A thread can terminate by calling chThdExit() or by simply returning from its main function.
Threads created using this function do not obey to the CH_DBG_FILL_THREADS debug option because it would keep the kernel locked for too much time.
Parameters
[out]tdppointer to the thread descriptor
Returns
The pointer to the thread_t structure allocated for the thread into the working space area.
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 270 of file chthreads.c.

References chSchReadyI(), and chThdCreateSuspendedI().

Here is the call graph for this function:

◆ chThdCreate()

thread_t * chThdCreate ( const thread_descriptor_t tdp)

Creates a new thread into a static memory area.

The new thread is initialized and make ready to execute.

Postcondition
The created thread has a reference counter set to one, it is caller responsibility to call chThdRelease() or chthdWait() in order to release the reference. The thread persists in the registry until its reference counter reaches zero.
Note
A thread can terminate by calling chThdExit() or by simply returning from its main function.
Parameters
[out]tdppointer to the thread descriptor
Returns
The pointer to the thread_t structure allocated for the thread into the working space area.
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 291 of file chthreads.c.

References __thd_memfill(), CH_DBG_STACK_FILL_VALUE, chDbgAssert, chRegFindThreadByWorkingArea(), chSchWakeupS(), chSysLock, chSysUnlock, chThdCreateSuspendedI(), MSG_OK, thread_descriptor_t::wbase, and thread_descriptor_t::wend.

Here is the call graph for this function:

◆ chThdCreateStatic()

thread_t * chThdCreateStatic ( void *  wsp,
size_t  size,
tprio_t  prio,
tfunc_t  pf,
void *  arg 
)

Creates a new thread into a static memory area.

Postcondition
The created thread has a reference counter set to one, it is caller responsibility to call chThdRelease() or chthdWait() in order to release the reference. The thread persists in the registry until its reference counter reaches zero.
Note
A thread can terminate by calling chThdExit() or by simply returning from its main function.
Parameters
[out]wsppointer to a working area dedicated to the thread stack
[in]sizesize of the working area
[in]priothe priority level for the new thread
[in]pfthe thread function
[in]argan argument passed to the thread function. It can be NULL.
Returns
The pointer to the thread_t structure allocated for the thread into the working space area.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 334 of file chthreads.c.

References __thd_memfill(), __thd_object_init(), CH_DBG_STACK_FILL_VALUE, chDbgAssert, chDbgCheck, chRegFindThreadByWorkingArea(), chSchWakeupS(), chSysLock, chSysUnlock, currcore, HIGHPRIO, MEM_ALIGN_NEXT, MEM_IS_ALIGNED, MSG_OK, PORT_SETUP_CONTEXT, PORT_STACK_ALIGN, PORT_WORKING_AREA_ALIGN, THD_WORKING_AREA_SIZE, and ch_thread::wabase.

Here is the call graph for this function:

◆ chThdStart()

thread_t * chThdStart ( thread_t tp)

Resumes a thread created with chThdCreateI().

Parameters
[in]tppointer to the thread
Returns
The pointer to the thread_t structure allocated for the thread into the working space area.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 390 of file chthreads.c.

References CH_STATE_WTSTART, chDbgAssert, chSchWakeupS(), chSysLock, chSysUnlock, MSG_OK, and ch_thread::state.

Here is the call graph for this function:

◆ chThdAddRef()

thread_t * chThdAddRef ( thread_t tp)

Adds a reference to a thread object.

Precondition
The configuration option CH_CFG_USE_REGISTRY must be enabled in order to use this function.
Parameters
[in]tppointer to the thread
Returns
The same thread pointer passed as parameter representing the new reference.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 412 of file chthreads.c.

References chDbgAssert, chSysLock, chSysUnlock, and ch_thread::refs.

◆ chThdRelease()

void chThdRelease ( thread_t tp)

Releases a reference to a thread object.

If the references counter reaches zero and the thread is in the CH_STATE_FINAL state then the thread's memory is returned to the proper allocator and the thread is removed from the registry.
Threads whose counter reaches zero and are still active become "detached" and will be removed from registry on termination.

Precondition
The configuration option CH_CFG_USE_REGISTRY must be enabled in order to use this function.
Note
Static threads are not affected.
Parameters
[in]tppointer to the thread
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 438 of file chthreads.c.

References CH_FLAG_MODE_HEAP, CH_FLAG_MODE_MASK, CH_FLAG_MODE_MPOOL, CH_STATE_FINAL, chDbgAssert, chHeapFree(), chPoolFree(), chSysLock, chSysUnlock, chThdGetWorkingAreaX(), ch_thread::flags, ch_thread::mpool, ch_thread::refs, REG_REMOVE, and ch_thread::state.

Referenced by chRegNextThread(), and chThdWait().

Here is the call graph for this function:

◆ chThdExit()

void chThdExit ( msg_t  msg)

Terminates the current thread.

The thread goes in the CH_STATE_FINAL state holding the specified exit status code, other threads can retrieve the exit status code by invoking the function chThdWait().

Postcondition
Eventual code after this function will never be executed, this function never returns. The compiler has no way to know this so do not assume that the compiler would remove the dead code.
Parameters
[in]msgthread exit code
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 488 of file chthreads.c.

References chSysLock, and chThdExitS().

Here is the call graph for this function:

◆ chThdExitS()

void chThdExitS ( msg_t  msg)

Terminates the current thread.

The thread goes in the CH_STATE_FINAL state holding the specified exit status code, other threads can retrieve the exit status code by invoking the function chThdWait().

Postcondition
Exiting a non-static thread that does not have references (detached) causes the thread to remain in the registry. It can only be removed by performing a registry scan operation.
Eventual code after this function will never be executed, this function never returns. The compiler has no way to know this so do not assume that the compiler would remove the dead code.
Parameters
[in]msgthread exit code
Function Class:
This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 512 of file chthreads.c.

References CH_CFG_THREAD_EXIT_HOOK, CH_FLAG_MODE_MASK, CH_FLAG_MODE_STATIC, ch_list_notempty(), ch_list_unlink(), CH_STATE_FINAL, chDbgAssert, chSchGoSleepS(), chSchReadyI(), chThdGetSelfX, ch_thread::exitcode, ch_thread::flags, ch_thread::refs, REG_REMOVE, ch_thread::u, unlikely, and ch_thread::waiting.

Referenced by chThdExit().

Here is the call graph for this function:

◆ chThdWait()

msg_t chThdWait ( thread_t tp)

Blocks the execution of the invoking thread until the specified thread terminates then the exit code is returned.

This function waits for the specified thread to terminate then decrements its reference counter, if the counter reaches zero then the thread working area is returned to the proper allocator and the thread is removed from registry.

Precondition
The configuration option CH_CFG_USE_WAITEXIT must be enabled in order to use this function.
Postcondition
Enabling chThdWait() requires 2-4 (depending on the architecture) extra bytes in the thread_t structure.
Note
If CH_CFG_USE_DYNAMIC is not specified this function just waits for the thread termination, no memory allocators are involved.
Parameters
[in]tppointer to the thread
Returns
The exit code from the terminated thread.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 569 of file chthreads.c.

References ch_list_link(), CH_STATE_FINAL, CH_STATE_WTEXIT, chDbgAssert, chDbgCheck, chSchGoSleepS(), chSysLock, chSysUnlock, chThdGetSelfX, chThdRelease(), ch_thread::exitcode, ch_thread::hdr, likely, ch_thread::list, ch_thread::refs, ch_thread::state, ch_thread::u, and ch_thread::waiting.

Here is the call graph for this function:

◆ chThdSetPriority()

tprio_t chThdSetPriority ( tprio_t  newprio)

Changes the running thread priority level then reschedules if necessary.

Note
The function returns the real thread priority regardless of the current priority that could be higher than the real priority because the priority inheritance mechanism.
Parameters
[in]newpriothe new priority level of the running thread
Returns
The old priority level.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 609 of file chthreads.c.

References chDbgCheck, chSchRescheduleS(), chSysLock, chSysUnlock, chThdGetSelfX, ch_thread::hdr, HIGHPRIO, ch_thread::pqueue, ch_priority_queue::prio, and ch_thread::realprio.

Here is the call graph for this function:

◆ chThdTerminate()

void chThdTerminate ( thread_t tp)

Requests a thread termination.

Precondition
The target thread must be written to invoke periodically chThdShouldTerminate() and terminate cleanly if it returns true.
Postcondition
The specified thread will terminate after detecting the termination condition.
Parameters
[in]tppointer to the thread
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 645 of file chthreads.c.

References CH_FLAG_TERMINATE, chSysLock, chSysUnlock, and ch_thread::flags.

◆ chThdSleep()

void chThdSleep ( sysinterval_t  time)

Suspends the invoking thread for the specified time.

Parameters
[in]timethe delay in system ticks, the special values are handled as follow:
  • TIME_INFINITE the thread enters an infinite sleep state.
  • TIME_IMMEDIATE this value is not allowed.
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 664 of file chthreads.c.

References chSysLock, chSysUnlock, and chThdSleepS.

◆ chThdSleepUntil()

void chThdSleepUntil ( systime_t  time)

Suspends the invoking thread until the system time arrives to the specified value.

Note
The function has no concept of "past", all specifiable times are in the future, this means that if you call this function exceeding your calculated intervals then the function will return in a far future time, not immediately.
See also
chThdSleepUntilWindowed()
Parameters
[in]timeabsolute system time
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 684 of file chthreads.c.

References chSysLock, chSysUnlock, chThdSleepS, chTimeDiffX, chVTGetSystemTimeX, and likely.

◆ chThdSleepUntilWindowed()

systime_t chThdSleepUntilWindowed ( systime_t  prev,
systime_t  next 
)

Suspends the invoking thread until the system time arrives to the specified value.

Note
The system time is assumed to be between prev and next else the call is assumed to have been called outside the allowed time interval, in this case no sleep is performed.
See also
chThdSleepUntil()
Parameters
[in]prevabsolute system time of the previous deadline
[in]nextabsolute system time of the next deadline
Returns
the next parameter
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 709 of file chthreads.c.

References chSysLock, chSysUnlock, chThdSleepS, chTimeDiffX, chTimeIsInRangeX(), chVTGetSystemTimeX, and likely.

Here is the call graph for this function:

◆ chThdYield()

void chThdYield ( void  )

Yields the time slot.

Yields the CPU control to the next thread in the ready list with equal priority, if any.

Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 729 of file chthreads.c.

References chSchDoYieldS(), chSysLock, and chSysUnlock.

Here is the call graph for this function:

◆ chThdSuspendS()

msg_t chThdSuspendS ( thread_reference_t trp)

Sends the current thread sleeping and sets a reference variable.

Note
This function must reschedule, it can only be called from thread context.
Parameters
[in]trpa pointer to a thread reference object
Returns
The wake up message.
Function Class:
This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 746 of file chthreads.c.

References CH_STATE_SUSPENDED, chDbgAssert, chSchGoSleepS(), chThdGetSelfX, ch_thread::u, and ch_thread::wttrp.

Here is the call graph for this function:

◆ chThdSuspendTimeoutS()

msg_t chThdSuspendTimeoutS ( thread_reference_t trp,
sysinterval_t  timeout 
)

Sends the current thread sleeping and sets a reference variable.

Note
This function must reschedule, it can only be called from thread context.
Parameters
[in]trpa pointer to a thread reference object
[in]timeoutthe timeout in system ticks, the special values are handled as follow:
  • TIME_INFINITE the thread enters an infinite sleep state.
  • TIME_IMMEDIATE the thread is not suspended and the function returns MSG_TIMEOUT as if a timeout occurred.
Returns
The wake up message.
Return values
MSG_TIMEOUTif the operation timed out.
Function Class:
This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 777 of file chthreads.c.

References CH_STATE_SUSPENDED, chDbgAssert, chSchGoSleepTimeoutS(), chThdGetSelfX, MSG_TIMEOUT, TIME_IMMEDIATE, ch_thread::u, unlikely, and ch_thread::wttrp.

Here is the call graph for this function:

◆ chThdResumeI()

void chThdResumeI ( thread_reference_t trp,
msg_t  msg 
)

Wakes up a thread waiting on a thread reference object.

Note
This function must not reschedule because it can be called from ISR context.
Parameters
[in]trpa pointer to a thread reference object
[in]msgthe message code
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 802 of file chthreads.c.

References CH_STATE_SUSPENDED, chDbgAssert, chSchReadyI(), ch_thread::rdymsg, ch_thread::state, and ch_thread::u.

Here is the call graph for this function:

◆ chThdResumeS()

void chThdResumeS ( thread_reference_t trp,
msg_t  msg 
)

Wakes up a thread waiting on a thread reference object.

Note
This function must reschedule, it can only be called from thread context.
Parameters
[in]trpa pointer to a thread reference object
[in]msgthe message code
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 825 of file chthreads.c.

References CH_STATE_SUSPENDED, chDbgAssert, chSchWakeupS(), and ch_thread::state.

Referenced by chThdResume().

Here is the call graph for this function:

◆ chThdResume()

void chThdResume ( thread_reference_t trp,
msg_t  msg 
)

Wakes up a thread waiting on a thread reference object.

Note
This function must reschedule, it can only be called from thread context.
Parameters
[in]trpa pointer to a thread reference object
[in]msgthe message code
Function Class:
Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 847 of file chthreads.c.

References chSysLock, chSysUnlock, and chThdResumeS().

Here is the call graph for this function:

◆ chThdEnqueueTimeoutS()

msg_t chThdEnqueueTimeoutS ( threads_queue_t tqp,
sysinterval_t  timeout 
)

Enqueues the caller thread on a threads queue object.

The caller thread is enqueued and put to sleep until it is dequeued or the specified timeouts expires.

Parameters
[in]tqppointer to the threads queue object
[in]timeoutthe timeout in system ticks, the special values are handled as follow:
  • TIME_INFINITE the thread enters an infinite sleep state.
  • TIME_IMMEDIATE the thread is not enqueued and the function returns MSG_TIMEOUT as if a timeout occurred.
Returns
The message from osalQueueWakeupOneI() or osalQueueWakeupAllI() functions.
Return values
MSG_TIMEOUTif the thread has not been dequeued within the specified timeout or if the function has been invoked with TIME_IMMEDIATE as timeout specification.
Function Class:
This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 877 of file chthreads.c.

References ch_queue_insert(), CH_STATE_QUEUED, chSchGoSleepTimeoutS(), chThdGetSelfX, MSG_TIMEOUT, TIME_IMMEDIATE, and unlikely.

Here is the call graph for this function:

◆ chThdDequeueNextI()

void chThdDequeueNextI ( threads_queue_t tqp,
msg_t  msg 
)

Dequeues and wakes up one thread from the threads queue object, if any.

Parameters
[in]tqppointer to the threads queue object
[in]msgthe message code
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 898 of file chthreads.c.

References ch_queue_notempty(), and chThdDoDequeueNextI().

Here is the call graph for this function:

◆ chThdDequeueAllI()

void chThdDequeueAllI ( threads_queue_t tqp,
msg_t  msg 
)

Dequeues and wakes up all threads from the threads queue object.

Parameters
[in]tqppointer to the threads queue object
[in]msgthe message code
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 913 of file chthreads.c.

References ch_queue_notempty(), and chThdDoDequeueNextI().

Here is the call graph for this function:

◆ chThdGetSelfX()

static thread_t* chThdGetSelfX ( void  )
inlinestatic

Returns a pointer to the current thread_t.

Returns
A pointer to the current thread.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 341 of file chthreads.h.

References __sch_get_currthread.

Referenced by chThdGetPriorityX(), and chThdShouldTerminateX().

◆ chThdGetPriorityX()

static tprio_t chThdGetPriorityX ( void  )
inlinestatic

Returns the current thread priority.

Note
Can be invoked in any context.
Returns
The current thread priority.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 354 of file chthreads.h.

References chThdGetSelfX(), ch_thread::hdr, ch_thread::pqueue, and ch_priority_queue::prio.

Here is the call graph for this function:

◆ chThdGetTicksX()

static systime_t chThdGetTicksX ( thread_t tp)
inlinestatic

Returns the number of ticks consumed by the specified thread.

Note
This function is only available when the CH_DBG_THREADS_PROFILING configuration option is enabled.
Parameters
[in]tppointer to the thread
Returns
The number of consumed system ticks.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 370 of file chthreads.h.

References ch_thread::time.

◆ chThdGetWorkingAreaX()

static stkalign_t* chThdGetWorkingAreaX ( thread_t tp)
inlinestatic

Returns the working area base of the specified thread.

Parameters
[in]tppointer to the thread
Returns
The working area base pointer.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 386 of file chthreads.h.

References ch_thread::wabase.

Referenced by chRegFindThreadByWorkingArea(), and chThdRelease().

◆ chThdTerminatedX()

static bool chThdTerminatedX ( thread_t tp)
inlinestatic

Verifies if the specified thread is in the CH_STATE_FINAL state.

Parameters
[in]tppointer to the thread
Return values
truethread terminated.
falsethread not terminated.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 401 of file chthreads.h.

References CH_STATE_FINAL, and ch_thread::state.

◆ chThdShouldTerminateX()

static bool chThdShouldTerminateX ( void  )
inlinestatic

Verifies if the current thread has a termination request pending.

Return values
truetermination request pending.
falsetermination request not pending.
Function Class:
This is an X-Class API, this function can be invoked from any context.

Definition at line 414 of file chthreads.h.

References CH_FLAG_TERMINATE, chThdGetSelfX(), and ch_thread::flags.

Here is the call graph for this function:

◆ chThdStartI()

static thread_t* chThdStartI ( thread_t tp)
inlinestatic

Resumes a thread created with chThdCreateI().

Parameters
[in]tppointer to the thread
Returns
The pointer to the thread_t structure allocated for the thread into the working space area.
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 428 of file chthreads.h.

References CH_STATE_WTSTART, chDbgAssert, chSchReadyI(), and ch_thread::state.

Here is the call graph for this function:

◆ chThdSleepS()

static void chThdSleepS ( sysinterval_t  ticks)
inlinestatic

Suspends the invoking thread for the specified number of ticks.

Parameters
[in]ticksthe delay in system ticks, the special values are handled as follow:
  • TIME_INFINITE the thread enters an infinite sleep state.
  • TIME_IMMEDIATE this value is not allowed.
Function Class:
This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 447 of file chthreads.h.

References CH_STATE_SLEEPING, chDbgCheck, chSchGoSleepTimeoutS(), and TIME_IMMEDIATE.

Here is the call graph for this function:

◆ chThdQueueObjectInit()

static void chThdQueueObjectInit ( threads_queue_t tqp)
inlinestatic

Initializes a threads queue object.

Parameters
[out]tqppointer to the threads queue object
Function Class:
Initializer, this function just initializes an object and can be invoked before the kernel is initialized.

Definition at line 461 of file chthreads.h.

References ch_queue_init().

Here is the call graph for this function:

◆ chThdQueueIsEmptyI()

static bool chThdQueueIsEmptyI ( threads_queue_t tqp)
inlinestatic

Evaluates to true if the specified queue is empty.

Parameters
[out]tqppointer to the threads queue object
Returns
The queue status.
Return values
falseif the queue is not empty.
trueif the queue is empty.
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 476 of file chthreads.h.

◆ chThdDoDequeueNextI()

static void chThdDoDequeueNextI ( threads_queue_t tqp,
msg_t  msg 
)
inlinestatic

Dequeues and wakes up one thread from the threads queue object.

Dequeues one thread from the queue without checking if the queue is empty.

Precondition
The queue must contain at least an object.
Parameters
[in]tqppointer to the threads queue object
[in]msgthe message code
Function Class:
This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 494 of file chthreads.h.

References ch_queue_fifo_remove(), ch_queue_notempty(), CH_STATE_QUEUED, chDbgAssert, chSchReadyI(), ch_thread::rdymsg, ch_thread::state, and ch_thread::u.

Here is the call graph for this function:
stkalign_t
port_stkalign_t stkalign_t
Definition: chearly.h:80
THD_WORKING_AREA_BASE
#define THD_WORKING_AREA_BASE(s)
Base of a working area casted to the correct type.
Definition: chthreads.h:150