Loading...
Searching...
No Matches
thread.h File Reference

Furi: Furi Thread API. More...

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

Go to the source code of this file.

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

FuriThreadfuri_thread_alloc (void)
 Create a FuriThread instance.
 
FuriThreadfuri_thread_alloc_service (const char *name, uint32_t stack_size, FuriThreadCallback callback, void *context)
 Create a FuriThread instance (service mode).
 
FuriThreadfuri_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.
 
FuriThreadfuri_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]contextpointer to a user-specified object
Returns
value to be used as the thread return code

◆ 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]signalvalue of the signal to be handled by the recipient
[in,out]argoptional argument (can be of any value, including NULL)
[in,out]contextpointer 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]threadto the FuriThread instance that changed the state
[in]stateidentifier of the state the thread has transitioned to
[in,out]contextpointer 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]datapointer to the data to be written to the standard out
[in]sizesize of the data in bytes

Enumeration Type Documentation

◆ 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

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]namehuman-readable thread name (can be NULL)
[in]stack_sizestack size in bytes (can be changed later)
[in]callbackpointer to a function to be executed in this thread
[in]contextpointer 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]namehuman-readable thread name (can be NULL)
[in]stack_sizestack size in bytes (cannot be changed later)
[in]callbackpointer to a function to be executed in this thread
[in]contextpointer 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]threadpointer 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]threadpointer to the FuriThread instance to be modified

◆ furi_thread_enumerate()

bool furi_thread_enumerate ( FuriThreadList * thread_list)

Enumerate all threads.

Parameters
[out]thread_listpointer 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]flagsbitmask 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_idunique identifier of the thread to be notified
[in]flagsbitmask 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]flagsbitmask of thread flags to wait for
[in]optionscombination of option flags determining the behavior of the function
[in]timeoutmaximum 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]threadpointer 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_idunique 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]threadpointer 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]threadpointer 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_idunique 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]threadpointer 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]threadpointer 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]threadpointer 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_idunique 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]threadpointer 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_idunique 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]threadpointer 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_idunique 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]threadpointer to the FuriThread instance to be modified
[in]appidthread 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]threadpointer to the FuriThread instance to be modified
[in]callbackpointer 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]threadpointer to the FuriThread instance to be modified
[in]contextpointer 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
prioritypriority 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]threadpointer to the FuriThread instance to be modified
[in]namehuman-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]threadpointer to the FuriThread instance to be modified
[in]prioritypriority 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]threadpointer to the FuriThread instance to be modified
[in]callbackpointer to a user-specified callback function
[in]contextpointer 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]threadpointer to the FuriThread instance to be modified
[in]stack_sizestack 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]threadpointer to the FuriThread instance to be modified
[in]callbackpointer 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]threadpointer to the FuriThread instance to be modified
[in]contextpointer 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]callbackpointer 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]threadpointer to the FuriThread instance to be signaled
[in]signalsignal value to be sent
[in,out]argoptional 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]threadpointer 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]datapointer to the data to be written
[in]sizedata 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_idunique identifier of the thread to be suspended