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 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 { ... }
}

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_ms epoch). Returns non-zero on timeout.

Provided Methods

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: eventfd write forwarded by a worker thread; 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.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors