#futex #cross-platform #atomic #wait #wake #macos #macos-ios

no-std atomic-wait

Cross-platform atomic wait and wake (aka futex) functionality

5 releases (3 stable)

1.1.0 Jan 2, 2023
1.0.1 Sep 27, 2022
0.2.0 Sep 25, 2022
0.1.0 Sep 16, 2022

#233 in Concurrency

Download history 1108/week @ 2024-12-02 1982/week @ 2024-12-09 1883/week @ 2024-12-16 824/week @ 2024-12-23 1467/week @ 2024-12-30 2794/week @ 2025-01-06 2842/week @ 2025-01-13 2679/week @ 2025-01-20 2945/week @ 2025-01-27 3125/week @ 2025-02-03 2910/week @ 2025-02-10 2475/week @ 2025-02-17 3953/week @ 2025-02-24 3628/week @ 2025-03-03 3476/week @ 2025-03-10 4400/week @ 2025-03-17

15,562 downloads per month
Used in 20 crates (15 directly)

BSD-2-Clause

10KB
151 lines

Cross platform atomic wait and wake (aka futex) functionality.

This crate only supports functionality that's available on all of Linux, FreeBSD, Windows, and macOS. That is:

  • Only AtomicU32 is supported. (Linux currently only supports 32-bit futexes.)
  • Only the "wait", "wake one", and "wake all" operations are supported. (Linux supports more operations, but Windows and macOS don't.)
  • No timeouts. (macOS doesn't have a stable/public API for timeouts.)
  • The wake operations don't return the number of threads woken up. (Only Linux supports this.)

Supported platforms: Linux 2.6.22+, FreeBSD 11+, Windows 8+, Windows Server 2012+, macOS 11+, iOS 14+, watchOS 7+.

Usage

use std::sync::atomic::AtomicU32;
use atomic_wait::{wait, wake_one, wake_all};

let a = AtomicU32::new(0);

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

wake_one(&a); // Wake one waiting thread.

wake_all(&a); // 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 libc++, making use of the same (ABI-stable) functions behind C++20's atomic_wait and atomic_notify functions.

Dependencies

~0–12MB
~72K SLoC