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_until(cv: *mut c_void, m: *mut c_void, abstime: u64) -> i8;

    // Provided methods
    fn task_stack_unused_bytes() -> usize { ... }
    fn task_stack_unused_bytes_upto(limit: usize) -> 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_park_until_us(_w: *mut c_void, _deadline_us: u64) -> i8 { ... }
    fn wake_park_granularity_us() -> u64 { ... }
    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_until(cv: *mut c_void, m: *mut c_void, abstime: u64) -> i8

Atomically release m and block on cv until signalled or until the absolute monotonic deadline abstime (milliseconds since the PlatformClock::clock_ns epoch); the mutex is re-acquired before this returns. Returns 0 when signalled, 1 on timeout and -1 on error (issue 1906). The remaining time rounds UP to the port’s tick.

The ONLY condvar wait: the unbounded condvar_wait was removed from the platform ABI (issue 1196, phase-436 D2). A caller whose contract is unbounded loops over bounded waits, re-testing its predicate.

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 task_stack_unused_bytes_upto(limit: usize) -> usize

task_stack_unused_bytes, capped at limit, reading at most limit bytes of the stack (phase-436 E5).

The default is the full query, capped, which is right for a port whose measurement is already cheap or absent. A port that SCANS for paint overrides it to read only the limit bytes at the deep end; see nros_platform_task_stack_unused_bytes_upto in nros/platform.h.

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_park_until_us(_w: *mut c_void, _deadline_us: u64) -> i8

phase-436 W7 — OPTIONAL microsecond park.

wake_wait_ms is the required primitive and floors every wait at a millisecond through its own signature; this is the same wait without that floor, for kernels whose timeout type is finer (issue 1242).

w MUST be the executor’s own wake object: the backend’s listener signals that one, and a park on anything else cannot be broken by data arriving.

Default -1 — “cannot park”, which leaves the executor on the millisecond path it already had. A port that can do better overrides.

fn wake_park_granularity_us() -> u64

The finest park wake_park_until_us can express, in microseconds.

Default 0 — “no finer park offered”. An RTOS tick is a coarser limit than the ABI signature (ThreadX ticks at 100 Hz) and a timespec primitive a finer one, so only the port can answer (issue 1242).

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".

Implementations on Foreign Types

impl PlatformThreading for CffiPlatform

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_signal_from_isr(cv: *mut c_void) -> i8

fn condvar_wait_until(cv: *mut c_void, m: *mut c_void, abstime: u64) -> 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

Implementors