Furi: Furi Thread API. More...

#include "base.h"
#include "common_defines.h"
#include <stdint.h>
#include <stddef.h>

Typedefs
typedef struct FuriThread	FuriThread
	FuriThread opaque type.

typedef struct FuriThreadList	FuriThreadList
	FuriThreadList type.

typedef void *	FuriThreadId
	Unique thread identifier type (used by the OS kernel).

typedef int32_t(*	FuriThreadCallback) (void *context)
	Thread callback function pointer type.

typedef void(*	FuriThreadStdoutWriteCallback) (const char *data, size_t size)
	Standard output callback function pointer type.

typedef void(*	FuriThreadStateCallback) (FuriThread thread, FuriThreadState state, void context)
	State change callback function pointer type.

typedef bool(*	FuriThreadSignalCallback) (uint32_t signal, void arg, void context)
	Signal handler callback function pointer type.

Enumerations
enum	FuriThreadState { FuriThreadStateStopped , FuriThreadStateStopping , FuriThreadStateStarting , FuriThreadStateRunning }
	Enumeration of possible FuriThread states. More...

enum	FuriThreadPriority { FuriThreadPriorityIdle = 0 , FuriThreadPriorityInit = 4 , FuriThreadPriorityLowest = 14 , FuriThreadPriorityLow = 15 , FuriThreadPriorityNormal = 16 , FuriThreadPriorityHigh = 17 , FuriThreadPriorityHighest = 18 , FuriThreadPriorityIsr }
	Enumeration of possible FuriThread priorities. More...

Functions
FuriThread *	furi_thread_alloc (void)
	Create a FuriThread instance.

FuriThread *	furi_thread_alloc_service (const char name, uint32_t stack_size, FuriThreadCallback callback, void context)
	Create a FuriThread instance (service mode).

FuriThread *	furi_thread_alloc_ex (const char name, uint32_t stack_size, FuriThreadCallback callback, void context)
	Create a FuriThread instance w/ extra parameters.

void	furi_thread_free (FuriThread *thread)
	Delete a FuriThread instance.

void	furi_thread_set_name (FuriThread thread, const char name)
	Set the name of a FuriThread instance.

void	furi_thread_set_appid (FuriThread thread, const char appid)
	Set the application ID of a FuriThread instance.

void	furi_thread_set_stack_size (FuriThread *thread, size_t stack_size)
	Set the stack size of a FuriThread instance.

void	furi_thread_set_callback (FuriThread *thread, FuriThreadCallback callback)
	Set the user callback function to be executed in a FuriThread.

void	furi_thread_set_context (FuriThread thread, void context)
	Set the callback function context.

void	furi_thread_set_priority (FuriThread *thread, FuriThreadPriority priority)
	Set the priority of a FuriThread.

FuriThreadPriority	furi_thread_get_priority (FuriThread *thread)
	Get the priority of a FuriThread.

void	furi_thread_set_current_priority (FuriThreadPriority priority)
	Set the priority of the current FuriThread.

FuriThreadPriority	furi_thread_get_current_priority (void)
	Get the priority of the current FuriThread.

void	furi_thread_set_state_callback (FuriThread *thread, FuriThreadStateCallback callback)
	Set the callback function to be executed upon a state thransition of a FuriThread.

void	furi_thread_set_state_context (FuriThread thread, void context)
	Set the state change callback context.

FuriThreadState	furi_thread_get_state (FuriThread *thread)
	Get the state of a FuriThread isntance.

void	furi_thread_set_signal_callback (FuriThread thread, FuriThreadSignalCallback callback, void context)
	Set a signal handler callback for a FuriThread instance.

FuriThreadSignalCallback	furi_thread_get_signal_callback (const FuriThread *thread)
	Get a signal callback for a FuriThread instance.

bool	furi_thread_signal (const FuriThread thread, uint32_t signal, void arg)
	Send a signal to a FuriThread instance.

void	furi_thread_start (FuriThread *thread)
	Start a FuriThread instance.

bool	furi_thread_join (FuriThread *thread)
	Wait for a FuriThread to exit.

FuriThreadId	furi_thread_get_id (FuriThread *thread)
	Get the unique identifier of a FuriThread instance.

void	furi_thread_enable_heap_trace (FuriThread *thread)
	Enable heap usage tracing for a FuriThread.

void	furi_thread_disable_heap_trace (FuriThread *thread)
	Disable heap usage tracing for a FuriThread.

size_t	furi_thread_get_heap_size (FuriThread *thread)
	Get heap usage by a FuriThread instance.

int32_t	furi_thread_get_return_code (FuriThread *thread)
	Get the return code of a FuriThread instance.

FuriThreadId	furi_thread_get_current_id (void)
	Get the unique identifier of the current FuriThread.

FuriThread *	furi_thread_get_current (void)
	Get the FuriThread instance associated with the current thread.

void	furi_thread_yield (void)
	Return control to the scheduler.

uint32_t	furi_thread_flags_set (FuriThreadId thread_id, uint32_t flags)
	Set the thread flags of a FuriThread.

uint32_t	furi_thread_flags_clear (uint32_t flags)
	Clear the thread flags of the current FuriThread.

uint32_t	furi_thread_flags_get (void)
	Get the thread flags of the current FuriThread.

uint32_t	furi_thread_flags_wait (uint32_t flags, uint32_t options, uint32_t timeout)
	Wait for some thread flags to be set.

bool	furi_thread_enumerate (FuriThreadList *thread_list)
	Enumerate all threads.

const char *	furi_thread_get_name (FuriThreadId thread_id)
	Get the name of a thread based on its unique identifier.

const char *	furi_thread_get_appid (FuriThreadId thread_id)
	Get the application id of a thread based on its unique identifier.

uint32_t	furi_thread_get_stack_space (FuriThreadId thread_id)
	Get thread stack watermark.

FuriThreadStdoutWriteCallback	furi_thread_get_stdout_callback (void)
	Get the standard output callback for the current thead.

void	furi_thread_set_stdout_callback (FuriThreadStdoutWriteCallback callback)
	Set standard output callback for the current thread.

size_t	furi_thread_stdout_write (const char *data, size_t size)
	Write data to buffered standard output.

int32_t	furi_thread_stdout_flush (void)
	Flush buffered data to standard output.

void	furi_thread_suspend (FuriThreadId thread_id)
	Suspend a thread.

void	furi_thread_resume (FuriThreadId thread_id)
	Resume a thread.

bool	furi_thread_is_suspended (FuriThreadId thread_id)
	Test if a thread is suspended.

Detailed Description

Furi: Furi Thread API.

Typedef Documentation

◆ FuriThreadCallback

typedef int32_t(* FuriThreadCallback) (void *context)

Thread callback function pointer type.

The function to be used as a thread callback MUST follow this signature.

Parameters

[in,out] context pointer to a user-specified object

Returns: value to be used as the thread return code

◆ FuriThreadList

typedef struct FuriThreadList FuriThreadList

FuriThreadList type.

Anonymous FuriThreadList type.

◆ FuriThreadSignalCallback

typedef bool(* FuriThreadSignalCallback) (uint32_t signal, void *arg, void *context)

Signal handler callback function pointer type.

The function to be used as a signal handler callback MUS follow this signature.

Parameters

[in]	signal	value of the signal to be handled by the recipient
[in,out]	arg	optional argument (can be of any value, including NULL)
[in,out]	context	pointer to a user-specified object

Returns: true if the signal was handled, false otherwise

◆ FuriThreadStateCallback

typedef void(* FuriThreadStateCallback) (FuriThread *thread, FuriThreadState state, void *context)

State change callback function pointer type.

           The function to be used as a state callback MUST follow this
           signature.

Parameters

[in]	thread	to the FuriThread instance that changed the state
[in]	state	identifier of the state the thread has transitioned to
[in,out]	context	pointer to a user-specified object

◆ FuriThreadStdoutWriteCallback

typedef void(* FuriThreadStdoutWriteCallback) (const char *data, size_t size)

Standard output callback function pointer type.

The function to be used as a standard output callback MUST follow this signature.

Warning: The handler MUST process ALL of the provided data before returning.

Parameters

[in]	data	pointer to the data to be written to the standard out
[in]	size	size of the data in bytes

Enumeration Type Documentation

◆ FuriThreadPriority

enum FuriThreadPriority

Enumeration of possible FuriThread priorities.

Enumerator
FuriThreadPriorityIdle	Idle priority.
FuriThreadPriorityInit	Init System Thread Priority.
FuriThreadPriorityLowest	Lowest.
FuriThreadPriorityLow	Low.
FuriThreadPriorityNormal	Normal, system default.
FuriThreadPriorityHigh	High.
FuriThreadPriorityHighest	Highest.
FuriThreadPriorityIsr	Deferred ISR (highest possible)

◆ FuriThreadState

enum FuriThreadState

Enumeration of possible FuriThread states.

Many of the FuriThread functions MUST ONLY be called when the thread is STOPPED.

Enumerator
FuriThreadStateStopped	Thread is stopped and is safe to release. Event delivered from system init thread(TCB cleanup routine). It is safe to release thread instance.
FuriThreadStateStopping	Thread is stopping. Event delivered from child thread.
FuriThreadStateStarting	Thread is starting. Event delivered from parent(self) thread.
FuriThreadStateRunning	Thread is running. Event delivered from child thread.

Function Documentation

◆ furi_thread_alloc()

FuriThread * furi_thread_alloc ( void )

Create a FuriThread instance.

Returns: pointer to the created FuriThread instance

◆ furi_thread_alloc_ex()

FuriThread * furi_thread_alloc_ex	(	const char *	name,
		uint32_t	stack_size,
		FuriThreadCallback	callback,
		void *	context )

Create a FuriThread instance w/ extra parameters.

Parameters

[in]	name	human-readable thread name (can be NULL)
[in]	stack_size	stack size in bytes (can be changed later)
[in]	callback	pointer to a function to be executed in this thread
[in]	context	pointer to a user-specified object (will be passed to the callback)

Returns: pointer to the created FuriThread instance

◆ furi_thread_alloc_service()

FuriThread * furi_thread_alloc_service	(	const char *	name,
		uint32_t	stack_size,
		FuriThreadCallback	callback,
		void *	context )

Create a FuriThread instance (service mode).

Service threads are more memory efficient, but have the following limitations:

Cannot return from the callback
Cannot be joined or freed
Stack size cannot be altered

Parameters

[in]	name	human-readable thread name (can be NULL)
[in]	stack_size	stack size in bytes (cannot be changed later)
[in]	callback	pointer to a function to be executed in this thread
[in]	context	pointer to a user-specified object (will be passed to the callback)

Returns: pointer to the created FuriThread instance

◆ furi_thread_disable_heap_trace()

void furi_thread_disable_heap_trace ( FuriThread * thread )

Disable heap usage tracing for a FuriThread.

The thread MUST be stopped when calling this function.

Parameters

[in,out] thread pointer to the FuriThread instance to be modified

◆ furi_thread_enable_heap_trace()

void furi_thread_enable_heap_trace ( FuriThread * thread )

Enable heap usage tracing for a FuriThread.

The thread MUST be stopped when calling this function.

Parameters

[in,out] thread pointer to the FuriThread instance to be modified

◆ furi_thread_enumerate()

bool furi_thread_enumerate ( FuriThreadList * thread_list )

Enumerate all threads.

Parameters

[out] thread_list pointer to the FuriThreadList container

Returns: true on success, false otherwise

◆ furi_thread_flags_clear()

uint32_t furi_thread_flags_clear ( uint32_t flags )

Clear the thread flags of the current FuriThread.

Parameters

[in] flags bitmask of thread flags to clear

Returns: bitmask of thread flags before clearing

◆ furi_thread_flags_get()

uint32_t furi_thread_flags_get ( void )

Get the thread flags of the current FuriThread.

Returns: current bitmask of thread flags

◆ furi_thread_flags_set()

uint32_t furi_thread_flags_set	(	FuriThreadId	thread_id,
		uint32_t	flags )

Set the thread flags of a FuriThread.

Can be used as a simple inter-thread communication mechanism.

Parameters

[in]	thread_id	unique identifier of the thread to be notified
[in]	flags	bitmask of thread flags to set

Returns: bitmask combination of previous and newly set flags

◆ furi_thread_flags_wait()

uint32_t furi_thread_flags_wait	(	uint32_t	flags,
		uint32_t	options,
		uint32_t	timeout )

Wait for some thread flags to be set.

See also: FuriFlag for option and error flags.

Parameters

[in]	flags	bitmask of thread flags to wait for
[in]	options	combination of option flags determining the behavior of the function
[in]	timeout	maximum time to wait in milliseconds (use FuriWaitForever to wait forever)

Returns: bitmask combination of received thread and error flags

◆ furi_thread_free()

void furi_thread_free ( FuriThread * thread )

Delete a FuriThread instance.

The thread MUST be stopped when calling this function.

Warning: see furi_thread_join for caveats on stopping a thread.

Parameters

[in,out] thread pointer to the FuriThread instance to be deleted

◆ furi_thread_get_appid()

const char * furi_thread_get_appid ( FuriThreadId thread_id )

Get the application id of a thread based on its unique identifier.

Parameters

[in] thread_id unique identifier of the thread to be queried

Returns: pointer to a zero-terminated string

◆ furi_thread_get_current()

FuriThread * furi_thread_get_current ( void )

Get the FuriThread instance associated with the current thread.

Returns: pointer to a FuriThread instance or NULL if this thread does not belong to Furi

◆ furi_thread_get_current_id()

FuriThreadId furi_thread_get_current_id ( void )

Get the unique identifier of the current FuriThread.

Returns: unique identifier value

◆ furi_thread_get_current_priority()

FuriThreadPriority furi_thread_get_current_priority ( void )

Get the priority of the current FuriThread.

Returns: priority level value

◆ furi_thread_get_heap_size()

size_t furi_thread_get_heap_size ( FuriThread * thread )

Get heap usage by a FuriThread instance.

The heap trace MUST be enabled before callgin this function.

Parameters

[in] thread pointer to the FuriThread instance to be queried

Returns: heap usage in bytes

◆ furi_thread_get_id()

FuriThreadId furi_thread_get_id ( FuriThread * thread )

Get the unique identifier of a FuriThread instance.

Parameters

[in] thread pointer to the FuriThread instance to be queried

Returns: unique identifier value or NULL if thread is not running

◆ furi_thread_get_name()

const char * furi_thread_get_name ( FuriThreadId thread_id )

Get the name of a thread based on its unique identifier.

Parameters

[in] thread_id unique identifier of the thread to be queried

Returns: pointer to a zero-terminated string or NULL

◆ furi_thread_get_priority()

FuriThreadPriority furi_thread_get_priority ( FuriThread * thread )

Get the priority of a FuriThread.

Parameters

[in] thread pointer to the FuriThread instance to be queried

Returns: priority level value

◆ furi_thread_get_return_code()

int32_t furi_thread_get_return_code ( FuriThread * thread )

Get the return code of a FuriThread instance.

This value is equal to the return value of the thread callback function.

The thread MUST be stopped when calling this function.

Parameters

[in] thread pointer to the FuriThread instance to be queried

Returns: return code value

◆ furi_thread_get_signal_callback()

FuriThreadSignalCallback furi_thread_get_signal_callback ( const FuriThread * thread )

Get a signal callback for a FuriThread instance.

Parameters

[in] thread pointer to the FuriThread instance to be queried

Returns: pointer to the callback function or NULL if none has been set

◆ furi_thread_get_stack_space()

uint32_t furi_thread_get_stack_space ( FuriThreadId thread_id )

Get thread stack watermark.

Parameters

[in] thread_id unique identifier of the thread to be queried

Returns: stack watermark value

◆ furi_thread_get_state()

FuriThreadState furi_thread_get_state ( FuriThread * thread )

Get the state of a FuriThread isntance.

Parameters

[in] thread pointer to the FuriThread instance to be queried

Returns: thread state value

◆ furi_thread_get_stdout_callback()

FuriThreadStdoutWriteCallback furi_thread_get_stdout_callback ( void )

Get the standard output callback for the current thead.

Returns: pointer to the standard out callback function

◆ furi_thread_is_suspended()

bool furi_thread_is_suspended ( FuriThreadId thread_id )

Test if a thread is suspended.

Parameters

[in] thread_id unique identifier of the thread to be queried

Returns: true if thread is suspended, false otherwise

◆ furi_thread_join()

bool furi_thread_join ( FuriThread * thread )

Wait for a FuriThread to exit.

The thread callback function must return in order for the FuriThread instance to become joinable.

Warning: Use this method only when the CPU is not busy (i.e. when the Idle task receives control), otherwise it will wait forever.

Parameters

[in] thread pointer to the FuriThread instance to be joined

Returns: always true

◆ furi_thread_resume()

void furi_thread_resume ( FuriThreadId thread_id )

Resume a thread.

Parameters

[in] thread_id unique identifier of the thread to be resumed

◆ furi_thread_set_appid()

void furi_thread_set_appid	(	FuriThread *	thread,
		const char *	appid )

Set the application ID of a FuriThread instance.

The thread MUST be stopped when calling this function.

Technically, it is like a "process id", but it is not a system-wide unique identifier. All threads spawned by the same app will have the same appid.

Parameters

[in,out]	thread	pointer to the FuriThread instance to be modified
[in]	appid	thread application ID (can be NULL)

◆ furi_thread_set_callback()

void furi_thread_set_callback	(	FuriThread *	thread,
		FuriThreadCallback	callback )

Set the user callback function to be executed in a FuriThread.

The thread MUST be stopped when calling this function.

Parameters

[in,out]	thread	pointer to the FuriThread instance to be modified
[in]	callback	pointer to a user-specified function to be executed in this thread

◆ furi_thread_set_context()

void furi_thread_set_context	(	FuriThread *	thread,
		void *	context )

Set the callback function context.

The thread MUST be stopped when calling this function.

Parameters

[in,out]	thread	pointer to the FuriThread instance to be modified
[in]	context	pointer to a user-specified object (will be passed to the callback, can be NULL)

◆ furi_thread_set_current_priority()

void furi_thread_set_current_priority ( FuriThreadPriority priority )

Set the priority of the current FuriThread.

Parameters

priority priority level value

◆ furi_thread_set_name()

void furi_thread_set_name	(	FuriThread *	thread,
		const char *	name )

Set the name of a FuriThread instance.

The thread MUST be stopped when calling this function.

Parameters

[in,out]	thread	pointer to the FuriThread instance to be modified
[in]	name	human-readable thread name (can be NULL)

◆ furi_thread_set_priority()

void furi_thread_set_priority	(	FuriThread *	thread,
		FuriThreadPriority	priority )

Set the priority of a FuriThread.

The thread MUST be stopped when calling this function.

Parameters

[in,out]	thread	pointer to the FuriThread instance to be modified
[in]	priority	priority level value

◆ furi_thread_set_signal_callback()

void furi_thread_set_signal_callback	(	FuriThread *	thread,
		FuriThreadSignalCallback	callback,
		void *	context )

Set a signal handler callback for a FuriThread instance.

The thread MUST be stopped when calling this function if calling it from another thread.

Parameters

[in,out]	thread	pointer to the FuriThread instance to be modified
[in]	callback	pointer to a user-specified callback function
[in]	context	pointer to a user-specified object (will be passed to the callback, can be NULL)

◆ furi_thread_set_stack_size()

void furi_thread_set_stack_size	(	FuriThread *	thread,
		size_t	stack_size )

Set the stack size of a FuriThread instance.

The thread MUST be stopped when calling this function. Additionally, it is NOT possible to change the stack size of a service thread under any circumstances.

Parameters

[in,out]	thread	pointer to the FuriThread instance to be modified
[in]	stack_size	stack size in bytes

◆ furi_thread_set_state_callback()

void furi_thread_set_state_callback	(	FuriThread *	thread,
		FuriThreadStateCallback	callback )

Set the callback function to be executed upon a state thransition of a FuriThread.

The thread MUST be stopped when calling this function.

Parameters

[in,out]	thread	pointer to the FuriThread instance to be modified
[in]	callback	pointer to a user-specified callback function

◆ furi_thread_set_state_context()

void furi_thread_set_state_context	(	FuriThread *	thread,
		void *	context )

Set the state change callback context.

The thread MUST be stopped when calling this function.

Parameters

[in,out]	thread	pointer to the FuriThread instance to be modified
[in]	context	pointer to a user-specified object (will be passed to the callback, can be NULL)

◆ furi_thread_set_stdout_callback()

void furi_thread_set_stdout_callback ( FuriThreadStdoutWriteCallback callback )

Set standard output callback for the current thread.

Parameters

[in] callback pointer to the callback function or NULL to clear

◆ furi_thread_signal()

bool furi_thread_signal	(	const FuriThread *	thread,
		uint32_t	signal,
		void *	arg )

Send a signal to a FuriThread instance.

Parameters

[in]	thread	pointer to the FuriThread instance to be signaled
[in]	signal	signal value to be sent
[in,out]	arg	optional argument (can be of any value, including NULL)

◆ furi_thread_start()

void furi_thread_start ( FuriThread * thread )

Start a FuriThread instance.

The thread MUST be stopped when calling this function.

Parameters

[in,out] thread pointer to the FuriThread instance to be started

◆ furi_thread_stdout_flush()

int32_t furi_thread_stdout_flush ( void )

Flush buffered data to standard output.

Returns: error code value

◆ furi_thread_stdout_write()

size_t furi_thread_stdout_write	(	const char *	data,
		size_t	size )

Write data to buffered standard output.

Parameters

[in]	data	pointer to the data to be written
[in]	size	data size in bytes

Returns: number of bytes that was actually written

◆ furi_thread_suspend()

void furi_thread_suspend ( FuriThreadId thread_id )

Suspend a thread.

Suspended threads are no more receiving any of the processor time.

Parameters

[in] thread_id unique identifier of the thread to be suspended

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ FuriThreadCallback

◆ FuriThreadList

◆ FuriThreadSignalCallback

◆ FuriThreadStateCallback

◆ FuriThreadStdoutWriteCallback

Enumeration Type Documentation

◆ FuriThreadPriority

◆ FuriThreadState

Function Documentation

◆ furi_thread_alloc()

◆ furi_thread_alloc_ex()

◆ furi_thread_alloc_service()

◆ furi_thread_disable_heap_trace()

◆ furi_thread_enable_heap_trace()

◆ furi_thread_enumerate()

◆ furi_thread_flags_clear()

◆ furi_thread_flags_get()

◆ furi_thread_flags_set()

◆ furi_thread_flags_wait()

◆ furi_thread_free()

◆ furi_thread_get_appid()

◆ furi_thread_get_current()

◆ furi_thread_get_current_id()

◆ furi_thread_get_current_priority()

◆ furi_thread_get_heap_size()

◆ furi_thread_get_id()

◆ furi_thread_get_name()

◆ furi_thread_get_priority()

◆ furi_thread_get_return_code()

◆ furi_thread_get_signal_callback()

◆ furi_thread_get_stack_space()

◆ furi_thread_get_state()

◆ furi_thread_get_stdout_callback()

◆ furi_thread_is_suspended()

◆ furi_thread_join()

◆ furi_thread_resume()

◆ furi_thread_set_appid()

◆ furi_thread_set_callback()

◆ furi_thread_set_context()

◆ furi_thread_set_current_priority()

◆ furi_thread_set_name()

◆ furi_thread_set_priority()

◆ furi_thread_set_signal_callback()

◆ furi_thread_set_stack_size()

◆ furi_thread_set_state_callback()

◆ furi_thread_set_state_context()

◆ furi_thread_set_stdout_callback()

◆ furi_thread_signal()

◆ furi_thread_start()

◆ furi_thread_stdout_flush()

◆ furi_thread_stdout_write()

◆ furi_thread_suspend()