|
oveRTOS C API
Embedded RTOS framework — build system, configuration, and portable C API
|
Deferred work execution on a dedicated RTOS thread. More...
Typedefs | |
| typedef void(* | ove_work_fn) (ove_work_t work) |
| Prototype for a work item handler function. | |
Functions | |
| int | ove_workqueue_init (ove_workqueue_t *wq, ove_workqueue_storage_t *storage, const char *name, ove_prio_t priority, size_t stack_size, void *stack) |
| Initialise a work queue using caller-provided static storage. | |
| void | ove_workqueue_deinit (ove_workqueue_t wq) |
| Deinitialise a statically-allocated work queue. | |
| int | ove_work_init_static (ove_work_t *work, ove_work_storage_t *storage, ove_work_fn handler) |
| Initialise a work item using caller-provided static storage. | |
| int | ove_work_init (ove_work_t *work, ove_work_fn handler) |
| Allocate and initialise a heap-backed work item. | |
| void | ove_work_free (ove_work_t work) |
| Free a heap-allocated work item. | |
| int | ove_workqueue_create (ove_workqueue_t *wq, const char *name, ove_prio_t priority, size_t stack_size) |
| Allocate a heap-backed work queue. | |
| void | ove_workqueue_destroy (ove_workqueue_t wq) |
| Destroy a heap-allocated work queue. | |
| int | ove_work_submit (ove_workqueue_t wq, ove_work_t work) |
| Submit a work item for immediate execution on the work queue. | |
| int | ove_work_submit_delayed (ove_workqueue_t wq, ove_work_t work, uint32_t delay_ms) |
| Submit a work item for execution after a delay. | |
| int | ove_work_cancel (ove_work_t work) |
| Cancel a pending work item before it executes. | |
Deferred work execution on a dedicated RTOS thread.
A work queue owns a single thread that executes submitted work items in FIFO order. Work items may be submitted immediately or after a delay, and pending items may be cancelled before execution begins.
Two allocation strategies are supported for the queue itself:
_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._init() / _deinit() — explicit storage control with caller-supplied buffers. Use when creating objects in loops, arrays, or structs.Work items similarly have static (ove_work_init_static) and heap (ove_work_init / ove_work_free) variants.
CONFIG_OVE_WORKQUEUE. | typedef void(* ove_work_fn) (ove_work_t work) |
Prototype for a work item handler function.
Called by the work queue thread when the work item is executed. The work handle may be used to reschedule or identify the item inside the handler.
| [in] | work | Handle of the work item being executed. |
| int ove_workqueue_init | ( | ove_workqueue_t * | wq, |
| ove_workqueue_storage_t * | storage, | ||
| const char * | name, | ||
| ove_prio_t | priority, | ||
| size_t | stack_size, | ||
| void * | stack | ||
| ) |
Initialise a work queue using caller-provided static storage.
Creates the underlying RTOS thread with the given name, priority, stack_size, and pre-allocated stack buffer. The queue begins dispatching items as soon as the first work item is submitted.
| [out] | wq | Receives the initialised work queue handle. |
| [in] | storage | Pointer to statically-allocated work queue storage. |
| [in] | name | Human-readable name for the underlying thread. |
| [in] | priority | Thread priority for the work queue thread. |
| [in] | stack_size | Size of the thread stack in bytes. |
| [in] | stack | Pointer to the pre-allocated stack buffer. |
CONFIG_OVE_WORKQUEUE. | void ove_workqueue_deinit | ( | ove_workqueue_t | wq | ) |
Deinitialise a statically-allocated work queue.
Stops the underlying thread and releases all RTOS resources. Any work items still in the queue at deinit time are discarded without execution.
| [in] | wq | Work queue handle returned by ove_workqueue_init. |
CONFIG_OVE_WORKQUEUE. | int ove_work_init_static | ( | ove_work_t * | work, |
| ove_work_storage_t * | storage, | ||
| ove_work_fn | handler | ||
| ) |
Initialise a work item using caller-provided static storage.
Associates the handler function with the work item. The item must be initialised before it can be submitted to a work queue.
| [out] | work | Receives the initialised work handle. |
| [in] | storage | Pointer to statically-allocated work item storage. |
| [in] | handler | Function to call when the work item is executed. |
CONFIG_OVE_WORKQUEUE. | int ove_work_init | ( | ove_work_t * | work, |
| ove_work_fn | handler | ||
| ) |
Allocate and initialise a heap-backed work item.
Allocates the work item control structure from the heap and associates handler with it.
| [out] | work | Receives the created work handle. |
| [in] | handler | Function to call when the work item is executed. |
CONFIG_OVE_WORKQUEUE and that CONFIG_OVE_ZERO_HEAP is not set. | void ove_work_free | ( | ove_work_t | work | ) |
Free a heap-allocated work item.
Releases the memory allocated by ove_work_init. The item must not be pending in a work queue when this function is called; cancel it first with ove_work_cancel if necessary.
| [in] | work | Work handle returned by ove_work_init. |
CONFIG_OVE_WORKQUEUE and that CONFIG_OVE_ZERO_HEAP is not set. | int ove_workqueue_create | ( | ove_workqueue_t * | wq, |
| const char * | name, | ||
| ove_prio_t | priority, | ||
| size_t | stack_size | ||
| ) |
Allocate a heap-backed work queue.
Allocates the work queue and its thread from the heap and starts dispatching immediately.
| [out] | wq | Receives the created work queue handle. |
| [in] | name | Human-readable name for the underlying thread. |
| [in] | priority | Thread priority for the work queue thread. |
| [in] | stack_size | Stack size in bytes for the work queue thread. |
CONFIG_OVE_WORKQUEUE and OVE_HEAP_WORKQUEUE. | void ove_workqueue_destroy | ( | ove_workqueue_t | wq | ) |
Destroy a heap-allocated work queue.
Stops the underlying thread and frees all resources. Pending work items are discarded. Must only be called on handles from ove_workqueue_create.
| [in] | wq | Work queue handle returned by ove_workqueue_create. |
CONFIG_OVE_WORKQUEUE and OVE_HEAP_WORKQUEUE. | int ove_work_submit | ( | ove_workqueue_t | wq, |
| ove_work_t | work | ||
| ) |
Submit a work item for immediate execution on the work queue.
Enqueues work for execution on wq. If the item is already pending the call may fail or reset the pending state depending on the underlying implementation.
| [in] | wq | Target work queue handle. |
| [in] | work | Work item handle to submit. |
| int ove_work_submit_delayed | ( | ove_workqueue_t | wq, |
| ove_work_t | work, | ||
| uint32_t | delay_ms | ||
| ) |
Submit a work item for execution after a delay.
Schedules work to run on wq after at least delay_ms milliseconds have elapsed. The item may be cancelled before the delay expires using ove_work_cancel.
| [in] | wq | Target work queue handle. |
| [in] | work | Work item handle to schedule. |
| [in] | delay_ms | Minimum delay before execution in milliseconds. |
| int ove_work_cancel | ( | ove_work_t | work | ) |
Cancel a pending work item before it executes.
Attempts to remove work from the queue before its handler is called. Has no effect if the item is not pending or is already executing.
| [in] | work | Work item handle to cancel. |
OVE_ERR_INVAL if the item was not pending, or another negative error code on failure. 1.9.8