Create, configure, and query RTOS threads across all supported backends. More...

Data Structures
struct	ove_thread_stats
	Per-thread runtime statistics snapshot. More...

struct	ove_thread_desc
	Thread creation descriptor passed to ove_thread_init() / ove_thread_create(). More...

struct	ove_mem_stats
	System heap statistics. More...

struct	ove_thread_info
	Snapshot of a single thread's info. More...

Macros
#define	ove_thread_create(phandle, stack_sz, pdesc)
	Create a thread (works in both heap and zero-heap mode).

Typedefs
typedef void(*	ove_thread_fn) (void *arg)
	Thread entry-point function prototype.

Enumerations
enum	ove_thread_state_t { OVE_THREAD_STATE_RUNNING = 0 , OVE_THREAD_STATE_READY , OVE_THREAD_STATE_BLOCKED , OVE_THREAD_STATE_SUSPENDED , OVE_THREAD_STATE_TERMINATED , OVE_THREAD_STATE_UNKNOWN }
	Thread execution state as reported by the active backend. More...

enum	ove_prio_t { OVE_PRIO_IDLE = 0 , OVE_PRIO_LOW = 1 , OVE_PRIO_BELOW_NORMAL = 2 , OVE_PRIO_NORMAL = 3 , OVE_PRIO_ABOVE_NORMAL = 4 , OVE_PRIO_HIGH = 5 , OVE_PRIO_REALTIME = 6 , OVE_PRIO_CRITICAL = 7 }
	Portable thread-priority levels. More...

Functions
int	ove_thread_init (ove_thread_t handle, ove_thread_storage_t storage, const struct ove_thread_desc *desc)
	Initialise a thread using caller-supplied static storage.

int	ove_thread_deinit (ove_thread_t handle)
	Terminate and release a thread created with ove_thread_init().

int	ove_thread_create_ (ove_thread_t handle, const struct ove_thread_desc desc)
	Internal heap-backed thread creation function.

int	ove_thread_destroy (ove_thread_t handle)
	Stop and free a thread created with ove_thread_create().

ove_thread_t	ove_thread_get_self (void)
	Return the handle of the currently executing thread.

void	ove_thread_set_priority (ove_thread_t handle, ove_prio_t prio)
	Change the scheduling priority of a thread.

void	ove_thread_sleep_ms (uint32_t ms)
	Block the calling thread for at least `ms` milliseconds.

void	ove_thread_yield (void)
	Voluntarily yield the CPU to another ready thread of equal or higher priority.

void	ove_thread_start_scheduler (void)
	Start the RTOS scheduler.

void	ove_thread_suspend (ove_thread_t handle)
	Suspend a thread, preventing it from being scheduled.

void	ove_thread_resume (ove_thread_t handle)
	Resume a previously suspended thread.

size_t	ove_thread_get_stack_usage (ove_thread_t handle)
	Query how many bytes of stack the thread has used at its high-water mark.

ove_thread_state_t	ove_thread_get_state (ove_thread_t handle)
	Query the current execution state of a thread.

int	ove_thread_get_runtime_stats (ove_thread_t handle, struct ove_thread_stats *stats)
	Retrieve runtime statistics for a thread.

int	ove_sys_get_mem_stats (struct ove_mem_stats *stats)
	Query system heap statistics.

int	ove_thread_list (struct ove_thread_info out, size_t max_count, size_t actual_count)
	List all threads in the system.

Detailed Description

Create, configure, and query RTOS threads across all supported backends.

Two allocation strategies are available:

_create() / _destroy() — unified API that works in both heap and zero-heap mode. In zero-heap mode these are macros that generate per-call-site static storage; the stack size must be a compile-time constant. ove_thread_create() takes three arguments: (handle, stack_sz, desc).
_init() / _deinit() — explicit storage control with caller-supplied buffers. Use when creating objects in loops, arrays, or structs.

Macro Definition Documentation

◆ ove_thread_create

#define ove_thread_create	(	phandle,
		stack_sz,
		pdesc
	)

Value:

    ({ struct ove_thread_desc _ove_d_ = *(pdesc); \
       _ove_d_.stack_size = (stack_sz); \
       ove_thread_create_((phandle), &_ove_d_); })

Create a thread (works in both heap and zero-heap mode).

In heap mode, allocates storage from the heap. In zero-heap mode, generates per-call-site static storage and an aligned stack buffer.

stack_sz must be a compile-time integer constant in zero-heap mode. The macro sets desc->stack_size; the caller should not set it.

Parameters

phandle	Pointer to thread handle to receive the result.
stack_sz	Stack size in bytes.
pdesc	Pointer to a thread descriptor.

Typedef Documentation

◆ ove_thread_fn

typedef void(* ove_thread_fn) (void *arg)

Thread entry-point function prototype.

Parameters

[in] arg Caller-supplied context pointer passed from ove_thread_desc::arg.

Enumeration Type Documentation

◆ ove_thread_state_t

enum ove_thread_state_t

Thread execution state as reported by the active backend.

Enumerator
OVE_THREAD_STATE_RUNNING	Currently executing on the CPU.
OVE_THREAD_STATE_READY	Ready to run, waiting for the CPU.
OVE_THREAD_STATE_BLOCKED	Blocked on a synchronisation object or delay.
OVE_THREAD_STATE_SUSPENDED	Explicitly suspended via ove_thread_suspend().
OVE_THREAD_STATE_TERMINATED	Entry function has returned; not yet destroyed.
OVE_THREAD_STATE_UNKNOWN	State could not be determined.

◆ ove_prio_t

enum ove_prio_t

Portable thread-priority levels.

Each value maps to a backend-specific numeric priority at initialisation time. Higher enum values represent higher scheduling priority.

Enumerator
OVE_PRIO_IDLE	Lowest priority; runs only when no other thread is ready.
OVE_PRIO_LOW	Low priority background work.
OVE_PRIO_BELOW_NORMAL	Below-normal priority.
OVE_PRIO_NORMAL	Default application priority.
OVE_PRIO_ABOVE_NORMAL	Above-normal priority.
OVE_PRIO_HIGH	High priority; prefer for time-sensitive tasks.
OVE_PRIO_REALTIME	Real-time priority; use with care.
OVE_PRIO_CRITICAL	Highest priority; reserved for critical system tasks.

Function Documentation

◆ ove_thread_init()

int ove_thread_init	(	ove_thread_t *	handle,
		ove_thread_storage_t *	storage,
		const struct ove_thread_desc *	desc
	)

Initialise a thread using caller-supplied static storage.

Creates a new thread without any heap allocation. The caller must provide both a storage object and a stack buffer via desc->stack / desc->stack_size.

Parameters

[out]	handle	Receives the opaque thread handle on success.
[in]	storage	Pointer to statically allocated backend storage. Must remain valid for the lifetime of the thread.
[in]	desc	Thread descriptor; all fields must be valid.

Returns: OVE_OK on success, or a negative error code on failure.

See also: ove_thread_deinit, ove_thread_create

◆ ove_thread_deinit()

int ove_thread_deinit ( ove_thread_t handle )

Terminate and release a thread created with ove_thread_init().

Stops the thread and releases any backend-internal resources. The static storage supplied at init time is not freed.

Parameters

[in] handle Handle returned by ove_thread_init().

Returns: OVE_OK on success, or a negative error code on failure.

See also: ove_thread_init

◆ ove_thread_create_()

int ove_thread_create_	(	ove_thread_t *	handle,
		const struct ove_thread_desc *	desc
	)

Internal heap-backed thread creation function.

Prefer the ove_thread_create() macro which works in both heap and zero-heap mode. This function is the underlying implementation used in heap mode.

Parameters

[out]	handle	Receives the opaque thread handle on success.
[in]	desc	Thread descriptor; `stack` should be NULL.

Returns: OVE_OK on success, or a negative error code on failure.

See also: ove_thread_create

◆ ove_thread_destroy()

int ove_thread_destroy ( ove_thread_t handle )

Stop and free a thread created with ove_thread_create().

Parameters

[in] handle Handle returned by ove_thread_create().

Returns: OVE_OK on success, or a negative error code on failure.

See also: ove_thread_create

◆ ove_thread_get_self()

ove_thread_t ove_thread_get_self ( void )

Return the handle of the currently executing thread.

Returns: Handle of the calling thread.

◆ ove_thread_set_priority()

void ove_thread_set_priority	(	ove_thread_t	handle,
		ove_prio_t	prio
	)

Change the scheduling priority of a thread.

Parameters

[in]	handle	Thread to modify.
[in]	prio	New priority level.

◆ ove_thread_sleep_ms()

void ove_thread_sleep_ms ( uint32_t ms )

Block the calling thread for at least ms milliseconds.

Parameters

[in] ms Minimum sleep duration in milliseconds. A value of 0 yields the CPU for one scheduler tick.

◆ ove_thread_yield()

void ove_thread_yield ( void )

Voluntarily yield the CPU to another ready thread of equal or higher priority.

Has no effect if no other eligible thread is ready to run.

◆ ove_thread_start_scheduler()

void ove_thread_start_scheduler ( void )

Start the RTOS scheduler.

Must be called after all threads and resources have been created. Typically called indirectly through ove_run(). Does not return on most platforms.

See also: ove_run

◆ ove_thread_suspend()

void ove_thread_suspend ( ove_thread_t handle )

Suspend a thread, preventing it from being scheduled.

The thread remains suspended until ove_thread_resume() is called.

Parameters

[in] handle Thread to suspend. May be the calling thread itself.

See also: ove_thread_resume

◆ ove_thread_resume()

void ove_thread_resume ( ove_thread_t handle )

Resume a previously suspended thread.

Parameters

[in] handle Thread to resume. Must have been suspended with ove_thread_suspend().

See also: ove_thread_suspend

◆ ove_thread_get_stack_usage()

size_t ove_thread_get_stack_usage ( ove_thread_t handle )

Query how many bytes of stack the thread has used at its high-water mark.

Parameters

[in] handle Thread to inspect.

Returns: Number of bytes consumed at the historical peak, or 0 if the backend does not support stack profiling.

◆ ove_thread_get_state()

ove_thread_state_t ove_thread_get_state ( ove_thread_t handle )

Query the current execution state of a thread.

Parameters

[in] handle Thread to inspect.

Returns: One of the OVE_THREAD_STATE_* values.

◆ ove_thread_get_runtime_stats()

int ove_thread_get_runtime_stats	(	ove_thread_t	handle,
		struct ove_thread_stats *	stats
	)

Retrieve runtime statistics for a thread.

Populates stats with the total CPU time and utilisation percentage since the scheduler started.

Parameters

[in]	handle	Thread to inspect.
[out]	stats	Pointer to a caller-allocated structure that will receive the statistics.

Returns: OVE_OK on success, OVE_ERR_NOT_SUPPORTED if the backend does not provide runtime accounting.

◆ ove_sys_get_mem_stats()

int ove_sys_get_mem_stats ( struct ove_mem_stats * stats )

Query system heap statistics.

Parameters

[out] stats Caller-allocated structure to receive stats.

Returns: OVE_OK on success, OVE_ERR_NOT_SUPPORTED if unavailable.

◆ ove_thread_list()

int ove_thread_list	(	struct ove_thread_info *	out,
		size_t	max_count,
		size_t *	actual_count
	)

List all threads in the system.

Parameters

[out]	out	Array to fill with thread info.
[in]	max_count	Maximum entries in `out`.
[out]	actual_count	Actual number of threads written (may be NULL).

Returns: OVE_OK on success, OVE_ERR_NOT_SUPPORTED if unavailable.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ ove_thread_create

Typedef Documentation

◆ ove_thread_fn

Enumeration Type Documentation

◆ ove_thread_state_t

◆ ove_prio_t

Function Documentation

◆ ove_thread_init()

◆ ove_thread_deinit()

◆ ove_thread_create_()

◆ ove_thread_destroy()

◆ ove_thread_get_self()

◆ ove_thread_set_priority()

◆ ove_thread_sleep_ms()

◆ ove_thread_yield()

◆ ove_thread_start_scheduler()

◆ ove_thread_suspend()

◆ ove_thread_resume()

◆ ove_thread_get_stack_usage()

◆ ove_thread_get_state()

◆ ove_thread_get_runtime_stats()

◆ ove_sys_get_mem_stats()

◆ ove_thread_list()