C API thread definitions. More...

Classes
struct	os_thread_attr_s
	Thread attributes. More...

struct	os_thread_context_s
	Thread context. More...

struct	os_thread_s
	Thread object storage. More...

struct	os_thread_stack_s
	Thread stack. More...

struct	os_thread_statistics_s
	Thread statistics. More...

Typedefs
typedef struct os_thread_attr_s	os_thread_attr_t
	Thread attributes.

typedef struct os_thread_context_s	os_thread_context_t
	Thread context.

typedef void *	os_thread_func_args_t
	Type of thread function arguments.

typedef void (	os_thread_func_t) (os_thread_func_args_t args)
	Type of thread function.

typedef uint8_t	os_thread_prio_t
	Type of variables holding thread priorities.

typedef os_port_thread_stack_allocation_element_t	os_thread_stack_allocation_element_t
	Type of variables holding aligned stack elements.

typedef os_port_thread_stack_element_t	os_thread_stack_element_t
	Type of variables holding stack words.

typedef struct os_thread_stack_s	os_thread_stack_t
	Thread stack.

typedef uint8_t	os_thread_state_t
	Type of variables holding thread states.

typedef struct os_thread_statistics_s	os_thread_statistics_t
	Thread statistics.

typedef struct os_thread_s	os_thread_t
	Thread object storage.

Enumerations
enum	{ os_thread_priority_none = 0 , os_thread_priority_idle = (1 << (4) ) , os_thread_priority_lowest = (2 << (4) ) , os_thread_priority_low = (2 << (4) ) , os_thread_priority_below_normal = (4 << (4) ) , os_thread_priority_normal = (6 << (4) ) , os_thread_priority_above_normal = (8 << (4) ) , os_thread_priority_high = (10 << (4) ) , os_thread_priority_realtime = (12 << (4) ) , os_thread_priority_highest = (((13 + 1) << (4) ) - 1) , os_thread_priority_isr = (((14 + 1) << (4) ) - 1) , os_thread_priority_error = (((15 + 1) << (4) ) - 1) }
	Thread priorities; intermediate values are also possible. More...

enum	{ os_thread_state_undefined = 0 , os_thread_state_ready = 1 , os_thread_state_running = 2 , os_thread_state_suspended = 3 , os_thread_state_terminated = 4 , os_thread_state_destroyed = 5 , os_thread_state_initialising = 6 }
	An enumeration with all possible thread states. More...

Current Thread Functions
os_thread_t *	os_this_thread (void)
	Get the current running thread.

void	os_this_thread_suspend (void)
	Suspend the current running thread to wait for an event.

void	os_this_thread_exit (void *exit_ptr)
	Terminate the current running thread.

os_result_t	os_this_thread_flags_wait (os_flags_mask_t mask, os_flags_mask_t *oflags, os_flags_mode_t mode)
	Wait for thread event flags.

os_result_t	os_this_thread_flags_try_wait (os_flags_mask_t mask, os_flags_mask_t *oflags, os_flags_mode_t mode)
	Try to wait for thread event flags.

os_result_t	os_this_thread_flags_timed_wait (os_flags_mask_t mask, os_clock_duration_t timeout, os_flags_mask_t *oflags, os_flags_mode_t mode)
	Timed wait for thread event flags.

os_result_t	os_this_thread_flags_clear (os_flags_mask_t mask, os_flags_mask_t *oflags)
	Clear thread event flags.

os_flags_mask_t	os_this_thread_flags_get (os_flags_mask_t mask, os_flags_mode_t mode)
	Get/clear thread event flags.

Thread Attribute Functions
void	os_thread_attr_init (os_thread_attr_t *attr)
	Initialise the thread attributes.

Thread Creation Functions
void	os_thread_construct (os_thread_t thread, const char name, os_thread_func_t func, const os_thread_func_args_t args, const os_thread_attr_t *attr)
	Construct a statically allocated thread object instance.

void	os_thread_destruct (os_thread_t *thread)
	Destruct the statically allocated thread object instance.

os_thread_t *	os_thread_new (const char name, os_thread_func_t func, const os_thread_func_args_t args, const os_thread_attr_t attr)
	Allocate a thread object instance and construct it.

void	os_thread_delete (os_thread_t *thread)
	Destruct the thread object instance and deallocate it.

bool	os_thread_is_constructed (os_thread_t *thread)
	Check if the thread is constructed.

Thread Functions
const char *	os_thread_get_name (os_thread_t *thread)
	Get the thread name.

os_thread_prio_t	os_thread_get_priority (os_thread_t *thread)
	Get the thread current scheduling priority.

os_result_t	os_thread_set_priority (os_thread_t *thread, os_thread_prio_t prio)
	Set the thread dynamic scheduling priority.

os_result_t	os_thread_kill (os_thread_t *thread)
	Force thread termination.

os_result_t	os_thread_join (os_thread_t thread, void *exit_ptr)
	Wait for thread termination.

void	os_thread_resume (os_thread_t *thread)
	Resume the thread.

os_result_t	os_thread_flags_raise (os_thread_t thread, os_flags_mask_t mask, os_flags_mask_t oflags)
	Raise thread event flags.

os_thread_state_t	os_thread_get_state (os_thread_t *thread)
	Get the thread scheduler state.

os_thread_user_storage_t *	os_thread_get_user_storage (os_thread_t *thread)
	Get the thread user storage.

os_thread_stack_t *	os_thread_get_stack (os_thread_t *thread)
	Get the thread context stack.

Thread Stack Functions
size_t	os_thread_stack_get_default_size (void)
	Get the default stack size.

size_t	os_thread_stack_set_default_size (size_t size_bytes)
	Set the default stack size.

size_t	os_thread_stack_get_min_size (void)
	Get the min stack size.

size_t	os_thread_stack_set_min_size (size_t size_bytes)
	Set the min stack size.

os_thread_stack_element_t *	os_thread_stack_get_bottom (os_thread_stack_t *stack)
	Get the stack lowest reserved address.

os_thread_stack_element_t *	os_thread_stack_get_top (os_thread_stack_t *stack)
	Get the top stack address.

size_t	os_thread_stack_get_size (os_thread_stack_t *stack)
	Get the stack size.

size_t	os_thread_stack_get_available (os_thread_stack_t *stack)
	Compute how much available stack remains.

bool	os_thread_stack_check_bottom_magic (os_thread_stack_t *stack)
	Check if bottom magic word is still there.

bool	os_thread_stack_check_top_magic (os_thread_stack_t *stack)
	Check if top magic word is still there.

Thread Statistics Functions
os_statistics_counter_t	os_thread_stat_get_context_switches (os_thread_t *thread)
	Get the number of thread context switches.

os_statistics_duration_t	os_thread_stat_get_cpu_cycles (os_thread_t *thread)
	Get the thread execution time.

Thread Children Iterator Functions
os_iterator_t	os_children_threads_iter_begin (os_thread_t *thread)
	Get the beginning of the list of children threads.

os_iterator_t	os_children_threads_iter_end (os_thread_t *thread)
	Get the end of the list of children threads.

os_thread_t *	os_children_threads_iter_get (os_iterator_t iterator)
	Get the thread from the current iterator position.

os_iterator_t	os_children_threads_iter_next (os_iterator_t iterator)
	Advance the iterator to the next position.

Compatibility Macros
#define	os_thread_create os_thread_construct

#define	os_thread_destroy os_thread_destruct

#define	os_timer_create os_timer_construct

#define	os_timer_destroy os_timer_destruct

#define	os_mutex_create os_mutex_construct

#define	os_mutex_recursive_create os_mutex_recursive_construct

#define	os_mutex_destroy os_mutex_destruct

#define	os_condvar_create os_condvar_construct

#define	os_condvar_destroy os_condvar_destruct

#define	os_semaphore_create os_semaphore_construct

#define	os_semaphore_binary_create os_semaphore_binary_construct

#define	os_semaphore_counting_create os_semaphore_counting_construct

#define	os_semaphore_destroy os_semaphore_destruct

#define	os_mempool_create os_mempool_construct

#define	os_mempool_destroy os_mempool_destruct

#define	os_mqueue_create os_mqueue_construct

#define	os_mqueue_destroy os_mqueue_destruct

#define	os_evflags_create os_evflags_construct

#define	os_evflags_destroy os_evflags_destruct

Detailed Description

C API thread definitions.

For the complete definition, see: RTOS C++ API

Examples

void*
func (void* args 
{
  printf ("%s\n", __func__);
 
  return NULL;
}
 
int
os_main (int argc, char* argv[])
{
    {
      // Unnamed default thread; stack dynamically allocated.
      os_thread_t th1;
      os_thread_construct (&th1, NULL, func, NULL, NULL);
 
      name = os_thread_get_name (&th1);
 
      os_thread_join (&th1, NULL);
 
      // The destroy() is recommended, but not mandatory when using join().
      // The test checks if join() fully destroys the thread.
      os_thread_destruct(&th1);
    }
 
    {
      // Named default threads.
      os_thread_t th2;
      os_thread_construct (&th2, "th2", func, NULL, NULL);
 
      os_thread_join (&th2, NULL);
 
      os_thread_destruct(&th2);
    }
 
    {
      // Custom thread with static stack and lower priority.
      static char stack[2 * OS_INTEGER_RTOS_DEFAULT_STACK_SIZE_BYTES];
 
      os_thread_attr_t ath3;
      os_thread_attr_init (&ath3);
      ath3.th_priority = os_thread_priority_below_normal;
      ath3.th_stack_address = stack;
      ath3.th_stack_size_bytes = sizeof(stack);
 
      os_thread_t th3;
      os_thread_construct (&th3, "th3", func, NULL, &ath3);
 
      os_thread_prio_t prio;
      prio = os_thread_get_priority (&th3);
      os_thread_set_priority (os_this_thread (), prio);
 
      // Lower main thread priority to allow task to run.
      os_thread_set_priority (os_this_thread (), os_thread_priority_below_normal);
 
      os_thread_join (&th3, NULL);
 
      // Restore main thread priority.
      os_thread_set_priority (os_this_thread (), os_thread_priority_normal);
 
      os_thread_destruct(&th3);
    }
 
    {
      os_this_thread_flags_clear (os_flags_all, NULL);
 
      os_thread_flags_raise (os_this_thread (), 0x3, NULL);
      os_this_thread_flags_wait (0x3, NULL, os_flags_mode_all);
 
      os_thread_flags_raise (os_this_thread (), 0x3, NULL);
      os_this_thread_flags_try_wait (0x3, NULL, os_flags_mode_all);
 
      os_thread_flags_raise (os_this_thread (), 0x3, NULL);
      os_this_thread_flags_timed_wait (0x3, 10, NULL, os_flags_mode_all);
    }
 
    {
      size_t n;
 
      n = os_thread_stack_get_default_size ();
      os_thread_stack_set_default_size (n);
 
      n = os_thread_stack_get_min_size ();
      os_thread_stack_set_min_size (n);
 
      os_thread_stack_t* stack;
      stack = os_thread_get_stack (os_this_thread ());
 
      os_thread_stack_get_bottom (stack);
 
      os_thread_stack_get_top (stack);
 
      os_thread_stack_check_bottom_magic (stack);
      os_thread_stack_check_top_magic (stack);
    }
}

Macro Definition Documentation

◆ os_condvar_create

#define os_condvar_create os_condvar_construct

Definition at line 1652 of file os-c-api.h.

◆ os_condvar_destroy

#define os_condvar_destroy os_condvar_destruct

Definition at line 1653 of file os-c-api.h.

◆ os_evflags_create

#define os_evflags_create os_evflags_construct

Definition at line 2642 of file os-c-api.h.

◆ os_evflags_destroy

#define os_evflags_destroy os_evflags_destruct

Definition at line 2643 of file os-c-api.h.

◆ os_mempool_create

#define os_mempool_create os_mempool_construct

Definition at line 2132 of file os-c-api.h.

◆ os_mempool_destroy

#define os_mempool_destroy os_mempool_destruct

Definition at line 2133 of file os-c-api.h.

◆ os_mqueue_create

#define os_mqueue_create os_mqueue_construct

Definition at line 2428 of file os-c-api.h.

◆ os_mqueue_destroy

#define os_mqueue_destroy os_mqueue_destruct

Definition at line 2429 of file os-c-api.h.

◆ os_mutex_create

#define os_mutex_create os_mutex_construct

Definition at line 1459 of file os-c-api.h.

◆ os_mutex_destroy

#define os_mutex_destroy os_mutex_destruct

Definition at line 1461 of file os-c-api.h.

◆ os_mutex_recursive_create

#define os_mutex_recursive_create os_mutex_recursive_construct

Definition at line 1460 of file os-c-api.h.

◆ os_semaphore_binary_create

#define os_semaphore_binary_create os_semaphore_binary_construct

Definition at line 1926 of file os-c-api.h.

◆ os_semaphore_counting_create

#define os_semaphore_counting_create os_semaphore_counting_construct

Definition at line 1927 of file os-c-api.h.

◆ os_semaphore_create

#define os_semaphore_create os_semaphore_construct

Definition at line 1925 of file os-c-api.h.

◆ os_semaphore_destroy

#define os_semaphore_destroy os_semaphore_destruct

Definition at line 1928 of file os-c-api.h.

◆ os_thread_create

#define os_thread_create os_thread_construct

Definition at line 625 of file os-c-api.h.

◆ os_thread_destroy

#define os_thread_destroy os_thread_destruct

Definition at line 626 of file os-c-api.h.

◆ os_timer_create

#define os_timer_create os_timer_construct

Definition at line 1158 of file os-c-api.h.

◆ os_timer_destroy

#define os_timer_destroy os_timer_destruct

Definition at line 1159 of file os-c-api.h.

Typedef Documentation

◆ os_thread_attr_t

typedef struct os_thread_attr_s os_thread_attr_t

Thread attributes.

Initialise this structure with os_thread_attr_init(), and then set any of the individual members directly.

See also: os::rtos::thread::attributes

◆ os_thread_context_t

typedef struct os_thread_context_s os_thread_context_t

Thread context.

The members of this structure are hidden and should not be accessed directly, but through associated functions.

See also: os::rtos::thread::context

◆ os_thread_func_args_t

typedef void* os_thread_func_args_t

Type of thread function arguments.

Useful to cast other similar types to silence possible compiler warnings.

See also: os::rtos::thread::func_args_t

Definition at line 330 of file os-c-decls.h.

◆ os_thread_func_t

typedef void *(* os_thread_func_t) (os_thread_func_args_t args)

Type of thread function.

Useful to cast other similar types to silence possible compiler warnings.

See also: os::rtos::thread::func_t

Definition at line 341 of file os-c-decls.h.

◆ os_thread_prio_t

typedef uint8_t os_thread_prio_t

Type of variables holding thread priorities.

A numeric type used to hold thread priorities, affecting the thread behaviour, like scheduling and thread wakeup due to events; usually an unsigned 8-bits type.

Higher values represent higher priorities.

See also: os::rtos::thread::priority_t

Definition at line 363 of file os-c-decls.h.

◆ os_thread_stack_allocation_element_t

typedef os_port_thread_stack_allocation_element_t os_thread_stack_allocation_element_t

Type of variables holding aligned stack elements.

A numeric type intended to be used for stack allocations.

See also: os::rtos::stack::allocation_element_t

Definition at line 386 of file os-c-decls.h.

◆ os_thread_stack_element_t

typedef os_port_thread_stack_element_t os_thread_stack_element_t

Type of variables holding stack words.

A numeric type intended to store a stack word as stored by push instructions.

See also: os::rtos::stack::element_t

Definition at line 376 of file os-c-decls.h.

◆ os_thread_stack_t

typedef struct os_thread_stack_s os_thread_stack_t

Thread stack.

The members of this structure are hidden and should not be accessed directly, but through associated functions.

See also: os::rtos::thread::stack

◆ os_thread_state_t

typedef uint8_t os_thread_state_t

Type of variables holding thread states.

See also: os::rtos::thread::state_t

Definition at line 349 of file os-c-decls.h.

◆ os_thread_statistics_t

typedef struct os_thread_statistics_s os_thread_statistics_t

Thread statistics.

The members of this structure are hidden and should not be accessed directly, but through associated functions.

See also: os::rtos::thread::statistics

◆ os_thread_t

typedef struct os_thread_s os_thread_t

Thread object storage.

This C structure has the same size as the C++ os::rtos::thread object and must be initialised with os_thread_create().

Later on a pointer to it can be used both in C and C++ to refer to the thread object instance.

The members of this structure are hidden and should not be used directly, but only through specific functions.

See also: os::rtos::thread

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Thread priorities; intermediate values are also possible.

See also: os::rtos::thread::state

Enumerator
os_thread_priority_none
os_thread_priority_idle
os_thread_priority_lowest
os_thread_priority_low
os_thread_priority_below_normal
os_thread_priority_normal
os_thread_priority_above_normal
os_thread_priority_high
os_thread_priority_realtime
os_thread_priority_highest
os_thread_priority_isr
os_thread_priority_error

Definition at line 268 of file os-c-decls.h.

◆ anonymous enum

anonymous enum

An enumeration with all possible thread states.

See also: os::rtos::thread::state

Enumerator
os_thread_state_undefined	Used to catch uninitialised threads.
os_thread_state_ready	Present in the READY list and competing for CPU.
os_thread_state_running	Has the CPU and runs.
os_thread_state_suspended	Not present in the READY list, waiting for an event.
os_thread_state_terminated	No longer usable, but resources not yet released.
os_thread_state_destroyed	Terminated and resources (like stack) released.
os_thread_state_initialising	Used to check reused threads.

Definition at line 290 of file os-c-decls.h.

Function Documentation

◆ os_children_threads_iter_begin()

os_iterator_t os_children_threads_iter_begin ( os_thread_t * thread )

Get the beginning of the list of children threads.

Parameters

[in] thread Pointer to thread object or NULL for the list of top threads.

Returns: An iterator positioned at the list begin.

Return the position of the first element in the list of children threads of the given thread. If NULL, the position first element in the list of top threads is returned.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 1005 of file os-c-wrapper.cpp.

◆ os_children_threads_iter_end()

os_iterator_t os_children_threads_iter_end ( os_thread_t * thread )

Get the end of the list of children threads.

Parameters

[in] thread Pointer to thread object or NULL for the list of top threads.

Returns: An iterator positioned at the list end.

Return the position after the last element in the list of children threads of the given thread. If NULL, the position after the last element in the list of top threads is returned.

The iteration loop must be terminated when the current iterator is equal to this position, before entering the loop body.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 1029 of file os-c-wrapper.cpp.

◆ os_children_threads_iter_get()

os_thread_t * os_children_threads_iter_get ( os_iterator_t iterator )

Get the thread from the current iterator position.

Parameters

[in] iterator An active iterator.

Returns: The pointer to the thread object instance.

Calling it when the iterator is equal to the end position leads to unpredictable results.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 1049 of file os-c-wrapper.cpp.

◆ os_children_threads_iter_next()

os_iterator_t os_children_threads_iter_next ( os_iterator_t iterator )

Advance the iterator to the next position.

Parameters

[in] iterator An active iterator.

Returns: An iterator positioned at the next list element.

Calling it when the iterator is equal to the end position leads to unpredictable results.

Warning: Cannot be invoked from Interrupt Service Routines.

Definition at line 1065 of file os-c-wrapper.cpp.

◆ os_this_thread()

os_thread_t * os_this_thread ( void )

Get the current running thread.

Parameters: None.

Returns: Pointer to the current running thread object instance.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::this_thread::thread()

Definition at line 482 of file os-c-wrapper.cpp.

◆ os_this_thread_exit()

void os_this_thread_exit ( void * exit_ptr )

Terminate the current running thread.

Parameters

[in] exit_ptr Pointer to object to return. (Optional, may be NULL).

Returns: Nothing.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::this_thread::exit()

Definition at line 506 of file os-c-wrapper.cpp.

◆ os_this_thread_flags_clear()

os_result_t os_this_thread_flags_clear	(	os_flags_mask_t	mask,
		os_flags_mask_t *	oflags
	)

Clear thread event flags.

Parameters

[in]	mask	The OR-ed flags to clear.
[out]	oflags	Optional pointer where to store the previous flags; may be `NULL`.

Return values

os_ok	The flags were cleared.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EINVAL	The mask is zero.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::this_thread::flags_clear()

Definition at line 559 of file os-c-wrapper.cpp.

◆ os_this_thread_flags_get()

os_flags_mask_t os_this_thread_flags_get	(	os_flags_mask_t	mask,
		os_flags_mode_t	mode
	)

Get/clear thread event flags.

Parameters

[in]	mask	The OR-ed flags to get/clear; may be zero.
[in]	mode	Mode bits to select if the flags should be cleared (the other bits are ignored).

Return values

flags	The selected bits from the current thread event flags mask.
sig::all	Cannot be invoked from an Interrupt Service Routines.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::this_thread::flags_get()

Definition at line 571 of file os-c-wrapper.cpp.

◆ os_this_thread_flags_timed_wait()

os_result_t os_this_thread_flags_timed_wait	(	os_flags_mask_t	mask,
		os_clock_duration_t	timeout,
		os_flags_mask_t *	oflags,
		os_flags_mode_t	mode
	)

Timed wait for thread event flags.

Parameters

[in]	mask	The expected flags (OR-ed bit-mask); may be zero.
[out]	oflags	Pointer where to store the current flags; may be `NULL`.
[in]	mode	Mode bits to select if either all or any flags are expected, and if the flags should be cleared.
[in]	timeout	Timeout to wait, in clock units (ticks or seconds).

Return values

os_ok	All expected flags are raised.
EPERM	Cannot be invoked from an Interrupt Service Routines.
ETIMEDOUT	The expected condition did not occur during the entire timeout duration.
EINVAL	The mask is outside of the permitted range.
EINTR	The operation was interrupted.
ENOTRECOVERABLE	Wait failed.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::this_thread::flags_timed_wait()

Definition at line 544 of file os-c-wrapper.cpp.

◆ os_this_thread_flags_try_wait()

os_result_t os_this_thread_flags_try_wait	(	os_flags_mask_t	mask,
		os_flags_mask_t *	oflags,
		os_flags_mode_t	mode
	)

Try to wait for thread event flags.

Parameters

[in]	mask	The expected flags (OR-ed bit-mask); may be zero.
[out]	oflags	Pointer where to store the current flags; may be `NULL`.
[in]	mode	Mode bits to select if either all or any flags are expected, and if the flags should be cleared.

Return values

os_ok	All expected flags are raised.
EINVAL	The mask is outside of the permitted range.
EWOULDBLOCK	The expected condition did not occur.
ENOTRECOVERABLE	Wait failed.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::this_thread::flags_try_wait()

Definition at line 531 of file os-c-wrapper.cpp.

◆ os_this_thread_flags_wait()

os_result_t os_this_thread_flags_wait	(	os_flags_mask_t	mask,
		os_flags_mask_t *	oflags,
		os_flags_mode_t	mode
	)

Wait for thread event flags.

Parameters

[in]	mask	The expected flags (OR-ed bit-mask); may be zero.
[out]	oflags	Pointer where to store the current flags; may be `NULL`.
[in]	mode	Mode bits to select if either all or any flags are expected, and if the flags should be cleared.

Return values

os_ok	All expected flags are raised.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EINVAL	The mask is outside of the permitted range.
EINTR	The operation was interrupted.
ENOTRECOVERABLE	Wait failed.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::this_thread::flags_wait()

Definition at line 518 of file os-c-wrapper.cpp.

◆ os_this_thread_suspend()

void os_this_thread_suspend ( void )

Suspend the current running thread to wait for an event.

Parameters: None.

Returns: Nothing.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::this_thread::suspend()

Definition at line 494 of file os-c-wrapper.cpp.

◆ os_thread_attr_init()

void os_thread_attr_init ( os_thread_attr_t * attr )

Initialise the thread attributes.

Parameters

[in] attr Pointer to thread attributes object instance.

Returns: Nothing.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::attributes

Definition at line 585 of file os-c-wrapper.cpp.

◆ os_thread_construct()

void os_thread_construct	(	os_thread_t *	thread,
		const char *	name,
		os_thread_func_t	func,
		const os_thread_func_args_t	args,
		const os_thread_attr_t *	attr
	)

Construct a statically allocated thread object instance.

Parameters

[in]	thread	Pointer to thread object instance storage.
[in]	name	Pointer to name (may be NULL).
[in]	func	Pointer to thread function.
[in]	args	Pointer to thread function arguments (may be NULL).
[in]	attr	Pointer to attributes (may be NULL)

Returns: Nothing.

Note: Must be paired with os_thread_destruct().

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread

Definition at line 600 of file os-c-wrapper.cpp.

◆ os_thread_delete()

void os_thread_delete ( os_thread_t * thread )

Destruct the thread object instance and deallocate it.

Parameters

[in] thread Pointer to dynamically allocated thread object instance.

Returns: Nothing.

Destruct the thread and deallocate the dynamically allocated space using the RTOS system allocator.

Note: Equivalent of C++ delete ptr_th.; Must be paired with os_thread_new().

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread

Definition at line 669 of file os-c-wrapper.cpp.

◆ os_thread_destruct()

void os_thread_destruct ( os_thread_t * thread )

Destruct the statically allocated thread object instance.

Parameters

[in] thread Pointer to thread object instance.

Returns: Nothing.

Note: Must be paired with os_thread_construct().

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread

Definition at line 623 of file os-c-wrapper.cpp.

◆ os_thread_flags_raise()

os_result_t os_thread_flags_raise	(	os_thread_t *	thread,
		os_flags_mask_t	mask,
		os_flags_mask_t *	oflags
	)

Raise thread event flags.

Parameters

[in]	thread	Pointer to thread object instance.
[in]	mask	The OR-ed flags to raise.
[out]	oflags	Optional pointer where to store the previous flags; may be `NULL`.

Return values

os_ok	The flags were raised.
EINVAL	The mask is zero.
EPERM	Cannot be invoked from an Interrupt Service Routines.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::flags_raise()

Definition at line 775 of file os-c-wrapper.cpp.

◆ os_thread_get_name()

const char * os_thread_get_name ( os_thread_t * thread )

Get the thread name.

Parameters

[in] thread Pointer to thread object instance.

Returns: Null terminated string.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::name()

Definition at line 696 of file os-c-wrapper.cpp.

◆ os_thread_get_priority()

os_thread_prio_t os_thread_get_priority ( os_thread_t * thread )

Get the thread current scheduling priority.

Parameters

[in] thread Pointer to thread object instance.

Returns: The thread priority.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::priority()

Definition at line 709 of file os-c-wrapper.cpp.

◆ os_thread_get_stack()

os_thread_stack_t * os_thread_get_stack ( os_thread_t * thread )

Get the thread context stack.

Parameters

[in] thread Pointer to thread object instance.

Returns: A pointer to the context stack object instance.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::stack()

Definition at line 824 of file os-c-wrapper.cpp.

◆ os_thread_get_state()

os_thread_state_t os_thread_get_state ( os_thread_t * thread )

Get the thread scheduler state.

Parameters

[in] thread Pointer to thread object instance.

Returns: Thread scheduler state.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::state()

Definition at line 790 of file os-c-wrapper.cpp.

◆ os_thread_get_user_storage()

os_thread_user_storage_t * os_thread_get_user_storage ( os_thread_t * thread )

Get the thread user storage.

Parameters

[in] thread Pointer to thread object instance.

Returns: The address of the thread user storage.

Note: Available only when OS_INCLUDE_RTOS_CUSTOM_THREAD_USER_STORAGE is defined.; Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::user_storage()

Definition at line 809 of file os-c-wrapper.cpp.

◆ os_thread_is_constructed()

bool os_thread_is_constructed ( os_thread_t * thread )

Check if the thread is constructed.

Parameters

[in] thread Pointer to thread object instance.

Returns: true if the thread was constructed and not yet destructed.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::is_constructed()

Definition at line 682 of file os-c-wrapper.cpp.

◆ os_thread_join()

os_result_t os_thread_join	(	os_thread_t *	thread,
		void **	exit_ptr
	)

Wait for thread termination.

Parameters

[in]	thread	Pointer to terminating thread object instance.
[in]	exit_ptr	Pointer to thread exit value. (may be NULL).

Return values

os_ok	The thread was terminated.
EPERM	Cannot be invoked from an Interrupt Service Routines.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::join()

Definition at line 749 of file os-c-wrapper.cpp.

◆ os_thread_kill()

os_result_t os_thread_kill ( os_thread_t * thread )

Force thread termination.

Parameters

[in] thread Pointer to thread object instance.

Return values

os_ok	The thread was terminated.
EPERM	Cannot be invoked from an Interrupt Service Routines.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::kill()

Definition at line 736 of file os-c-wrapper.cpp.

◆ os_thread_new()

os_thread_t * os_thread_new	(	const char *	name,
		os_thread_func_t	func,
		const os_thread_func_args_t	args,
		const os_thread_attr_t *	attr
	)

Allocate a thread object instance and construct it.

Parameters

[in]	name	Pointer to name (may be NULL).
[in]	func	Pointer to thread function.
[in]	args	Pointer to thread function arguments (may be NULL).
[in]	attr	Pointer to attributes (may be NULL)

Returns: Pointer to new thread object instance.

Dynamically allocate the thread object instance using the RTOS system allocator and construct it.

Note: Equivalent of C++ new thread(...).; Must be paired with os_thread_delete().

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread

Definition at line 643 of file os-c-wrapper.cpp.

◆ os_thread_resume()

void os_thread_resume ( os_thread_t * thread )

Resume the thread.

Parameters

[in] thread Pointer to thread object instance.

Returns: Nothing.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::resume()

Definition at line 762 of file os-c-wrapper.cpp.

◆ os_thread_set_priority()

os_result_t os_thread_set_priority	(	os_thread_t *	thread,
		os_thread_prio_t	prio
	)

Set the thread dynamic scheduling priority.

Parameters

[in]	thread	Pointer to thread object instance.
[in]	prio	New priority.

Return values

os_ok	The priority was set.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EINVAL	The value of prio is invalid for the scheduling policy of the specified thread.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::priority(priority_t)

Definition at line 722 of file os-c-wrapper.cpp.

◆ os_thread_stack_check_bottom_magic()

bool os_thread_stack_check_bottom_magic ( os_thread_stack_t * stack )

Check if bottom magic word is still there.

Parameters

[in] stack Pointer to stack object instance.

Return values

true	The magic word is still there.
false	The magic word was overwritten.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::stack::check_bottom_magic()

Definition at line 939 of file os-c-wrapper.cpp.

◆ os_thread_stack_check_top_magic()

bool os_thread_stack_check_top_magic ( os_thread_stack_t * stack )

Check if top magic word is still there.

Parameters

[in] stack Pointer to stack object instance.

Return values

true	The magic word is still there.
false	The magic word was overwritten.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::stack::check_top_magic()

Definition at line 952 of file os-c-wrapper.cpp.

◆ os_thread_stack_get_available()

size_t os_thread_stack_get_available ( os_thread_stack_t * stack )

Compute how much available stack remains.

Parameters

[in] stack Pointer to stack object instance.

Returns: Number of available bytes.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::stack::available()

Definition at line 926 of file os-c-wrapper.cpp.

◆ os_thread_stack_get_bottom()

os_thread_stack_element_t * os_thread_stack_get_bottom ( os_thread_stack_t * stack )

Get the stack lowest reserved address.

Parameters

[in] stack Pointer to stack object instance.

Returns: The address of the stack reserved area.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::stack::bottom()

Definition at line 887 of file os-c-wrapper.cpp.

◆ os_thread_stack_get_default_size()

size_t os_thread_stack_get_default_size ( void )

Get the default stack size.

Parameters: None.

Returns: The default stack size in bytes.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::stack::default_size()

Definition at line 839 of file os-c-wrapper.cpp.

◆ os_thread_stack_get_min_size()

size_t os_thread_stack_get_min_size ( void )

Get the min stack size.

Parameters: None.

Returns: The min stack size in bytes.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::stack::min_size()

Definition at line 863 of file os-c-wrapper.cpp.

◆ os_thread_stack_get_size()

size_t os_thread_stack_get_size ( os_thread_stack_t * stack )

Get the stack size.

Parameters

[in] stack Pointer to stack object instance.

Returns: The stack size in bytes.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::stack::size()

Definition at line 913 of file os-c-wrapper.cpp.

◆ os_thread_stack_get_top()

os_thread_stack_element_t * os_thread_stack_get_top ( os_thread_stack_t * stack )

Get the top stack address.

Parameters

[in] stack Pointer to stack object instance.

Returns: The address after the last stack element.

Note: Can be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::stack::top()

Definition at line 900 of file os-c-wrapper.cpp.

◆ os_thread_stack_set_default_size()

size_t os_thread_stack_set_default_size ( size_t size_bytes )

Set the default stack size.

Parameters

[in] size_bytes Default stack size in bytes.

Returns: The previous value of the default stack size in bytes.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::stack::default_size(std::size_t)

Definition at line 851 of file os-c-wrapper.cpp.

◆ os_thread_stack_set_min_size()

size_t os_thread_stack_set_min_size ( size_t size_bytes )

Set the min stack size.

Parameters

[in] size_bytes Minimum stack size in bytes.

Returns: The previous value of the min stack size in bytes.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::stack::min_size(std::size_t)

Definition at line 875 of file os-c-wrapper.cpp.

◆ os_thread_stat_get_context_switches()

os_statistics_counter_t os_thread_stat_get_context_switches ( os_thread_t * thread )

Get the number of thread context switches.

Returns: A long integer with the number of times the thread was scheduled for execution.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::statistics::context_switches()

Definition at line 969 of file os-c-wrapper.cpp.

◆ os_thread_stat_get_cpu_cycles()

os_statistics_duration_t os_thread_stat_get_cpu_cycles ( os_thread_t * thread )

Get the thread execution time.

Returns: A long integer with the accumulated number of CPU cycles, possibly divided by some prescaller.

Warning: Cannot be invoked from Interrupt Service Routines.

For the complete definition, see: os::rtos::thread::statistics::cpu_cycles()

Definition at line 986 of file os-c-wrapper.cpp.

Classes

Typedefs

Enumerations

Current Thread Functions

Thread Attribute Functions

Thread Creation Functions

Thread Functions

Thread Stack Functions

Thread Statistics Functions

Thread Children Iterator Functions

Compatibility Macros

Detailed Description

Macro Definition Documentation

◆ os_condvar_create

◆ os_condvar_destroy

◆ os_evflags_create

◆ os_evflags_destroy

◆ os_mempool_create

◆ os_mempool_destroy

◆ os_mqueue_create

◆ os_mqueue_destroy

◆ os_mutex_create

◆ os_mutex_destroy

◆ os_mutex_recursive_create

◆ os_semaphore_binary_create

◆ os_semaphore_counting_create

◆ os_semaphore_create

◆ os_semaphore_destroy

◆ os_thread_create

◆ os_thread_destroy

◆ os_timer_create

◆ os_timer_destroy

Typedef Documentation

◆ os_thread_attr_t

◆ os_thread_context_t

◆ os_thread_func_args_t

◆ os_thread_func_t

◆ os_thread_prio_t

◆ os_thread_stack_allocation_element_t

◆ os_thread_stack_element_t

◆ os_thread_stack_t

◆ os_thread_state_t

◆ os_thread_statistics_t

◆ os_thread_t

Enumeration Type Documentation

◆ anonymous enum

◆ anonymous enum

Function Documentation

◆ os_children_threads_iter_begin()

◆ os_children_threads_iter_end()

◆ os_children_threads_iter_get()

◆ os_children_threads_iter_next()

◆ os_this_thread()

◆ os_this_thread_exit()

◆ os_this_thread_flags_clear()

◆ os_this_thread_flags_get()

◆ os_this_thread_flags_timed_wait()

◆ os_this_thread_flags_try_wait()

◆ os_this_thread_flags_wait()

◆ os_this_thread_suspend()

◆ os_thread_attr_init()

◆ os_thread_construct()

◆ os_thread_delete()

◆ os_thread_destruct()

◆ os_thread_flags_raise()

◆ os_thread_get_name()

◆ os_thread_get_priority()

◆ os_thread_get_stack()

◆ os_thread_get_state()

◆ os_thread_get_user_storage()

◆ os_thread_is_constructed()

◆ os_thread_join()

◆ os_thread_kill()

◆ os_thread_new()

◆ os_thread_resume()

◆ os_thread_set_priority()

◆ os_thread_stack_check_bottom_magic()

◆ os_thread_stack_check_top_magic()

◆ os_thread_stack_get_available()

◆ os_thread_stack_get_bottom()