Crate indexbus_wake 

OS-backed wait/wake primitives for IndexBus.

This crate provides thin wrappers around platform “wait on address” primitives for an aligned u32:

• Linux: futex (FUTEX_WAIT|PRIVATE / FUTEX_WAKE|PRIVATE)
• Windows: WaitOnAddress / WakeByAddressSingle / WakeByAddressAll

These are intended for blocking adapters and higher-level async integration.

Feature flags

• std (default): enables std::fmt::Display and std::error::Error for WaitError. The wait/wake functions themselves only depend on core, but still require an OS.

Correctness notes

These primitives are parking mechanisms, not a full synchronization protocol:

• Waits may return spuriously (a wake can unblock a waiter even if the value is still equal).
• Wakes are not queued; a wake that happens before a thread actually sleeps can be lost.
• wait_u32_eq does not establish a happens-before edge for your data by itself.

Higher-level code should use the standard “sequence” pattern:

• Writer: update shared data, then store(seq + 1, Ordering::Release), then call wake_*.
• Reader: load(Ordering::Acquire) and, if unchanged, call wait_u32_eq in a loop.

Minimal usage

use core::time::Duration;
use indexbus_wake::{wait_u32_eq, wake_one};
use std::sync::atomic::{AtomicU32, Ordering};

let seq = AtomicU32::new(0);
let addr = &seq as *const AtomicU32 as *const u32;

// SAFETY: `addr` is aligned/valid for the call, and the location is mutated race-free via
// the `AtomicU32` at the same address.
unsafe {
    // Typical reader-side pattern: re-check the condition in a loop around this call.
    let _ = wait_u32_eq(addr, 0, Some(Duration::from_millis(10)));
}

seq.store(1, Ordering::Release);
unsafe { wake_one(addr) };

Enums

WaitError

Errors returned by platform wait primitives.

Functions

wait_u32_eq^⚠

Wait while the 32-bit value at addr equals expected.

wake_all^⚠

Wake all waiters blocked on addr.

wake_one^⚠

Wake a single waiter blocked on addr.