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_mem_stats
	System heap statistics. More...

struct	ove_thread_state_times
	Cumulative time per thread state (microseconds). More...

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

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 char name, ove_thread_fn entry, void arg, ove_prio_t priority, size_t stack_size, void *stack)
	Initialise a thread using caller-supplied static storage and stack.

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 char name, ove_thread_fn entry, void *arg, ove_prio_t priority, size_t stack_size)
	Allocate and start a heap-backed thread.

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.

void	ove_thread_request_stop (ove_thread_t handle)
	Cooperatively request that a thread stop running.

bool	ove_thread_should_stop (ove_thread_t handle)
	Check whether the calling (or specified) thread has been asked to stop.

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() — heap-allocated (storage + stack). Available only when OVE_HEAP_THREAD is defined (i.e. CONFIG_OVE_ZERO_HEAP is not set).
_init() / _deinit() — caller-supplied storage and stack buffer. Available in both modes. See OVE_THREAD_DEFINE_STATIC for a one-step static helper.

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 at creation time.

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 char *	name,
		ove_thread_fn	entry,
		void *	arg,
		ove_prio_t	priority,
		size_t	stack_size,
		void *	stack
	)

Initialise a thread using caller-supplied static storage and stack.

Creates a new thread without any heap allocation. The caller must provide a backend storage object and a stack buffer of stack_size bytes.

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]	name	Human-readable thread name. May be truncated.
[in]	entry	Thread entry-point function. Must not be NULL.
[in]	arg	Opaque argument forwarded to `entry`. May be NULL.
[in]	priority	Scheduling priority.
[in]	stack_size	Stack size in bytes. Must be > 0.
[in]	stack	Pointer to caller-allocated stack buffer. Must be 8-byte aligned (ARM AAPCS). Use the `OVE_THREAD_STACK_DEFINE_` family of helpers in `include/ove/storage.h`.

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 char *	name,
		ove_thread_fn	entry,
		void *	arg,
		ove_prio_t	priority,
		size_t	stack_size
	)

Allocate and start a heap-backed thread.

Both the backend storage and the stack are allocated from the RTOS heap.

Note: Requires OVE_HEAP_THREAD. In zero-heap mode this function is not declared; use ove_thread_init() or OVE_THREAD_DEFINE_STATIC() instead.

Parameters

[out]	handle	Receives the opaque thread handle on success.
[in]	name	Human-readable thread name. May be truncated.
[in]	entry	Thread entry-point function. Must not be NULL.
[in]	arg	Opaque argument forwarded to `entry`. May be NULL.
[in]	priority	Scheduling priority.
[in]	stack_size	Stack size in bytes. Must be > 0.

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

See also: ove_thread_destroy

◆ ove_thread_destroy()

int ove_thread_destroy ( ove_thread_t handle )

Stop and free a thread created with ove_thread_create().

Note: Requires OVE_HEAP_THREAD.

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_request_stop()

void ove_thread_request_stop ( ove_thread_t handle )

Cooperatively request that a thread stop running.

Sets the thread's stop-requested flag. The worker must poll ove_thread_should_stop and exit its entry function in response; the substrate does NOT forcibly terminate the thread.

Safe to call from any context (ISR, other thread, or the thread itself). Storing the flag is a single uncontended atomic write.

The flag is per-thread, allocated unconditionally (1 byte storage, not opt-in). Calling on a non-stoppable thread is the same as calling on any other thread — the worker just has to choose to observe ove_thread_should_stop.

Parameters

[in] handle Thread to signal.

See also: ove_thread_should_stop

◆ ove_thread_should_stop()

bool ove_thread_should_stop ( ove_thread_t handle )

Check whether the calling (or specified) thread has been asked to stop.

Returns true if ove_thread_request_stop was called for handle. The flag is sticky: once set it stays set for the thread's lifetime.

Workers should poll this in their main loop:

while (!ove_thread_should_stop(ove_thread_get_self())) {
    do_work();
}

Safe to call from any context. The load is a single uncontended atomic read.

Parameters

[in] handle Thread to inspect.

Returns: true if a stop has been requested, false otherwise.

See also: ove_thread_request_stop

◆ 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

Typedefs

Enumerations

Functions

Detailed Description

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_request_stop()

◆ ove_thread_should_stop()

◆ ove_thread_get_stack_usage()

◆ ove_thread_get_state()

◆ ove_thread_get_runtime_stats()

◆ ove_sys_get_mem_stats()

◆ ove_thread_list()