Threading

Managing threads and program execution. More...

Collaboration diagram for Threading:

Typedefs
typedef void(*	sys_thread_func_t) (void *arg)
	Thread function signatureFunction signature for thread entry points. More...

Functions
void	sys_abort (void)
	Aborts the current process immediately. More...
void	sys_panicf (const char *fmt,...)
	Prints a formatted panic message and aborts the process. More...
uint8_t	sys_thread_numcores (void)
	Returns the number of CPU cores available on the host system. More...
bool	sys_thread_create (sys_thread_func_t func, void *arg)
	Create a thread on any available core. More...
bool	sys_thread_create_on_core (sys_thread_func_t func, void *arg, uint8_t core)
	Create a thread on a specific core. More...
uint8_t	sys_thread_core (void)
	Get the CPU core number the current thread is running on. More...
void	sys_sleep (int32_t msec)
	Pauses the execution of the current thread for a specified time. More...

Detailed Description

Managing threads and program execution.

This module declares types and functions for thread management, including thread creation, synchronization, and communication. It is generally aware of the number of "cores" available on the system, and allows creating threads that can run on a specific core, or on any available core.

However, it really depends on the platform's capabilities and requirements. as to whether you should call sys_thread_create() or sys_thread_create_on_core(). On the Pico platform, for example, you should use sys_thread_create_on_core() to ensure the thread runs on a specific core. If you call this method when an existing thread is already running on that core, the core will be reset and the new thread will be scheduled to run on that core, so it's important to ensure that there isn't an existing thread already running on the specified core before calling this function.

The implementation of threads is like Go's goroutines, where the execution threads are "fire and forget" and do not require joining. If you wish to communicate between threads, use the event queue. If you wish to co-ordinate when threads are running or to synchronize their execution, you can use the provided synchronization primitives like waitgroups.

There are also methods for suspending the current thread for a specified duration, and for halting execution of the process immediately, in case of catastrophic failure.

Typedef Documentation

sys_thread_func_t

typedef void(* sys_thread_func_t) (void *arg)

Thread function signatureFunction signature for thread entry points.

The function receives a single void pointer argument and should not return a value. The thread terminates when this function returns.

Definition at line 52 of file thread.h.

Function Documentation

sys_abort()

void sys_abort

(

void

)

Aborts the current process immediately.

Note

This function does not return to the caller.

This function terminates the current process abnormally and immediately. It does not perform any cleanup operations and does not call exit handlers or destructors.

sys_panicf()

void sys_panicf	(	const char *	fmt,
			...
	)

Prints a formatted panic message and aborts the process.

Parameters

fmt	A printf-style format string specifying the panic message.
...	Additional arguments corresponding to format specifiers in fmt.

Note

This function does not return to the caller.

sys_sleep()

void sys_sleep

(

int32_t

msec

)

Pauses the execution of the current thread for a specified time.

Parameters

msec	The number of milliseconds to sleep.

Examples:

examples/runtime/led/main.c, examples/runtime/ntp/main.c, examples/runtime/watchdog/main.c, examples/runtime/wificonnect/main.c, and examples/runtime/wifiscan/main.c.

sys_thread_core()

uint8_t sys_thread_core

(

void

)

Get the CPU core number the current thread is running on.

Returns

The core number (0-based) that the current thread is executing on. Returns 0 if the core cannot be determined or on single-core systems.

This function queries the system to determine which CPU core the calling thread is currently scheduled on. Note that threads may migrate between cores, so this value may change over time unless thread affinity is set.

Examples:

examples/runtime/gpio/main.c.

sys_thread_create()

bool sys_thread_create	(	sys_thread_func_t	func,
		void *	arg
	)

Create a thread on any available core.

Parameters

func	Function to execute in the new thread
arg	Argument to pass to the thread function

Returns

true if thread was created successfully, false if no cores available or error

Creates a new thread that executes the specified function with the given argument. The thread runs independently and terminates when the function returns. No cleanup or joining is required - the thread is fire-and-forget. On systems with multiple cores, the thread may be scheduled on any available core.

sys_thread_create_on_core()

bool sys_thread_create_on_core	(	sys_thread_func_t	func,
		void *	arg,
		uint8_t	core
	)

Create a thread on a specific core.

Parameters

func	Function to execute in the new thread
arg	Argument to pass to the thread function
core	Core number to run the thread on (0-based)

Returns

true if thread was created on the specified core, false if core unavailable or error

Creates a new thread that executes the specified function on a specific CPU core. The thread runs independently and terminates when the function returns. If the specified core is not available or already in use, the function returns false. Core 0 is typically the main/boot core.

Examples:

examples/runtime/gpio/main.c.

sys_thread_numcores()

uint8_t sys_thread_numcores

(

void

)

Returns the number of CPU cores available on the host system.

Returns

The number of CPU cores available on the system. Returns 1 if the number of cores cannot be determined or if the system has only one core.

This function queries the system to determine the total number of processing cores available.