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.

The threads subsystem is implicitly included in kernel however some of its part may be excluded by disabling them in chconf.h, see the CH_USE_WAITEXIT and CH_USE_DYNAMIC configuration options.

Data Structures
struct	Thread
	Structure representing a thread. More...
Functions
Thread *	_thread_init (Thread *tp, tprio_t prio)
	Initializes a thread structure.
void	_thread_memfill (uint8_t startp, uint8_t endp, uint8_t v)
	Memory fill utility.
Thread *	chThdCreateI (void wsp, size_t size, tprio_t prio, tfunc_t pf, void arg)
	Creates a new thread into a static memory area.
Thread *	chThdCreateStatic (void wsp, size_t size, tprio_t prio, tfunc_t pf, void arg)
	Creates a new thread into a static memory area.
tprio_t	chThdSetPriority (tprio_t newprio)
	Changes the running thread priority level then reschedules if necessary.
Thread *	chThdResume (Thread *tp)
	Resumes a suspended thread.
void	chThdTerminate (Thread *tp)
	Requests a thread termination.
void	chThdSleep (systime_t time)
	Suspends the invoking thread for the specified time.
void	chThdSleepUntil (systime_t time)
	Suspends the invoking thread until the system time arrives to the specified value.
void	chThdYield (void)
	Yields the time slot.
void	chThdExit (msg_t msg)
	Terminates the current thread.
void	chThdExitS (msg_t msg)
	Terminates the current thread.
msg_t	chThdWait (Thread *tp)
	Blocks the execution of the invoking thread until the specified thread terminates then the exit code is returned.
Thread states
#define	THD_STATE_READY 0
	Waiting on the ready list.
#define	THD_STATE_CURRENT 1
	Currently running.
#define	THD_STATE_SUSPENDED 2
	Created in suspended state.
#define	THD_STATE_WTSEM 3
	Waiting on a semaphore.
#define	THD_STATE_WTMTX 4
	Waiting on a mutex.
#define	THD_STATE_WTCOND 5
	Waiting on a condition variable.
#define	THD_STATE_SLEEPING 6
	Waiting in `chThdSleep()` or `chThdSleepUntil()`.
#define	THD_STATE_WTEXIT 7
	Waiting in `chThdWait()`.
#define	THD_STATE_WTOREVT 8
	Waiting for an event.
#define	THD_STATE_WTANDEVT 9
	Waiting for several events.
#define	THD_STATE_SNDMSGQ 10
	Sending a message, in queue.
#define	THD_STATE_SNDMSG 11
	Sent a message, waiting answer.
#define	THD_STATE_WTMSG 12
	Waiting for a message.
#define	THD_STATE_WTQUEUE 13
	Waiting on an I/O queue.
#define	THD_STATE_FINAL 14
	Thread terminated.
#define	THD_STATE_NAMES
	Thread states as array of strings.
Thread flags and attributes
#define	THD_MEM_MODE_MASK 3
	Thread memory mode mask.
#define	THD_MEM_MODE_STATIC 0
	Static thread.
#define	THD_MEM_MODE_HEAP 1
	Thread allocated from a Memory Heap.
#define	THD_MEM_MODE_MEMPOOL 2
	Thread allocated from a Memory Pool.
#define	THD_TERMINATE 4
	Termination requested flag.
Macro Functions
#define	chThdSelf() currp
	Returns a pointer to the current `Thread`.
#define	chThdGetPriority() (currp->p_prio)
	Returns the current thread priority.
#define	chThdGetTicks(tp) ((tp)->p_time)
	Returns the number of ticks consumed by the specified thread.
#define	chThdLS() (void *)(currp + 1)
	Returns the pointer to the `Thread` local storage area, if any.
#define	chThdTerminated(tp) ((tp)->p_state == THD_STATE_FINAL)
	Verifies if the specified thread is in the `THD_STATE_FINAL` state.
#define	chThdShouldTerminate() (currp->p_flags & THD_TERMINATE)
	Verifies if the current thread has a termination request pending.
#define	chThdResumeI(tp) chSchReadyI(tp)
	Resumes a thread created with `chThdCreateI()`.
#define	chThdSleepS(time) chSchGoSleepTimeoutS(THD_STATE_SLEEPING, time)
	Suspends the invoking thread for the specified time.
#define	chThdSleepSeconds(sec) chThdSleep(S2ST(sec))
	Delays the invoking thread for the specified number of seconds.
#define	chThdSleepMilliseconds(msec) chThdSleep(MS2ST(msec))
	Delays the invoking thread for the specified number of milliseconds.
#define	chThdSleepMicroseconds(usec) chThdSleep(US2ST(usec))
	Delays the invoking thread for the specified number of microseconds.
Typedefs
typedef msg_t(*	tfunc_t )(void *)
	Thread function.

Function Documentation

Thread * _thread_init	(	Thread *	tp,
		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]	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 69 of file chthreads.c.

References CH_TIME_QUANTUM, list_init, Thread::p_epending, Thread::p_flags, Thread::p_msgqueue, Thread::p_mtxlist, Thread::p_name, Thread::p_preempt, Thread::p_prio, Thread::p_realprio, Thread::p_refs, Thread::p_state, Thread::p_stklimit, Thread::p_time, Thread::p_waiting, queue_init, REG_INSERT, THD_MEM_MODE_STATIC, THD_STATE_SUSPENDED, and THREAD_EXT_INIT_HOOK.

Referenced by chSysInit(), and chThdCreateI().

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

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

Thread * chThdCreateI	(	void *	wsp,
		size_t	size,
		tprio_t	prio,
		tfunc_t	pf,
		void *	arg
	)

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

Postcondition:: The initialized thread can be subsequently started by invoking chThdResume(), chThdResumeI() 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]	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 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 150 of file chthreads.c.

References _thread_init(), chDbgCheck, chDbgCheckClassI(), HIGHPRIO, SETUP_CONTEXT, and THD_WA_SIZE.

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

Here is the call graph for this function:

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

Creates a new thread into a static memory area.

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

References _thread_memfill(), CH_STACK_FILL_VALUE, CH_THREAD_FILL_VALUE, chSchWakeupS(), chSysLock, chSysUnlock, chThdCreateI(), and RDY_OK.

Referenced by chSysInit().

Here is the call graph for this function:

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

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

Here is the call graph for this function:

Thread * chThdResume ( Thread * tp )

Resumes a suspended thread.

Precondition:: The specified thread pointer must refer to an initialized thread in the THD_STATE_SUSPENDED state.

Postcondition:: The specified thread is immediately started or put in the ready list depending on the relative priority levels.

Note:: Use this function to start threads created with chThdInit().

Parameters:

[in] tp pointer to the thread

Returns:: The 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 243 of file chthreads.c.

References chDbgAssert, chSchWakeupS(), chSysLock, chSysUnlock, Thread::p_state, RDY_OK, and THD_STATE_SUSPENDED.

Here is the call graph for this function:

void chThdTerminate ( Thread * 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 266 of file chthreads.c.

References chSysLock, chSysUnlock, Thread::p_flags, and THD_TERMINATE.

void chThdSleep ( systime_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 285 of file chthreads.c.

References chDbgCheck, chSysLock, chSysUnlock, chThdSleepS, and TIME_IMMEDIATE.

void chThdSleepUntil ( systime_t time )

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

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

References chSysLock, chSysUnlock, chThdSleepS, and chTimeNow.

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

References chSchDoYieldS, chSysLock, and chSysUnlock.

void chThdExit ( msg_t msg )

Terminates the current thread.

The thread goes in the THD_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 338 of file chthreads.c.

References chSysLock, and chThdExitS().

Here is the call graph for this function:

void chThdExitS ( msg_t msg )

Terminates the current thread.

The thread goes in the THD_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:: This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 359 of file chthreads.c.

References chDbgAssert, chSchGoSleepS(), chSchReadyI(), currp, Thread::exitcode, FALSE, list_remove(), notempty, Thread::p_flags, Thread::p_waiting, REG_REMOVE, THD_MEM_MODE_MASK, THD_MEM_MODE_STATIC, THD_STATE_FINAL, and THREAD_EXT_EXIT_HOOK.

Referenced by chThdExit().

Here is the call graph for this function:

msg_t chThdWait ( Thread * 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.
The memory used by the exited thread is handled in different ways depending on the API that spawned the thread:

If the thread was spawned by chThdCreateStatic() or by chThdInit() then nothing happens and the thread working area is not released or modified in any way. This is the default, totally static, behavior.
If the thread was spawned by chThdCreateFromHeap() then the working area is returned to the system heap.
If the thread was spawned by chThdCreateFromMemoryPool() then the working area is returned to the owning memory pool.

Precondition:: The configuration option CH_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 structure.; After invoking chThdWait() the thread pointer becomes invalid and must not be used as parameter for further system calls.

Note:: If CH_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 413 of file chthreads.c.

References chDbgAssert, chDbgCheck, chSchGoSleepS(), chSysLock, chSysUnlock, chThdRelease(), currp, Thread::exitcode, list_insert(), Thread::p_refs, Thread::p_state, Thread::p_waiting, THD_STATE_FINAL, and THD_STATE_WTEXIT.

Here is the call graph for this function:

Define Documentation

#define THD_STATE_READY 0

Waiting on the ready list.

Definition at line 36 of file chthreads.h.

Referenced by chMtxLockS(), chSchDoRescheduleAhead(), and chSchReadyI().

#define THD_STATE_CURRENT 1

Currently running.

Definition at line 37 of file chthreads.h.

Referenced by chMtxLockS(), chSchDoRescheduleAhead(), chSchDoRescheduleBehind(), chSchGoSleepS(), chSchWakeupS(), and chSysInit().

#define THD_STATE_SUSPENDED 2

Created in suspended state.

Definition at line 38 of file chthreads.h.

Referenced by _thread_init(), and chThdResume().

#define THD_STATE_WTSEM 3

Waiting on a semaphore.

Definition at line 39 of file chthreads.h.

Referenced by chMtxLockS(), chSemSignalWait(), chSemWaitS(), and chSemWaitTimeoutS().

#define THD_STATE_WTMTX 4

Waiting on a mutex.

Definition at line 40 of file chthreads.h.

Referenced by chMtxLockS().

#define THD_STATE_WTCOND 5

Waiting on a condition variable.

Definition at line 41 of file chthreads.h.

Referenced by chCondWaitS(), chCondWaitTimeoutS(), and chMtxLockS().

#define THD_STATE_SLEEPING 6

Waiting in chThdSleep() or chThdSleepUntil().

Definition at line 43 of file chthreads.h.

#define THD_STATE_WTEXIT 7

Waiting in chThdWait().

Definition at line 45 of file chthreads.h.

Referenced by chThdWait().

#define THD_STATE_WTOREVT 8

Waiting for an event.

Definition at line 46 of file chthreads.h.

Referenced by chEvtSignalI(), chEvtWaitAny(), chEvtWaitAnyTimeout(), chEvtWaitOne(), and chEvtWaitOneTimeout().

#define THD_STATE_WTANDEVT 9

Waiting for several events.

Definition at line 47 of file chthreads.h.

Referenced by chEvtSignalI(), chEvtWaitAll(), and chEvtWaitAllTimeout().

#define THD_STATE_SNDMSGQ 10

Sending a message, in queue.

Definition at line 48 of file chthreads.h.

Referenced by chMsgSend(), and chMtxLockS().

#define THD_STATE_SNDMSG 11

Sent a message, waiting answer.

Definition at line 49 of file chthreads.h.

Referenced by chMsgRelease(), and chMsgWait().

#define THD_STATE_WTMSG 12

Waiting for a message.

Definition at line 51 of file chthreads.h.

Referenced by chMsgSend(), and chMsgWait().

#define THD_STATE_WTQUEUE 13

Waiting on an I/O queue.

Definition at line 52 of file chthreads.h.

#define THD_STATE_FINAL 14

Thread terminated.

Definition at line 53 of file chthreads.h.

Referenced by chSchReadyI(), chThdExitS(), chThdRelease(), and chThdWait().

#define THD_STATE_NAMES

Value:

"READY", "CURRENT", "SUSPENDED", "WTSEM", "WTMTX", "WTCOND", "SLEEPING",  \
  "WTEXIT", "WTOREVT", "WTANDEVT", "SNDMSGQ", "SNDMSG", "WTMSG", "WTQUEUE", \
  "FINAL"

Thread states as array of strings.

Each element in an array initialized with this macro can be indexed using the numeric thread state values.

Definition at line 60 of file chthreads.h.

#define THD_MEM_MODE_MASK 3

Thread memory mode mask.

Definition at line 70 of file chthreads.h.

Referenced by chThdExitS(), and chThdRelease().

#define THD_MEM_MODE_STATIC 0

Static thread.

Definition at line 71 of file chthreads.h.

Referenced by _thread_init(), and chThdExitS().

#define THD_MEM_MODE_HEAP 1

Thread allocated from a Memory Heap.

Definition at line 72 of file chthreads.h.

Referenced by chThdCreateFromHeap(), and chThdRelease().

#define THD_MEM_MODE_MEMPOOL 2

Thread allocated from a Memory Pool.

Definition at line 74 of file chthreads.h.

Referenced by chThdCreateFromMemoryPool(), and chThdRelease().

#define THD_TERMINATE 4

Termination requested flag.

Definition at line 76 of file chthreads.h.

Referenced by chThdTerminate().

#define chThdSelf ( ) currp

Returns a pointer to the current Thread.

Note:: Can be invoked in any context.

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 234 of file chthreads.h.

#define chThdGetPriority ( ) (currp->p_prio)

Returns the current thread priority.

Note:: Can be invoked in any context.

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 242 of file chthreads.h.

#define chThdGetTicks ( tp ) ((tp)->p_time)

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.; Can be invoked in any context.

Parameters:

[in] tp pointer to the thread

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 254 of file chthreads.h.

#define chThdLS ( ) (void *)(currp + 1)

Returns the pointer to the Thread local storage area, if any.

Note:: Can be invoked in any context.

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 262 of file chthreads.h.

#define chThdTerminated ( tp ) ((tp)->p_state == THD_STATE_FINAL)

Verifies if the specified thread is in the THD_STATE_FINAL state.

Note:: Can be invoked in any context.

Parameters:

[in] tp pointer to the thread

Return values:

TRUE	thread terminated.
FALSE	thread not terminated.

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 274 of file chthreads.h.

#define chThdShouldTerminate ( ) (currp->p_flags & THD_TERMINATE)

Verifies if the current thread has a termination request pending.

Note:: Can be invoked in any context.

Return values:

TRUE	termination request pending.
FALSE	termination request not pending.

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 285 of file chthreads.h.

#define chThdResumeI ( tp ) chSchReadyI(tp)

Resumes a thread created with chThdCreateI().

Parameters:

[in] tp pointer to the thread

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

#define chThdSleepS ( time ) chSchGoSleepTimeoutS(THD_STATE_SLEEPING, 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:: This is an S-Class API, this function can be invoked from within a system lock zone by threads only.

Definition at line 308 of file chthreads.h.

Referenced by chThdSleep(), and chThdSleepUntil().

#define chThdSleepSeconds ( sec ) chThdSleep(S2ST(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 clock.; The maximum specified value is implementation dependent.

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

#define chThdSleepMilliseconds ( msec ) chThdSleep(MS2ST(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 clock.; The maximum specified value is implementation dependent.

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

#define chThdSleepMicroseconds ( usec ) chThdSleep(US2ST(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 clock.; The maximum specified value is implementation dependent.

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

Typedef Documentation

typedef msg_t(* tfunc_t)(void *)

Thread function.

Definition at line 222 of file chthreads.h.

Detailed Description

Operation mode

Data Structures

Functions

Thread states

Thread flags and attributes

Macro Functions

Typedefs

Function Documentation

Define Documentation

Typedef Documentation