Collaboration diagram for Threads:

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:

Init, a thread is prepared and put in the suspended state.
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...
Defines
#define	THD_STATE_READY 0
	Thread state: Ready to run, waiting on the ready list.
#define	THD_STATE_CURRENT 1
	Thread state: Currently running.
#define	THD_STATE_SUSPENDED 2
	Thread state: Thread created in suspended state.
#define	THD_STATE_WTSEM 3
	Thread state: Waiting on a semaphore.
#define	THD_STATE_WTMTX 4
	Thread state: Waiting on a mutex.
#define	THD_STATE_WTCOND 5
	Thread state: Waiting in `chCondWait()`.
#define	THD_STATE_SLEEPING 6
	Thread state: Waiting in `chThdSleep()` or `chThdSleepUntil()`.
#define	THD_STATE_WTEXIT 7
	Thread state: Waiting in `chThdWait()`.
#define	THD_STATE_WTOREVT 8
	Thread state: Waiting in `chEvtWaitXXX()`.
#define	THD_STATE_WTANDEVT 9
	Thread state: Waiting in `chEvtWaitAllTimeout()`.
#define	THD_STATE_SNDMSG 10
	Thread state: Waiting in `chMsgSend()`.
#define	THD_STATE_WTMSG 11
	Thread state: Waiting in `chMsgWait()`.
#define	THD_STATE_FINAL 12
	Thread state: After termination.
#define	THD_MEM_MODE_MASK 3
	Thread memory mode mask.
#define	THD_MEM_MODE_STATIC 0
	Thread memory mode: static.
#define	THD_MEM_MODE_HEAP 1
	Thread memory mode: heap.
#define	THD_MEM_MODE_MEMPOOL 2
	Thread memory mode: pool.
#define	THD_TERMINATE 4
	Termination requested.
#define	chThdSelf() currp
	Returns a pointer to the current `Thread`.
#define	chThdGetPriority() (currp->p_prio)
	Returns the current thread priority.
#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 `chThdInit()`.
#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.
Functions
Thread *	init_thread (Thread *tp, tprio_t prio)
	Initializes a thread structure.
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.
Thread *	chThdCreateFromHeap (MemoryHeap heapp, size_t size, tprio_t prio, tfunc_t pf, void arg)
	Creates a new thread allocating the memory from the heap.
Thread *	chThdCreateFromMemoryPool (MemoryPool mp, tprio_t prio, tfunc_t pf, void arg)
	Creates a new thread allocating the memory from the specified memory pool.
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 by specifying an exit status code.
Thread *	chThdAddRef (Thread *tp)
	Adds a reference to a thread object.
void	chThdRelease (Thread *tp)
	Releases a reference to a thread object.
msg_t	chThdWait (Thread *tp)
	Blocks the execution of the invoking thread until the specified thread terminates then the exit code is returned.

Define Documentation

#define THD_STATE_READY 0

Thread state: Ready to run, waiting on the ready list.

Definition at line 175 of file chthreads.h.

Referenced by chMtxLockS().

#define THD_STATE_CURRENT 1

Thread state: Currently running.

Definition at line 177 of file chthreads.h.

#define THD_STATE_SUSPENDED 2

Thread state: Thread created in suspended state.

Definition at line 179 of file chthreads.h.

Referenced by chThdResume().

#define THD_STATE_WTSEM 3

Thread state: Waiting on a semaphore.

Definition at line 181 of file chthreads.h.

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

#define THD_STATE_WTMTX 4

Thread state: Waiting on a mutex.

Definition at line 183 of file chthreads.h.

Referenced by chMtxLockS().

#define THD_STATE_WTCOND 5

Thread state: Waiting in chCondWait().

Definition at line 185 of file chthreads.h.

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

#define THD_STATE_SLEEPING 6

Thread state: Waiting in chThdSleep() or chThdSleepUntil().

Definition at line 187 of file chthreads.h.

#define THD_STATE_WTEXIT 7

Thread state: Waiting in chThdWait().

Definition at line 189 of file chthreads.h.

Referenced by chThdWait().

#define THD_STATE_WTOREVT 8

Thread state: Waiting in chEvtWaitXXX().

Definition at line 191 of file chthreads.h.

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

#define THD_STATE_WTANDEVT 9

Thread state: Waiting in chEvtWaitAllTimeout().

Definition at line 193 of file chthreads.h.

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

#define THD_STATE_SNDMSG 10

Thread state: Waiting in chMsgSend().

Definition at line 195 of file chthreads.h.

Referenced by chMsgSend(), and chMtxLockS().

#define THD_STATE_WTMSG 11

Thread state: Waiting in chMsgWait().

Definition at line 197 of file chthreads.h.

Referenced by chMsgSend(), and chMsgWait().

#define THD_STATE_FINAL 12

Thread state: After termination.

Definition at line 199 of file chthreads.h.

Referenced by chThdExit(), chThdRelease(), and chThdWait().

#define THD_MEM_MODE_MASK 3

Thread memory mode mask.

Definition at line 204 of file chthreads.h.

Referenced by chThdExit(), and chThdRelease().

#define THD_MEM_MODE_STATIC 0

Thread memory mode: static.

Definition at line 205 of file chthreads.h.

Referenced by chThdExit().

#define THD_MEM_MODE_HEAP 1

Thread memory mode: heap.

Definition at line 206 of file chthreads.h.

Referenced by chThdRelease().

#define THD_MEM_MODE_MEMPOOL 2

Thread memory mode: pool.

Definition at line 207 of file chthreads.h.

Referenced by chThdRelease().

#define THD_TERMINATE 4

Termination requested.

Definition at line 208 of file chthreads.h.

#define chThdSelf ( ) currp

Returns a pointer to the current Thread.

Definition at line 253 of file chthreads.h.

#define chThdGetPriority ( ) (currp->p_prio)

Returns the current thread priority.

Definition at line 258 of file chthreads.h.

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

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

Definition at line 263 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.

Parameters:

[in] tp the pointer to the thread

Return values:

	TRUE	thread terminated.
	FALSE	thread not terminated.

Definition at line 272 of file chthreads.h.

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

Verifies if the current thread has a termination request pending.

Return values:

	TRUE	termination request pended.
	FALSE	termination request not pended.

Definition at line 280 of file chthreads.h.

#define chThdResumeI ( tp ) chSchReadyI(tp)

Resumes a thread created with chThdInit().

Parameters:

[in] tp the pointer to the thread

Definition at line 287 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 accepted but interpreted as a normal time specification not as an immediate timeout specification.

Definition at line 301 of file chthreads.h.

Referenced by canStart(), 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 the time in seconds

Definition at line 311 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 the time in milliseconds

Definition at line 322 of file chthreads.h.

Referenced by mmcConnect().

#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 the time in microseconds

Definition at line 333 of file chthreads.h.

Typedef Documentation

typedef msg_t(* tfunc_t)(void *)

Thread function.

Definition at line 211 of file chthreads.h.

Function Documentation

Thread * init_thread	(	Thread *	tp,
		tprio_t	prio
	)

Initializes a thread structure.

Parameters:

`[in]`	tp	pointer to the thread
`[in]`	prio	the priority level for the new thread

Returns:: The same thread pointer passed as parameter.

Definition at line 74 of file chthreads.c.

References list_init, Thread::p_epending, Thread::p_flags, Thread::p_msgqueue, Thread::p_mtxlist, Thread::p_prio, Thread::p_realprio, Thread::p_refs, Thread::p_state, Thread::p_time, Thread::p_waiting, queue_init, REG_INSERT, and THREAD_EXT_INIT.

Referenced by chSysInit(), and chThdCreateI().

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.

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.

Definition at line 137 of file chthreads.c.

References chDbgCheck, HIGHPRIO, init_thread(), 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.

Definition at line 163 of file chthreads.c.

References chSchWakeupS(), chSysLock, chSysUnlock, chThdCreateI(), RDY_OK, STACK_FILL_VALUE, and THREAD_FILL_VALUE.

Referenced by chibios_rt::BaseThread::BaseThread(), and chSysInit().

Here is the call graph for this function:

Thread * chThdCreateFromHeap	(	MemoryHeap *	heapp,
		size_t	size,
		tprio_t	prio,
		tfunc_t	pf,
		void *	arg
	)

Creates a new thread allocating the memory from the heap.

Note:: A thread can terminate by calling chThdExit() or by simply returning from its main function.; The memory allocated for the thread is not released when the thread terminates but when a chThdWait() is performed.; The function is available only if the CH_USE_DYNAMIC, CH_USE_HEAP and CH_USE_WAITEXIT options are enabled in chconf.h.

Parameters:

`[in]`	heapp	heap from which allocate the memory or `NULL` for the default heap
`[in]`	size	size of the working area to be allocated
`[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.

Return values:

NULL

if the memory cannot be allocated.

Definition at line 200 of file chthreads.c.

References chHeapAlloc(), chSchWakeupS(), chSysLock, chSysUnlock, chThdCreateI(), Thread::p_flags, RDY_OK, STACK_FILL_VALUE, and THREAD_FILL_VALUE.

Here is the call graph for this function:

Thread * chThdCreateFromMemoryPool	(	MemoryPool *	mp,
		tprio_t	prio,
		tfunc_t	pf,
		void *	arg
	)

Creates a new thread allocating the memory from the specified memory pool.

Note:: A thread can terminate by calling chThdExit() or by simply returning from its main function.; The memory allocated for the thread is not released when the thread terminates but when a chThdWait() is performed.; The function is available only if the CH_USE_DYNAMIC, CH_USE_MEMPOOLS and CH_USE_WAITEXIT options are enabled in chconf.h.

Parameters:

`[in]`	mp	pointer to the memory pool object
`[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.

Return values:

NULL

if the memory pool is empty.

Definition at line 245 of file chthreads.c.

References chDbgCheck, chPoolAlloc(), chSchWakeupS(), chSysLock, chSysUnlock, chThdCreateI(), MemoryPool::mp_object_size, Thread::p_flags, Thread::p_mpool, RDY_OK, STACK_FILL_VALUE, and THREAD_FILL_VALUE.

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.

Definition at line 282 of file chthreads.c.

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

Referenced by chibios_rt::BaseThread::SetPriority().

Here is the call graph for this function:

Thread * chThdResume ( Thread * tp )

Resumes a suspended thread.

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

Parameters:

[in] tp pointer to the thread

Returns:: The pointer to the thread.

Definition at line 310 of file chthreads.c.

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

Referenced by chibios_rt::BaseThread::Resume().

Here is the call graph for this function:

void chThdTerminate ( Thread * tp )

Requests a thread termination.

Note:: The thread is not terminated but a termination request is added to its p_flags field. The thread can read this status by invoking chThdShouldTerminate() and then terminate cleanly.

Parameters:

[in] tp pointer to the thread

Definition at line 329 of file chthreads.c.

References chSysLock, chSysUnlock, and Thread::p_flags.

Referenced by chibios_rt::BaseThread::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 accepted but interpreted as a normal time specification not as an immediate timeout specification.

Definition at line 348 of file chthreads.c.

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

Referenced by chibios_rt::BaseThread::Sleep().

void chThdSleepUntil ( systime_t time )

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

Parameters:

[in] time absolute system time

Definition at line 363 of file chthreads.c.

References chSysLock, chSysUnlock, chThdSleepS, and chTimeNow.

Referenced by chibios_rt::BaseThread::SleepUntil().

void chThdYield ( void )

Yields the time slot.

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

Definition at line 376 of file chthreads.c.

References chSchDoYieldS, chSysLock, and chSysUnlock.

void chThdExit ( msg_t msg )

Terminates the current thread by specifying an exit status code.

Parameters:

[in] msg thread exit code. The code can be retrieved by using chThdWait().

Definition at line 389 of file chthreads.c.

References chSchGoSleepS(), chSchReadyI(), chSysLock, Thread::exitcode, list_remove(), notempty, Thread::p_flags, Thread::p_u, Thread::p_waiting, REG_REMOVE, THD_MEM_MODE_MASK, THD_MEM_MODE_STATIC, THD_STATE_FINAL, and THREAD_EXT_EXIT.

Referenced by chibios_rt::BaseThread::Exit().

Here is the call graph for this function:

Thread * chThdAddRef ( Thread * tp )

Adds a reference to a thread object.

Parameters:

[in] tp pointer to the thread

Returns:: The same thread pointer passed as parameter representing the new reference.

Definition at line 418 of file chthreads.c.

References chDbgAssert, chSysLock, chSysUnlock, and Thread::p_refs.

void chThdRelease ( Thread * tp )

Releases a reference to a thread object.

If the references counter reaches zero and the thread is in the THD_STATE_FINAL state then the thread's memory is returned to the proper allocator.

Note:: Static threads are not affected.

Parameters:

[in] tp pointer to the thread

Definition at line 436 of file chthreads.c.

References chDbgAssert, chHeapFree(), chPoolFree(), chSysLock, chSysUnlock, Thread::p_flags, Thread::p_mpool, Thread::p_refs, Thread::p_state, REG_REMOVE, THD_MEM_MODE_HEAP, THD_MEM_MODE_MASK, THD_MEM_MODE_MEMPOOL, and THD_STATE_FINAL.

Referenced by chRegNextThread(), and chThdWait().

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.

Please read the Threads Lifecycle article for more details.

Note:: After invoking chThdWait() the thread pointer becomes invalid and must not be used as parameter for further system calls.; The function is available only if the CH_USE_WAITEXIT option is enabled in chconf.h.; 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.

Definition at line 499 of file chthreads.c.

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

Referenced by chibios_rt::BaseThread::Wait().

Here is the call graph for this function:

Threads [Base Kernel Services]

Description

Operation mode

Data Structures

Defines

Typedefs

Functions

Define Documentation

Typedef Documentation

Function Documentation

Threads
[Base Kernel Services]