Trait PlatformThreading 

pub trait PlatformThreading {
    // Required methods
    fn task_init(
        task: *mut c_void,
        attr: *mut c_void,
        entry: Option<unsafe extern "C" fn(*mut c_void) -> *mut c_void>,
        arg: *mut c_void,
    ) -> i8;
    fn task_join(task: *mut c_void) -> i8;
    fn task_detach(task: *mut c_void) -> i8;
    fn task_cancel(task: *mut c_void) -> i8;
    fn task_exit();
    fn task_free(task: *mut *mut c_void);
    fn mutex_init(m: *mut c_void) -> i8;
    fn mutex_drop(m: *mut c_void) -> i8;
    fn mutex_lock(m: *mut c_void) -> i8;
    fn mutex_try_lock(m: *mut c_void) -> i8;
    fn mutex_unlock(m: *mut c_void) -> i8;
    fn mutex_rec_init(m: *mut c_void) -> i8;
    fn mutex_rec_drop(m: *mut c_void) -> i8;
    fn mutex_rec_lock(m: *mut c_void) -> i8;
    fn mutex_rec_try_lock(m: *mut c_void) -> i8;
    fn mutex_rec_unlock(m: *mut c_void) -> i8;
    fn condvar_init(cv: *mut c_void) -> i8;
    fn condvar_drop(cv: *mut c_void) -> i8;
    fn condvar_signal(cv: *mut c_void) -> i8;
    fn condvar_signal_all(cv: *mut c_void) -> i8;
    fn condvar_wait(cv: *mut c_void, m: *mut c_void) -> i8;
    fn condvar_wait_until(cv: *mut c_void, m: *mut c_void, abstime: u64) -> i8;

    // Provided methods
    fn task_stack_unused_bytes() -> usize { ... }
    fn condvar_signal_from_isr(cv: *mut c_void) -> i8 { ... }
    fn wake_init(_w: *mut c_void) -> i8 { ... }
    fn wake_drop(_w: *mut c_void) -> i8 { ... }
    fn wake_wait_ms(_w: *mut c_void, _timeout_ms: u32) -> i8 { ... }
    fn wake_signal(_w: *mut c_void) -> i8 { ... }
    fn wake_signal_from_isr(w: *mut c_void) -> i8 { ... }
    fn wake_storage_size() -> usize { ... }
    fn wake_storage_align() -> usize { ... }
    fn task_storage_size() -> usize { ... }
    fn task_storage_align() -> usize { ... }
    fn mutex_storage_size() -> usize { ... }
    fn mutex_storage_align() -> usize { ... }
    fn mutex_rec_storage_size() -> usize { ... }
    fn mutex_rec_storage_align() -> usize { ... }
    fn condvar_storage_size() -> usize { ... }
    fn condvar_storage_align() -> usize { ... }
}

Threading primitives: tasks, mutexes, and condition variables.

Threading

Mutex / condvar operations must be safe under concurrent callers. Recursive mutex (mutex_rec_*) must support same-thread re-entrancy — zenoh-pico relies on this; a non-recursive mutex backing mutex_rec_* deadlocks under load.

ISR-safety

None of these methods are ISR-safe on hosted RTOSes (FreeRTOS / NuttX / Zephyr / ThreadX) — the underlying primitives panic or error when invoked from an ISR. Only core::hint::spin_loop() in PlatformYield::yield_now is.

For single-threaded platforms (bare-metal), all operations should be no-ops returning 0, except task_init which should return -1.

Required Methods

fn task_init( task: *mut c_void, attr: *mut c_void, entry: Option<unsafe extern "C" fn(*mut c_void) -> *mut c_void>, arg: *mut c_void, ) -> i8

Spawn a new task. task is opaque caller-provided storage; attr carries scheduling hints (priority, stack size) or null for defaults; entry is the task entry point; arg is forwarded to entry. Returns 0 on success, non-zero on failure.

fn task_join(task: *mut c_void) -> i8

Block until task exits. Cleans up the task storage on success.

fn task_detach(task: *mut c_void) -> i8

Mark task as detached — its storage is reclaimed on exit without a join.

fn task_cancel(task: *mut c_void) -> i8

Request task to terminate at the next cancellation point. Cooperative.

fn task_exit()

Terminate the calling task immediately. Does not return.

fn task_free(task: *mut *mut c_void)

Free the task storage allocated by task_init.

fn mutex_init(m: *mut c_void) -> i8

Initialise a non-recursive mutex in caller-provided storage.

fn mutex_drop(m: *mut c_void) -> i8

Tear down a non-recursive mutex.

fn mutex_lock(m: *mut c_void) -> i8

Lock; block if held.

fn mutex_try_lock(m: *mut c_void) -> i8

Try to lock; non-zero return immediately if held.

fn mutex_unlock(m: *mut c_void) -> i8

Unlock; only the owning thread may call this.

fn mutex_rec_init(m: *mut c_void) -> i8

Initialise a recursive mutex (same-thread re-entrancy permitted). Required by zenoh-pico.

fn mutex_rec_drop(m: *mut c_void) -> i8

Tear down a recursive mutex.

fn mutex_rec_lock(m: *mut c_void) -> i8

Lock; re-entry from the owning thread must succeed.

fn mutex_rec_try_lock(m: *mut c_void) -> i8

Try to lock; same re-entry semantics as mutex_rec_lock.

fn mutex_rec_unlock(m: *mut c_void) -> i8

Unlock; releases when the lock count returns to zero.

fn condvar_init(cv: *mut c_void) -> i8

Initialise a condition variable in caller-provided storage.

fn condvar_drop(cv: *mut c_void) -> i8

Tear down a condition variable.

fn condvar_signal(cv: *mut c_void) -> i8

Wake one waiter on the condition variable.

fn condvar_signal_all(cv: *mut c_void) -> i8

Wake all waiters on the condition variable.

fn condvar_wait(cv: *mut c_void, m: *mut c_void) -> i8

Atomically release m and block on cv. The mutex is re-acquired before this function returns.

fn condvar_wait_until(cv: *mut c_void, m: *mut c_void, abstime: u64) -> i8

Wait with absolute monotonic deadline (milliseconds since the PlatformClock::clock_ns epoch). Returns non-zero on timeout.

Provided Methods

fn task_stack_unused_bytes() -> usize

Smallest number of bytes ever left unused on the CALLING task’s stack, or 0 if this platform does not instrument it.

Defaulted so every existing impl keeps compiling: a port that says nothing reports 0, which the ABI documents as “not instrumented” rather than “no headroom left”.

fn condvar_signal_from_isr(cv: *mut c_void) -> i8

Phase 124.B.7.a — ISR-safe variant of Self::condvar_signal. Callable from interrupt / signal-handler context. Backends implement via async-signal-safe primitives (POSIX: pipe write forwarded by a worker thread — Linux may use eventfd, which is a Linux syscall and not POSIX; RTOS: xSemaphoreGiveFromISR, tx_event_flags_set from ISR, k_sem_give from ISR). Returns non-zero when the backend has no ISR-safe path — caller can fall back to condvar_signal (with the obvious latency cost).

Default body: forward to condvar_signal. POSIX and other backends override to use their async-signal-safe primitive.

fn wake_init(_w: *mut c_void) -> i8

Initialise a binary-semaphore-shaped wake primitive in caller-provided storage. See <nros/platform.h> for the per-platform backing primitive (POSIX sem_t, Zephyr k_sem, FreeRTOS xSemaphoreBinary, …). Default returns -1 (unsupported).

fn wake_drop(_w: *mut c_void) -> i8

Tear down a wake primitive. Default returns -1 (unsupported).

fn wake_wait_ms(_w: *mut c_void, _timeout_ms: u32) -> i8

Block until signaled or timeout_ms elapses. Returns 0 on signal, 1 on timeout, -1 on error. Default returns -1 (unsupported).

fn wake_signal(_w: *mut c_void) -> i8

Wake one waiter. Idempotent — a signal pending when another arrives is coalesced (the primitive stays at value 1). Default returns -1 (unsupported).

fn wake_signal_from_isr(w: *mut c_void) -> i8

ISR-safe signal. Returns -1 when the backend has no ISR path; callers may fall back to wake_signal (with the obvious latency cost). Default forwards to wake_signal.

fn wake_storage_size() -> usize

Caller-storage size requirement (bytes). Default 0 — signals “no wake primitive available”. May be called before wake_init.

fn wake_storage_align() -> usize

Caller-storage alignment requirement (bytes). Default 1.

fn task_storage_size() -> usize

Caller-storage size requirement (bytes) for a task handle.

phase-359 W10 added these probes to platform.h and to the C ports but not to this trait or the export macro, so check-platform-abi-mirror saw a header symbol with no Rust emission. Same contract as the wake pair above: default 0 means “this platform cannot start a task”, which is the honest answer for a port whose task_init always fails, and it is safe to call before task_init.

fn task_storage_align() -> usize

Caller-storage alignment requirement (bytes) for a task handle. Default 1.

fn mutex_storage_size() -> usize

Caller-storage size requirement (bytes) for a plain mutex.

phase-364 W2 declared the lock family’s probes in platform.h without the trait or macro halves — the same shape phase-359 W10 left for task, one commit later. Defaults match the pair above: 0 size means “this platform offers no such primitive”, 1 alignment is the no-constraint answer, and both are safe to call before any *_init.

fn mutex_storage_align() -> usize

Caller-storage alignment requirement (bytes) for a plain mutex.

fn mutex_rec_storage_size() -> usize

Caller-storage size requirement (bytes) for a RECURSIVE mutex.

fn mutex_rec_storage_align() -> usize

Caller-storage alignment requirement (bytes) for a recursive mutex.

fn condvar_storage_size() -> usize

Caller-storage size requirement (bytes) for a condition variable.

fn condvar_storage_align() -> usize

Caller-storage alignment requirement (bytes) for a condition variable.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors