|
template<typename F >
requires (StackSize > 0) && ThreadEntry<F> |
| | Thread (F entry, void *ctx, ove_prio_t prio, const char *name) |
| | Constructs and starts the thread.
|
| |
template<typename F >
requires (StackSize > 0) && CooperativeThreadEntry<F> |
| | Thread (F entry, ove_prio_t prio, const char *name) |
| | Cooperative-cancellation constructor — std::jthread analog.
|
| |
template<typename F >
requires (StackSize > 0) && CapturingCooperativeEntry<std::decay_t<F>> |
| | Thread (F &&entry, ove_prio_t prio, const char *name) |
| | Cooperative-cancellation constructor for capturing entries. Heap-mode only. std::jthread-shaped.
|
| |
| | ~Thread () noexcept |
| | Destroys the thread wrapper, terminating and releasing the kernel thread.
|
| |
|
| Thread (const Thread &)=delete |
| |
|
Thread & | operator= (const Thread &)=delete |
| |
| | Thread (Thread &&other) noexcept |
| | Move constructor — transfers ownership of the kernel handle.
|
| |
| Thread & | operator= (Thread &&other) noexcept |
| | Move-assignment operator — transfers ownership of the kernel handle.
|
| |
| void | join () noexcept |
| | Block the caller until the worker thread exits, then release the kernel handle. Analog of std::thread::join.
|
| |
| void | detach () noexcept |
| | Release ownership of the kernel thread without waiting. Analog of std::thread::detach.
|
| |
| void | set_priority (ove_prio_t prio) |
| | Changes the priority of the thread at runtime.
|
| |
| void | suspend () |
| | Suspends execution of the thread.
|
| |
|
void | resume () |
| | Resumes a previously suspended thread.
|
| |
| ove_thread_state_t | get_state () const |
| | Returns the current execution state of the thread.
|
| |
| size_t | get_stack_usage () const |
| | Returns the number of bytes used by the thread's stack so far.
|
| |
| Result< struct ove_thread_stats > | get_runtime_stats () const noexcept |
| | Retrieves runtime statistics for the thread.
|
| |
| void | request_stop () noexcept |
| | Requests the thread to stop cooperatively.
|
| |
| stop_token | get_stop_token () const noexcept |
| | Get a token that observes this thread's cancellation flag.
|
| |
| stop_source | get_stop_source () const noexcept |
| | Get a writable stop_source for this thread. Analog of std::jthread::get_stop_source.
|
| |
| bool | stop_requested () const noexcept |
| |
| bool | valid () const |
| | Returns true if the underlying kernel handle is non-null.
|
| |
| bool | joinable () const noexcept |
| | std::thread::joinable analog — true if this wrapper is associated with an active kernel thread.
|
| |
| id | get_id () const noexcept |
| | Get the id for this thread. std::thread::get_id analog.
|
| |
| ove_thread_t | handle () const |
| | Returns the raw oveRTOS thread handle.
|
| |
template<size_t StackSize = 0>
class ove::Thread< StackSize >
RAII wrapper around an oveRTOS thread (task).
Creates and starts a thread on construction. The thread is destroyed and the underlying kernel resource is released on destruction.
In zero-heap mode (CONFIG_OVE_ZERO_HEAP) the stack is stored as a member array, so StackSize must be greater than zero and move operations are disabled. On heap-enabled builds a non-zero StackSize is still required because it is passed to the kernel at construction time.
- Template Parameters
-
| StackSize | Stack size in bytes for the thread (must be > 0). |
- Note
- Not copyable. Move-only when heap allocation is enabled.
template<size_t StackSize = 0>
template<typename F >
requires (StackSize > 0) && ThreadEntry<F>
| ove::Thread< StackSize >::Thread |
( |
F |
entry, |
|
|
void * |
ctx, |
|
|
ove_prio_t |
prio, |
|
|
const char * |
name |
|
) |
| |
|
inline |
Constructs and starts the thread.
Only participates in overload resolution when StackSize > 0 and the entry function satisfies ThreadEntry.
- Template Parameters
-
| F | Entry function type satisfying ThreadEntry. |
- Parameters
-
| [in] | entry | Function pointer (or compatible callable) to use as the thread entry point, with signature void fn(void*). |
| [in] | ctx | Opaque pointer passed as the argument to entry. |
| [in] | prio | Thread priority as an ove_prio_t value. |
| [in] | name | Human-readable name for the thread (for debugging). |
Asserts at startup if thread creation fails.
template<size_t StackSize = 0>
template<typename F >
requires (StackSize > 0) && CooperativeThreadEntry<F>
| ove::Thread< StackSize >::Thread |
( |
F |
entry, |
|
|
ove_prio_t |
prio, |
|
|
const char * |
name |
|
) |
| |
|
inline |
Cooperative-cancellation constructor — std::jthread analog.
The entry function receives an ove::stop_token and must poll stop_token::stop_requested() in any long-running loop so that ~Thread (or an explicit request_stop) can drive it to a clean exit instead of deadlocking the join wait.
do_work();
}
},
OVE_PRIO_NORMAL, "worker");
RAII wrapper around an oveRTOS thread (task).
Definition thread.hpp:343
Lightweight read-only handle to a thread's cooperative cancellation flag.
Definition thread.hpp:57
bool stop_requested() const noexcept
Definition thread.hpp:65
The entry must be a stateless callable (function pointer or captureless lambda) — the binding has no heap to store captures in zero-heap mode. Use the void(void*) constructor above with a static context struct if you need bound data.
Only participates in overload resolution when StackSize > 0 and F satisfies CooperativeThreadEntry.
template<size_t StackSize = 0>
template<typename F >
requires (StackSize > 0) && CapturingCooperativeEntry<std::decay_t<F>>
| ove::Thread< StackSize >::Thread |
( |
F && |
entry, |
|
|
ove_prio_t |
prio, |
|
|
const char * |
name |
|
) |
| |
|
inline |
Cooperative-cancellation constructor for capturing entries. Heap-mode only. std::jthread-shaped.
Accepts any callable invocable as void(stop_token) that isn't a plain function pointer — lambdas with captures, std::function, functors with member state. The closure is heap-allocated into a box owned by the kernel thread; the trampoline reclaims (and deletes) it after the entry returns.
int channel_id = 7;
q.send(Msg{channel_id});
}
},
OVE_PRIO_NORMAL, "w");
RAII wrapper around an oveRTOS typed message queue.
Definition queue.hpp:47
Lifetime: captured references must outlive the worker — the destructor's request_stop + join guarantees that, provided the captured data outlives the Thread itself. Same rule as std::jthread.
Cost: one heap allocation per spawn (size = sizeof(F)). One template instantiation per distinct closure type F — no type erasure or virtual dispatch.
Zero-heap: this constructor is not defined. Use the captureless cooperative constructor + a static context struct, or the legacy void(void*) constructor with a hand-rolled pointer.
template<size_t StackSize = 0>
Block the caller until the worker thread exits, then release the kernel handle. Analog of std::thread::join.
After join the wrapper is empty: valid returns false and ~Thread is a no-op. Further method calls on the wrapper (other than valid / handle) are undefined behaviour — matches std::thread::join post-conditions.
For cooperative workers, call request_stop before join if the worker's loop terminates on the stop flag. Workers without cooperative logic must terminate on their own; otherwise join blocks indefinitely. Calling join from the worker thread itself deadlocks.
Safe to call after detach (no-op, since the handle is already null).
Works in both heap and zero-heap modes — internally calls ove_thread_destroy (heap) or ove_thread_deinit (zero-heap), both of which wait for the worker to exit.
template<size_t StackSize = 0>
Release ownership of the kernel thread without waiting. Analog of std::thread::detach.
After detach the wrapper is empty: valid returns false and ~Thread is a no-op. The kernel thread keeps running with its own resources; the RTOS reaps them when the entry function returns.
Unlike ~Thread, detach does NOT call request_stop — the worker is genuinely fire-and-forget. Hand it out a stop_token via get_stop_token before detaching if you still want a way to cooperatively shut it down later.
void detach() noexcept
Release ownership of the kernel thread without waiting. Analog of std::thread::detach.
Definition thread.hpp:597
Heap-mode only. See the zero-heap detach stub for why.
template<size_t StackSize = 0>
Requests the thread to stop cooperatively.
Sets the thread's cancellation flag. The worker must poll stop_token::stop_requested via the stop_token it received (cooperative-cancellation constructor) for this to have any effect — the substrate does NOT force-terminate.
Safe from any context (ISR, other thread, the thread itself). Idempotent; the flag is sticky.
- See also
- ~Thread, stop_token
