thread.h¶

Defines

EMB_THREAD_DETACHED¶

EMB_THREAD_CRITICAL¶

EMB_THREAD_CANCEL_DISABLED¶

EMB_THREAD_NO_AUTOSTART¶

EMB_THREAD_INACTIVE¶

EMB_THREAD_READY¶

EMB_THREAD_RUNNING¶

EMB_THREAD_BLOCKED¶

EMB_THREAD_TERMINATED¶

EMB_WAIT_REASON_NONE¶

EMB_WAIT_REASON_START¶

EMB_WAIT_REASON_SUSPEND¶

EMB_WAIT_REASON_SLEEP¶

EMB_WAIT_REASON_OBJECT¶

EMB_WAIT_REASON_JOIN¶

EMB_WAIT_REASON_NOTIFY¶

EMB_STACK_ALIGN¶

EMB_THREAD_STACK_MIN¶

EMB_STACK_FILL¶

EMB_THREAD_STACK(name, size)¶

EMB_THREAD_DEFINE(sym, entry, arg, priority_, stack_size_, flags_)¶

Typedefs

typedef union emb_thread_storage emb_thread_storage_t¶

typedef void (*emb_thread_entry_t)(void *arg)¶

typedef struct emb_thread_attr emb_thread_attr_t¶

typedef void (*emb_thread_visit_t)(emb_thread_t thread, void *arg)¶

Functions

void emb_thread_attr_default(emb_thread_attr_t *out_attr)¶

emb_thread_attr_default() - Fill out_attr

with the defaults.

Context: thread isr prekernel Blocking: no Timing: O(1) Ownership: none Configuration: Requirements: API-020 Since: 0.2 Stability: yes

Parameters:

out_attr – name NULL, stack NULL, priority 1, flags 0.

emb_status_t emb_thread_init(emb_thread_storage_t *storage, const emb_thread_attr_t *attr, emb_thread_entry_t entry, void *arg, emb_thread_t *out_thread)¶

emb_thread_init()

- Construct a thread in caller-provided storage; it does not run yet.

Context: prekernel thread Blocking: no Timing: O(1) + stack fill in checked and statistics builds Ownership: borrows:storage borrows:attr->stack Configuration: Requirements: API-021 KRN-THR-004 KRN-THR-007 KRN-THR-015 KRN-THR-023 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EINVAL for a NULL storage, entry, stack, a priority of 0 or above EMB_PRIORITY_MAX, a misaligned or undersized stack (misuse, SPEC-008 §12); EMB_EBUSY on the tiny profile when the priority’s table slot is taken.

Parameters:

storage – Storage for the control block, EMB_THREAD_STORAGE_ALIGN aligned.
attr – Attributes; stack and stack_size are required.
entry – The thread function.
arg – Passed to entry.
out_thread – The handle; EMB_HANDLE_NULL on failure.

emb_status_t emb_thread_start(emb_thread_t thread)¶

emb_thread_start()

- Make an INACTIVE thread READY.

Context: prekernel thread isr Blocking: no Timing: O(1) Ownership: none Configuration: Requirements: KRN-THR-016 KRN-THR-009 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_ESTATE when the thread is not INACTIVE; EMB_EINVAL for a bad handle.

Parameters:

thread – The thread.

emb_thread_t emb_thread_self(void)¶

emb_thread_self() - The calling thread.

Context: thread Blocking: no Timing: O(1) Ownership: none Configuration: Requirements: KRN-THR-008 Since: 0.2 Stability: yes

void emb_thread_exit(int code)¶

emb_thread_exit() - End the calling thread with code

(SPEC-008 §5).

Context: thread Blocking: no Timing: O(owned mutexes) Ownership: none Configuration: Requirements: KRN-THR-005 KRN-THR-006 KRN-THR-017 Since: 0.2 Stability: yes

Parameters:

code – Delivered to the joiner; ignored for a detached thread.

emb_status_t emb_thread_join(emb_thread_t thread, emb_timeout_t timeout, int *out_code)¶

emb_thread_join() - Wait for thread

to terminate and collect its exit code.

Context: thread Blocking: timeout Timing: O(1) state check; O(timeouts) finite timeout arm Ownership: none Configuration: Requirements: KRN-THR-006 KRN-THR-012 KRN-THR-018 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_ETIMEDOUT; EMB_ECANCELED; EMB_EBUSY for a second joiner; EMB_EINVAL for a detached/invalid thread; EMB_EDEADLK for self.

Parameters:

thread – A joinable thread that is not the caller.
timeout – How long to wait.
out_code – Receives the exit code on EMB_OK; may be NULL.

emb_status_t emb_thread_detach(emb_thread_t thread)¶

emb_thread_detach() - Make thread

detached; its storage is reusable at exit.

Context: thread isr Blocking: no Timing: O(1) Ownership: none Configuration: Requirements: KRN-THR-019 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EBUSY when a joiner is blocked on it.

Parameters:

thread – Joinable initialized thread with no blocked joiner.

emb_status_t emb_thread_suspend(emb_thread_t thread)¶

emb_thread_suspend() - Keep thread from running until emb_thread_resume()

An overlay (SPEC-004 §6.5): a blocked thread keeps its queue position and its deadline. Idempotent.

Context: thread Blocking: no Timing: O(1) Ownership: none Configuration: Requirements: KRN-THR-010 KRN-THR-020 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EPERM for a kernel thread; EMB_ESTATE for an INACTIVE or TERMINATED thread.

Parameters:

thread – Started application thread; suspending self delays return until resumed.

emb_status_t emb_thread_resume(emb_thread_t thread)¶

emb_thread_resume() - Undo emb_thread_suspend()

. Idempotent.

Context: thread isr Blocking: no Timing: O(1) Ownership: none Configuration: Requirements: KRN-THR-010 KRN-THR-020 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_ESTATE for an INACTIVE or TERMINATED thread.

Parameters:

thread – Started thread whose suspend overlay is to be removed.

emb_status_t emb_thread_cancel(emb_thread_t thread)¶

emb_thread_cancel() - Request cancellation of thread

(SPEC-008 §7).

Context: thread isr Blocking: no Timing: O(1) Ownership: none Configuration: Requirements: KRN-THR-011 KRN-THR-021 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EPERM for a kernel thread; EMB_ESTATE for INACTIVE or TERMINATED.

Parameters:

thread – Started application thread to request cancellation of; storage is not destroyed.

emb_status_t emb_thread_cancel_point(void)¶

emb_thread_cancel_point() - Deliver a pending cancel request to the caller.

Context: thread Blocking: no Timing: O(1) Ownership: none Configuration: Requirements: KRN-THR-011 KRN-THR-021 Since: 0.2 Stability: yes

Return: EMB_ECANCELED when a request was pending and enabled, else EMB_OK.

emb_status_t emb_thread_cancel_disable(void)¶

emb_thread_cancel_disable() - Increment the caller’s cancel-disable count.

Context: thread Blocking: no Timing: O(1) Ownership: none Configuration: Requirements: KRN-THR-021 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EOVERFLOW at 255.

emb_status_t emb_thread_cancel_enable(void)¶

emb_thread_cancel_enable() - Decrement the caller’s cancel-disable count.

Context: thread Blocking: no Timing: O(1) Ownership: none Configuration: Requirements: KRN-THR-021 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_ESTATE when the count is already zero.

emb_status_t emb_thread_set_priority(emb_thread_t thread, uint8_t priority)¶

emb_thread_set_priority() - Change the base priority of thread

(SPEC-005 §10).

Context: thread Blocking: no Timing: O(PI work), plus waiter requeue and profile-specific scheduling Ownership: none Configuration: Requirements: KRN-THR-022 KRN-SYNC-032 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EINVAL; EMB_EPERM for a kernel thread; EMB_EBUSY on the tiny profile when the new priority’s slot is taken.

Parameters:

thread – Initialized application thread whose base priority is to change.
priority – 1 .. EMB_PRIORITY_MAX.

uint8_t emb_thread_get_priority(emb_thread_t thread)¶

emb_thread_get_priority() - Base priority of thread

; 0 for a bad handle.

Context: thread isr Blocking: no Timing: O(1) Ownership: none Configuration: Requirements: KRN-THR-022 Since: 0.2 Stability: yes

Parameters:

thread – Initialized thread to inspect; returns 0 for an invalid handle.

uint8_t emb_thread_get_effective_priority(emb_thread_t thread)¶

emb_thread_get_effective_priority() - Effective priority of thread

(SPEC-005 §2.1).

Context: thread isr Blocking: no Timing: O(1) Ownership: none Configuration: Requirements: KRN-THR-022 KRN-SYNC-018 Since: 0.2 Stability: yes

Parameters:

thread – Initialized thread to inspect; returns 0 for an invalid handle.

void emb_thread_yield(void)¶

emb_thread_yield() - Move the caller behind equal-priority READY threads.

Never yields to a lower-priority thread (KRN-TIM-024). A no-op that keeps the reschedule pending while the scheduler is locked.

Context: thread Blocking: no Timing: O(1) Ownership: none Configuration: Requirements: KRN-TIM-024 KRN-IRQ-022 Since: 0.2 Stability: yes

emb_status_t emb_thread_sleep(emb_duration_t d)¶

emb_thread_sleep() - Block the caller for d

(SPEC-003 §6).

Context: thread Blocking: timeout Timing: O(timeouts) arm Ownership: none Configuration: Requirements: KRN-TIM-024 Since: 0.2 Stability: yes

Return: EMB_OK on expiry; EMB_ECANCELED.

Parameters:

d – Zero behaves as emb_thread_yield().

emb_status_t emb_thread_sleep_until(emb_instant_t t)¶

emb_thread_sleep_until() - Block the caller until the instant t

Context: thread Blocking: timeout Timing: O(timeouts) arm Ownership: none Configuration: Requirements: KRN-TIM-011 KRN-TIM-022 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_ECANCELED. In the 32-bit profile a deadline more than EMB_TIMEOUT_MAX_TICKS ahead is indistinguishable from a past one and yields.

Parameters:

t – A past instant behaves as emb_thread_yield().

emb_status_t emb_thread_state(emb_thread_t thread, uint8_t *out_state, uint8_t *out_reason)¶

emb_thread_state()

- Lifecycle state and, when BLOCKED, the wait reason.

Context: thread isr Blocking: no Timing: O(1) Ownership: none Configuration: Requirements: KRN-THR-025 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EINVAL.

Parameters:

thread – Initialized thread to inspect.
out_state – EMB_THREAD_INACTIVE .. EMB_THREAD_TERMINATED.
out_reason – EMB_WAIT_REASON_*; may be NULL.

const char *emb_thread_name(emb_thread_t thread)¶

emb_thread_name()

- The name given at init, or “” when none or names are compiled out.

Context: thread isr Blocking: no Timing: O(1) Ownership: none Configuration: Requirements: KRN-THR-025 Since: 0.2 Stability: yes

Parameters:

thread – Initialized thread whose borrowed name is returned; invalid handles return an empty string.

uint8_t emb_thread_index(emb_thread_t thread)¶

emb_thread_index()

- The current small thread index; 0xFF for a bad handle.

Context: thread isr Blocking: no Timing: O(1) Ownership: none Configuration: Requirements: KRN-THR-025 KRN-THR-029 Since: 0.2 Stability: yes

Parameters:

thread – Initialized thread to inspect. On tiny, the index follows its base-priority table slot.

emb_status_t emb_thread_stack_info(emb_thread_t thread, size_t *out_size, size_t *out_high_water)¶

emb_thread_stack_info() - Configured size and high-water mark of thread's

stack.

Context: thread Blocking: no Timing: O(stack) scan with statistics on Ownership: none Configuration: Requirements: KRN-THR-023 KRN-THR-025 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EINVAL.

Parameters:

thread – Initialized thread to inspect.
out_size – Configured size in bytes; may be NULL.
out_high_water – Fill-pattern estimate of bytes used; may be NULL, 0 when stats are off.

emb_status_t emb_tls_set(uint8_t slot, void *p)¶

emb_tls_set() - Store p in the caller’s TLS slot slot

(SPEC-008 §9).

Context: thread Blocking: no Timing: O(1) Ownership: none Configuration: CONFIG_EMB_TLS_SLOTS Requirements: KRN-THR-013 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EINVAL for a slot out of range.

Parameters:

slot – Slot index, 0 through CONFIG_EMB_TLS_SLOTS - 1.
p – Pointer to retain in that slot; NULL clears it. Pointee lifetime stays with the caller.

void *emb_tls_get(uint8_t slot)¶

emb_tls_get()

- Read a pointer from the calling thread TLS slot.

Context: thread Blocking: no Timing: O(1) Ownership: none Configuration: CONFIG_EMB_TLS_SLOTS Requirements: KRN-THR-013 Since: 0.2 Stability: yes

Return: the stored pointer, or NULL for an unset/out-of-range slot or a caller outside thread context. No allocation, copying or cleanup occurs.

Parameters:

slot – Slot index, 0 through CONFIG_EMB_TLS_SLOTS - 1.

void emb_thread_foreach(emb_thread_visit_t cb, void *arg)¶

emb_thread_foreach() - Call cb

for every thread object, under the scheduler lock.

Context: thread Blocking: no Timing: O(threads) plus callback costs and any reschedule at final unlock Ownership: none Configuration: CONFIG_EMB_THREAD_LIST Requirements: KRN-THR-025 Since: 0.2 Stability: yes

Parameters:

cb – Called under the scheduler lock; must not block or modify the thread registry. NULL is a no-op.
arg – Passed unchanged to each callback; needed only for the duration of traversal.

emb_status_t emb_thread_destroy(emb_thread_t thread)¶

emb_thread_destroy()

- Return the storage of an INACTIVE or joined/detached TERMINATED thread.

Context: thread Blocking: no Timing: O(1) Ownership: gives:storage Configuration: Requirements: KRN-OBJ-001 KRN-THR-024 Since: 0.2 Stability: yes

Return: EMB_OK; EMB_EBUSY (misuse) for any other state; EMB_EINVAL.

Parameters:

thread – INACTIVE or joined/detached TERMINATED application thread; successful destruction permits storage reuse.

struct emb_thread_t¶

#include <thread.h>

Public Members

uintptr_t raw¶

struct emb_thread_attr¶

#include <thread.h>

Public Members

const char *name¶

void *stack¶

size_t stack_size¶

uint8_t priority¶

uint8_t flags¶

uint8_t cpu_affinity¶

uint8_t reserved_¶