ecmascript_futex

Cross platform library for implementing ECMAScript Atomics.wait, Atomics.wakeAsync, and Atomics.notify (aka futex) functionality in Rust, operating on ECMAScript memory as produced by the ecmascript_atomics crate. This crate is a fork of wait_on_address which is itself a fork of atomic-wait. The changes inherited and kept from wait_on_address are:

• Support for waiting with a timeout.
• Support for wasm32 on nightly using std::arch.
• Polyfill for all other platforms.

The API has been heavily modified; the wait APIs return the result of the wait to the extent that the OS APIs provide it, while the notify APIs report how many threads were woken up, again to the extent that the OS APIs provide such information.

Natively-supported platforms:

• Windows 8+, Windows Server 2012+
• macOS 14.4+, iOS 17.4+, watchOS 10.4+
• Linux 2.6.22+ (using fallback for 64-bit futexes)
• wasm32
• All other platforms with std support (using fallback)

Usage

use core::time::Duration;
use ecmascript_atomics::{Racy, RacyBox};
use ecmascript_futex::ECMAScriptAtomicWait;

let a = RacyBox::new(0u64).unwrap();
let a = a.as_slice().get(0).unwrap();

a.wait(1); // If the value is 1, wait.

a.wait_timeout(2, Duration::from_millis(100));  // If the value is 2, wait at most 100 milliseconds

a.notify_many(1); // Wake one waiting thread.

a.notify_all(); // Wake all waiting threads.

Implementation

On Linux, this uses the SYS_futex syscall.

On FreeBSD, this uses the _umtx_op syscall.

On Windows, this uses the WaitOnAddress and WakeByAddress APIs.

On macOS (and iOS and watchOS), this uses the os_sync_wait_on_address and os_sync_wake_by_address APIs.

On wasm32 with nightly, this uses memory_atomic_wait32, memory_atomic_wait64, and memory_atomic_notify instructions.

All other platforms with std support fall back to a fixed-size hashmap of Condvars, similar to libstdc++'s implementation for std::atomic<T>.