Threads

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

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 2646 of file os-c-api.h.

os_evflags_destroy

#define os_evflags_destroy   os_evflags_destruct

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

os_mempool_create

#define os_mempool_create   os_mempool_construct

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

os_mempool_destroy

#define os_mempool_destroy   os_mempool_destruct

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

os_mqueue_create

#define os_mqueue_create   os_mqueue_construct

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

os_mqueue_destroy

#define os_mqueue_destroy   os_mqueue_destruct

Definition at line 2433 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 623 of file os-c-api.h.

os_thread_destroy

#define os_thread_destroy   os_thread_destruct

Definition at line 624 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

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

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

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)

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

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 362 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

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

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

See also

os::rtos::stack::element_t

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

os_thread_stack_t

typedef struct os_thread_stack_s os_thread_stack_t

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

See also

os::rtos::thread::state_t

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

os_thread_statistics_t

typedef struct os_thread_statistics_s os_thread_statistics_t

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

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

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 267 of file os-c-decls.h.

  {
    // Ordered, with **none** as the first and **error** as the last.
    os_thread_priority_none = 0, // not defined
    os_thread_priority_idle = (1 << OS_THREAD_PRIO_SHIFT),
    os_thread_priority_lowest = (2 << OS_THREAD_PRIO_SHIFT), // lowest
    os_thread_priority_low = (2 << OS_THREAD_PRIO_SHIFT),
    os_thread_priority_below_normal = (4 << OS_THREAD_PRIO_SHIFT),
    os_thread_priority_normal = (6 << OS_THREAD_PRIO_SHIFT), // default
    os_thread_priority_above_normal = (8 << OS_THREAD_PRIO_SHIFT),
    os_thread_priority_high = (10 << OS_THREAD_PRIO_SHIFT),
    os_thread_priority_realtime = (12 << OS_THREAD_PRIO_SHIFT),
    os_thread_priority_highest = (((13 + 1) << OS_THREAD_PRIO_SHIFT) - 1),
    os_thread_priority_isr = (((14 + 1) << OS_THREAD_PRIO_SHIFT) - 1),
    os_thread_priority_error = (((15 + 1) << OS_THREAD_PRIO_SHIFT) - 1)
  };

anonymous enum

anonymous enum

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 289 of file os-c-decls.h.

  {
    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
  };

Function Documentation

os_children_threads_iter_begin()

os_iterator_t os_children_threads_iter_begin

(

os_thread_t *

thread

)

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 1173 of file os-c-wrapper.cpp.

{
#pragma GCC diagnostic push
#if defined(__clang__)
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Waggregate-return"
#endif
  return reinterpret_cast<os_iterator_t> (
      scheduler::children_threads (reinterpret_cast<rtos::thread*> (thread))
          .begin ()
          .get_iterator_pointer ());
#pragma GCC diagnostic pop
}

References os::rtos::scheduler::children_threads().

os_children_threads_iter_end()

os_iterator_t os_children_threads_iter_end

(

os_thread_t *

thread

)

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 1199 of file os-c-wrapper.cpp.

{
#pragma GCC diagnostic push
#if defined(__clang__)
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Waggregate-return"
#endif
  return reinterpret_cast<os_iterator_t> (
      scheduler::children_threads (reinterpret_cast<rtos::thread*> (thread))
          .end ()
          .get_iterator_pointer ());
#pragma GCC diagnostic pop
}

References os::rtos::scheduler::children_threads().

os_children_threads_iter_get()

os_thread_t * os_children_threads_iter_get

(

os_iterator_t

iterator

)

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 1221 of file os-c-wrapper.cpp.

{
  // Construct a local iterator object based on the pointer.
  thread::threads_list::iterator it{
    reinterpret_cast<utils::double_list_links*> (iterator)
  };
  return reinterpret_cast<os_thread_t*> (&(*it));
}

os_children_threads_iter_next()

os_iterator_t os_children_threads_iter_next

(

os_iterator_t

iterator

)

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 1238 of file os-c-wrapper.cpp.

{
  thread::threads_list::iterator it{
    reinterpret_cast<utils::double_list_links*> (iterator)
  };
  ++it;
 
  return reinterpret_cast<os_iterator_t> (it.get_iterator_pointer ());
}

os_this_thread()

os_thread_t * os_this_thread

(

void

)

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 640 of file os-c-wrapper.cpp.

{
  return (os_thread_t*)&this_thread::thread ();
}

Referenced by __assert_func().

os_this_thread_exit()

void os_this_thread_exit

(

void *

exit_ptr

)

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 664 of file os-c-wrapper.cpp.

{
  this_thread::exit (exit_ptr);
}

os_this_thread_flags_clear()

os_result_t os_this_thread_flags_clear	(	os_flags_mask_t	mask,
		os_flags_mask_t *	oflags
	)

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 717 of file os-c-wrapper.cpp.

{
  return (os_result_t)this_thread::flags_clear (mask, oflags);
}

os_this_thread_flags_get()

os_flags_mask_t os_this_thread_flags_get	(	os_flags_mask_t	mask,
		os_flags_mode_t	mode
	)

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 729 of file os-c-wrapper.cpp.

{
  return (os_flags_mask_t)this_thread::flags_get (mask, mode);
}

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
	)

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 702 of file os-c-wrapper.cpp.

{
  return (os_result_t)this_thread::flags_timed_wait (mask, timeout, oflags,
                                                     mode);
}

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
	)

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 689 of file os-c-wrapper.cpp.

{
  return (os_result_t)this_thread::flags_try_wait (mask, oflags, mode);
}

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
	)

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 676 of file os-c-wrapper.cpp.

{
  return (os_result_t)this_thread::flags_wait (mask, oflags, mode);
}

os_this_thread_suspend()

void os_this_thread_suspend

(

void

)

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 652 of file os-c-wrapper.cpp.

{
  return this_thread::suspend ();
}

os_thread_attr_init()

void os_thread_attr_init

(

os_thread_attr_t *

attr

)

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 743 of file os-c-wrapper.cpp.

{
  assert (attr != nullptr);
  new (attr) thread::attributes ();
}

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
	)

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 758 of file os-c-wrapper.cpp.

{
  assert (thread != nullptr);
  if (attr == nullptr)
    {
      attr = (const os_thread_attr_t*)&thread::initializer;
    }
  new (thread)
      rtos::thread (name, (thread::func_t)func, (thread::func_args_t)args,
                    (const thread::attributes&)*attr);
}

os_thread_delete()

void os_thread_delete

(

os_thread_t *

thread

)

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 827 of file os-c-wrapper.cpp.

{
  assert (thread != nullptr);
  delete reinterpret_cast<rtos::thread*> (thread);
}

os_thread_destruct()

void os_thread_destruct

(

os_thread_t *

thread

)

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 781 of file os-c-wrapper.cpp.

{
  assert (thread != nullptr);
  (reinterpret_cast<rtos::thread&> (*thread)).~thread ();
}

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
	)

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 935 of file os-c-wrapper.cpp.

{
  assert (thread != nullptr);
  return (os_result_t)(reinterpret_cast<rtos::thread&> (*thread))
      .flags_raise (mask, oflags);
}

os_thread_get_name()

const char * os_thread_get_name

(

os_thread_t *

thread

)

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 854 of file os-c-wrapper.cpp.

{
  assert (thread != nullptr);
  return (reinterpret_cast<rtos::thread&> (*thread)).name ();
}

Referenced by __assert_func().

os_thread_get_priority()

os_thread_prio_t os_thread_get_priority

(

os_thread_t *

thread

)

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 867 of file os-c-wrapper.cpp.

{
  assert (thread != nullptr);
  return (os_thread_prio_t)(reinterpret_cast<rtos::thread&> (*thread))
      .priority ();
}

os_thread_get_stack()

os_thread_stack_t * os_thread_get_stack

(

os_thread_t *

thread

)

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 985 of file os-c-wrapper.cpp.

{
  assert (thread != nullptr);
  return reinterpret_cast<os_thread_stack_t*> (
      &(reinterpret_cast<rtos::thread&> (*thread)).stack ());
}

os_thread_get_state()

os_thread_state_t os_thread_get_state

(

os_thread_t *

thread

)

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 950 of file os-c-wrapper.cpp.

{
  assert (thread != nullptr);
  return reinterpret_cast<os_thread_state_t> (
      (reinterpret_cast<rtos::thread&> (*thread)).state ());
}

os_thread_get_user_storage()

os_thread_user_storage_t * os_thread_get_user_storage

(

os_thread_t *

thread

)

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 970 of file os-c-wrapper.cpp.

{
  assert (thread != nullptr);
  return (reinterpret_cast<rtos::thread&> (*thread)).user_storage ();
}

os_thread_is_constructed()

bool os_thread_is_constructed

(

os_thread_t *

thread

)

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 840 of file os-c-wrapper.cpp.

{
  assert (thread != nullptr);
  return rtos::thread::is_constructed (
      reinterpret_cast<rtos::thread&> (*thread));
}

References os::rtos::thread::is_constructed().

os_thread_join()

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

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 908 of file os-c-wrapper.cpp.

{
  assert (thread != nullptr);
  return (os_result_t) reinterpret_cast<rtos::thread&> (*thread).join (
      exit_ptr);
}

References os::rtos::thread::join().

os_thread_kill()

os_result_t os_thread_kill

(

os_thread_t *

thread

)

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 895 of file os-c-wrapper.cpp.

{
  assert (thread != nullptr);
  return (os_result_t) reinterpret_cast<rtos::thread&> (*thread).kill ();
}

References os::rtos::thread::kill().

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
	)

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 801 of file os-c-wrapper.cpp.

{
  if (attr == nullptr)
    {
      attr = (const os_thread_attr_t*)&thread::initializer;
    }
  return reinterpret_cast<os_thread_t*> (
      new rtos::thread (name, (thread::func_t)func, (thread::func_args_t)args,
                        (const thread::attributes&)*attr));
}

os_thread_resume()

void os_thread_resume

(

os_thread_t *

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 922 of file os-c-wrapper.cpp.

{
  assert (thread != nullptr);
  return (reinterpret_cast<rtos::thread&> (*thread)).resume ();
}

os_thread_set_priority()

os_result_t os_thread_set_priority	(	os_thread_t *	thread,
		os_thread_prio_t	prio
	)

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 881 of file os-c-wrapper.cpp.

{
  assert (thread != nullptr);
  return (os_result_t)(reinterpret_cast<rtos::thread&> (*thread))
      .priority (prio);
}

os_thread_stack_check_bottom_magic()

bool os_thread_stack_check_bottom_magic

(

os_thread_stack_t *

stack

)

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 1101 of file os-c-wrapper.cpp.

{
  assert (stack != nullptr);
  return (reinterpret_cast<class rtos::thread::stack&> (*stack))
      .check_bottom_magic ();
}

os_thread_stack_check_top_magic()

bool os_thread_stack_check_top_magic

(

os_thread_stack_t *

stack

)

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 1115 of file os-c-wrapper.cpp.

{
  assert (stack != nullptr);
  return (reinterpret_cast<class rtos::thread::stack&> (*stack))
      .check_top_magic ();
}

os_thread_stack_get_available()

size_t os_thread_stack_get_available

(

os_thread_stack_t *

stack

)

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 1088 of file os-c-wrapper.cpp.

{
  assert (stack != nullptr);
  return (reinterpret_cast<class rtos::thread::stack&> (*stack)).available ();
}

os_thread_stack_get_bottom()

os_thread_stack_element_t * os_thread_stack_get_bottom

(

os_thread_stack_t *

stack

)

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 1049 of file os-c-wrapper.cpp.

{
  assert (stack != nullptr);
  return (reinterpret_cast<class rtos::thread::stack&> (*stack)).bottom ();
}

os_thread_stack_get_default_size()

size_t os_thread_stack_get_default_size

(

void

)

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 1001 of file os-c-wrapper.cpp.

{
  return thread::stack::default_size ();
}

References os::rtos::thread::stack::default_size().

os_thread_stack_get_min_size()

size_t os_thread_stack_get_min_size

(

void

)

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 1025 of file os-c-wrapper.cpp.

{
  return thread::stack::min_size ();
}

References os::rtos::thread::stack::min_size().

os_thread_stack_get_size()

size_t os_thread_stack_get_size

(

os_thread_stack_t *

stack

)

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 1075 of file os-c-wrapper.cpp.

{
  assert (stack != nullptr);
  return (reinterpret_cast<class rtos::thread::stack&> (*stack)).size ();
}

os_thread_stack_get_top()

os_thread_stack_element_t * os_thread_stack_get_top

(

os_thread_stack_t *

stack

)

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 1062 of file os-c-wrapper.cpp.

{
  assert (stack != nullptr);
  return (reinterpret_cast<class rtos::thread::stack&> (*stack)).top ();
}

os_thread_stack_set_default_size()

size_t os_thread_stack_set_default_size

(

size_t

size_bytes

)

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 1013 of file os-c-wrapper.cpp.

{
  return thread::stack::default_size (size_bytes);
}

References os::rtos::thread::stack::default_size().

os_thread_stack_set_min_size()

size_t os_thread_stack_set_min_size

(

size_t

size_bytes

)

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 1037 of file os-c-wrapper.cpp.

{
  return thread::stack::min_size (size_bytes);
}

References os::rtos::thread::stack::min_size().

os_thread_stat_get_context_switches()

os_statistics_counter_t os_thread_stat_get_context_switches

(

os_thread_t *

thread

)

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 1133 of file os-c-wrapper.cpp.

{
  assert (thread != nullptr);
  return static_cast<os_statistics_counter_t> (
      (reinterpret_cast<rtos::thread&> (*thread))
          .statistics ()
          .context_switches ());
}

os_thread_stat_get_cpu_cycles()

os_statistics_duration_t os_thread_stat_get_cpu_cycles

(

os_thread_t *

thread

)

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 1153 of file os-c-wrapper.cpp.

{
  assert (thread != nullptr);
  return static_cast<os_statistics_duration_t> (
      (reinterpret_cast<rtos::thread&> (*thread)).statistics ().cpu_cycles ());
}