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:

Create, a thread is started on the specified thread function. This operation is available in multiple variants, both static and dynamic.
Exit, a thread terminates by returning from its top level function or invoking a specific API, the thread can return a value that can be retrieved by other threads.
Wait, a thread waits for the termination of another thread and retrieves its return value.
Resume, a thread created in suspended state is started.
Sleep, the execution of a thread is suspended for the specified amount of time or the specified future absolute time is reached.
SetPriority, a thread changes its own priority level.
Yield, a thread voluntarily renounces to its time slot.

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...

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 *	_thread_init (thread_t tp, const char name, tprio_t prio)
	Initializes a thread structure. More...

void	_thread_memfill (uint8_t startp, uint8_t endp, uint8_t v)
	Memory fill utility. More...

thread_t *	chThdCreateSuspendedI (const thread_descriptor_t *tdp)
	Creates a new thread into a static memory area. More...

thread_t *	chThdCreateSuspended (const thread_descriptor_t *tdp)
	Creates a new thread into a static memory area. More...

thread_t *	chThdCreateI (const thread_descriptor_t *tdp)
	Creates a new thread into a static memory area. More...

thread_t *	chThdCreate (const thread_descriptor_t *tdp)
	Creates a new thread into a static memory area. More...

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. More...

thread_t *	chThdStart (thread_t *tp)
	Resumes a thread created with `chThdCreateI()`. More...

thread_t *	chThdAddRef (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_t *	chThdGetSelfX (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_t *	chThdGetWorkingAreaX (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_t *	chThdStartI (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] name the name of the threads queue variable

Definition at line 99 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] name the name of the threads queue variable

Definition at line 108 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] n the 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 124 of file chthreads.h.

◆ THD_WORKING_AREA

#define THD_WORKING_AREA	(	s,
		n
	)	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]	s	the name to be assigned to the stack array
[in]	n	the 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 137 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] s name of the working area

Definition at line 144 of file chthreads.h.

◆ THD_WORKING_AREA_END

#define THD_WORKING_AREA_END ( s )

Value:

(THD_WORKING_AREA_BASE(s) + \

(sizeof (s) / sizeof (stkalign_t)))

End of a working area casted to the correct type.

Parameters

[in] s name of the working area

Definition at line 151 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 164 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] sec time 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 184 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] msec time 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 200 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] usec time 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 216 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

◆ _thread_init()

thread_t * _thread_init	(	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]	tp	pointer to the thread
[in]	name	thread name
[in]	prio	the 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 88 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::msgqueue, ch_thread::mtxlist, ch_thread::name, ch_thread::pqueue, 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 chSysInit(), chThdCreateStatic(), and chThdCreateSuspendedI().

Here is the call graph for this function:

◆ _thread_memfill()

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

Memory fill utility.

Parameters

[in]	startp	first address to fill
[in]	endp	last address to fill +1
[in]	v	filler value

Function Class:: Not an API, this function is for internal use only.

Definition at line 136 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] tdp pointer 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 167 of file chthreads.c.

References _thread_init(), thread_descriptor_t::arg, chDbgCheck, chDbgCheckClassI(), thread_descriptor_t::funcp, HIGHPRIO, MEM_ALIGN_NEXT, MEM_IS_ALIGNED, thread_descriptor_t::name, thread_descriptor_t::prio, THD_WORKING_AREA_SIZE, ch_thread::wabase, thread_descriptor_t::wbase, and thread_descriptor_t::wend.

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

Here is the call graph for this function:

◆ 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] tdp pointer 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 216 of file chthreads.c.

References _thread_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] tdp pointer 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 259 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] tdp pointer 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 280 of file chthreads.c.

References _thread_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]	wsp	pointer to a working area dedicated to the thread stack
[in]	size	size of the working area
[in]	prio	the priority level for the new thread
[in]	pf	the thread function
[in]	arg	an 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 323 of file chthreads.c.

References _thread_init(), _thread_memfill(), CH_DBG_STACK_FILL_VALUE, chDbgAssert, chDbgCheck, chRegFindThreadByWorkingArea(), chSchWakeupS(), chSysLock(), chSysUnlock(), HIGHPRIO, MEM_ALIGN_NEXT, MEM_IS_ALIGNED, MSG_OK, 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] tp pointer 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 379 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] tp pointer 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 401 of file chthreads.c.

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

Here is the call graph for this function:

◆ 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] tp pointer 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 427 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] msg thread 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 477 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] msg thread 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 501 of file chthreads.c.

References CH_CFG_THREAD_EXIT_HOOK, CH_FLAG_MODE_MASK, CH_FLAG_MODE_STATIC, ch_list_notempty(), ch_list_pop(), CH_STATE_FINAL, chDbgAssert, chSchGoSleepS(), chSchReadyI(), currp, ch_thread::exitcode, ch_thread::flags, ch_thread::refs, REG_REMOVE, ch_thread::u, 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] tp pointer 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 559 of file chthreads.c.

References ch_list_push(), CH_STATE_FINAL, CH_STATE_WTEXIT, chDbgAssert, chDbgCheck, chSchGoSleepS(), chSysLock(), chSysUnlock(), chThdRelease(), currp, ch_thread::exitcode, 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] newprio the 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 598 of file chthreads.c.

References chDbgCheck, chSchRescheduleS(), chSysLock(), chSysUnlock(), currp, and HIGHPRIO.

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] tp pointer 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 633 of file chthreads.c.

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

Here is the call graph for this function:

◆ chThdSleep()

void chThdSleep ( sysinterval_t time )

Suspends the invoking thread for the specified time.

Parameters

[in]

time

the 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 652 of file chthreads.c.

References chSysLock(), chSysUnlock(), and chThdSleepS().

Here is the call graph for this function:

◆ 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] time absolute 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 672 of file chthreads.c.

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

Here is the call graph for this function:

◆ 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]	prev	absolute system time of the previous deadline
[in]	next	absolute 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 697 of file chthreads.c.

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

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 717 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] trp a 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 734 of file chthreads.c.

References CH_STATE_SUSPENDED, chDbgAssert, chSchGoSleepS(), chThdGetSelfX(), ch_thread::rdymsg, 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]	trp	a pointer to a thread reference object
[in]	timeout	the 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 wake up message.

Return values

MSG_TIMEOUT if 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 765 of file chthreads.c.

References CH_STATE_SUSPENDED, chDbgAssert, chSchGoSleepTimeoutS(), chThdGetSelfX(), MSG_TIMEOUT, TIME_IMMEDIATE, ch_thread::u, 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]	trp	a pointer to a thread reference object
[in]	msg	the 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 790 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]	trp	a pointer to a thread reference object
[in]	msg	the 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 813 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]	trp	a pointer to a thread reference object
[in]	msg	the 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 835 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]	tqp	pointer to the threads queue object
[in]	timeout	the 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_TIMEOUT if 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 865 of file chthreads.c.

References ch_queue_insert(), CH_STATE_QUEUED, chSchGoSleepTimeoutS(), currp, MSG_TIMEOUT, ch_threads_queue::queue, and TIME_IMMEDIATE.

Referenced by chMBFetchTimeoutS(), chMBPostAheadTimeoutS(), and chMBPostTimeoutS().

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]	tqp	pointer to the threads queue object
[in]	msg	the 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 885 of file chthreads.c.

References ch_queue_notempty(), chThdDoDequeueNextI(), and ch_threads_queue::queue.

Referenced by chMBFetchI(), chMBFetchTimeoutS(), chMBPostAheadI(), chMBPostAheadTimeoutS(), chMBPostI(), and chMBPostTimeoutS().

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]	tqp	pointer to the threads queue object
[in]	msg	the 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 900 of file chthreads.c.

References ch_queue_notempty(), chThdDoDequeueNextI(), and ch_threads_queue::queue.

Referenced by chMBResetI().

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 275 of file chthreads.h.

References ch, and ch_system::rlist.

Referenced by chMtxGetNextMutexX(), chMtxLockS(), chMtxTryLockS(), chMtxUnlock(), chMtxUnlockAllS(), chMtxUnlockS(), chThdGetPriorityX(), chThdShouldTerminateX(), chThdSuspendS(), and chThdSuspendTimeoutS().

◆ 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 288 of file chthreads.h.

References chThdGetSelfX(), and ch_thread::pqueue.

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] tp pointer 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 304 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] tp pointer 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 320 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] tp pointer to the thread

Return values

true	thread terminated.
false	thread not terminated.

Function Class:: This is an X-Class API, this function can be invoked from any context.

Definition at line 335 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

true	termination request pending.
false	termination request not pending.

Function Class:: This is an X-Class API, this function can be invoked from any context.

Definition at line 348 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] tp pointer 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 362 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]

ticks

the 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 381 of file chthreads.h.

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

Referenced by chThdSleep(), chThdSleepUntil(), and chThdSleepUntilWindowed().

Here is the call graph for this function:

◆ chThdQueueObjectInit()

static void chThdQueueObjectInit ( threads_queue_t * tqp )

inlinestatic

Initializes a threads queue object.

Parameters

[out] tqp pointer 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 395 of file chthreads.h.

References ch_queue_init(), and ch_threads_queue::queue.

Referenced by chMBObjectInit().

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] tqp pointer to the threads queue object

Returns: The queue status.

Return values

false	if the queue is not empty.
true	if 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 410 of file chthreads.h.

References ch_queue_isempty(), chDbgCheckClassI(), and ch_threads_queue::queue.

Here is the call graph for this function:

◆ 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]	tqp	pointer to the threads queue object
[in]	msg	the 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 428 of file chthreads.h.

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

Referenced by chThdDequeueAllI(), and chThdDequeueNextI().

Here is the call graph for this function:

Detailed Description

Operation mode

Threads queues

Working Areas

Threads abstraction macros

Macro Functions

Typedefs

Data Structures

Functions

Macro Definition Documentation

◆ _THREADS_QUEUE_DATA

◆ THREADS_QUEUE_DECL

◆ THD_WORKING_AREA_SIZE

◆ THD_WORKING_AREA

◆ THD_WORKING_AREA_BASE

◆ THD_WORKING_AREA_END

◆ THD_FUNCTION

◆ chThdSleepSeconds

◆ chThdSleepMilliseconds

◆ chThdSleepMicroseconds

Typedef Documentation

◆ tfunc_t

Function Documentation

◆ _thread_init()

◆ _thread_memfill()

◆ chThdCreateSuspendedI()

◆ chThdCreateSuspended()

◆ chThdCreateI()

◆ chThdCreate()

◆ chThdCreateStatic()

◆ chThdStart()

◆ chThdAddRef()

◆ chThdRelease()

◆ chThdExit()

◆ chThdExitS()

◆ chThdWait()

◆ chThdSetPriority()

◆ chThdTerminate()

◆ chThdSleep()

◆ chThdSleepUntil()

◆ chThdSleepUntilWindowed()

◆ chThdYield()

◆ chThdSuspendS()

◆ chThdSuspendTimeoutS()

◆ chThdResumeI()

◆ chThdResumeS()

◆ chThdResume()

◆ chThdEnqueueTimeoutS()

◆ chThdDequeueNextI()

◆ chThdDequeueAllI()

◆ chThdGetSelfX()

◆ chThdGetPriorityX()

◆ chThdGetTicksX()

◆ chThdGetWorkingAreaX()

◆ chThdTerminatedX()

◆ chThdShouldTerminateX()

◆ chThdStartI()

◆ chThdSleepS()

◆ chThdQueueObjectInit()

◆ chThdQueueIsEmptyI()

◆ chThdDoDequeueNextI()