Skip to content

Add Linux IO::Event::Futex support - #210

Open
samuel-williams-shopify wants to merge 10 commits into
mainfrom
add-futex
Open

Add Linux IO::Event::Futex support#210
samuel-williams-shopify wants to merge 10 commits into
mainfrom
add-futex

Conversation

@samuel-williams-shopify

@samuel-williams-shopify samuel-williams-shopify commented Aug 21, 2026

Copy link
Copy Markdown
Contributor

Description

Add a Linux-only IO::Event::Futex backed by an aligned 32-bit word in an IO::Buffer. The platform primitive lives in futex.c/futex.h; uring.c contains only the optional io_uring integration.

The futex provides atomic value access, increment-and-wake signalling, single waits, and vector waits over up to IO::Event::Futex::WAITV_LIMIT futex words. Futex#wait returns whether it slept, while Futex.wait_any returns the index of the futex that woke or nil when an expected value had already changed.

When a fiber scheduler implements futex_wait or futex_waitv, the native methods delegate to it. The URing selector provides cancellable asynchronous implementations using IORING_OP_FUTEX_WAIT and IORING_OP_FUTEX_WAITV. Without a scheduler, the same native methods call the Linux futex syscalls while releasing the GVL. A scheduler that does not expose the corresponding optional hook raises NotImplementedError rather than blocking its reactor thread.

The class is defined only on Linux and does not require io_uring. The asynchronous selector hooks are exposed separately when io-event was compiled with a sufficiently recent liburing and the running kernel reports support for the corresponding opcodes.

Motivation

This provides a low-overhead shared-memory notification path for processes that already exchange state through IO::Buffer. Vector waits allow a coordinator such as Fantail to sleep until any worker permit changes without polling every worker. Consumers can capability-detect IO::Event::Futex and use a portable notification mechanism when it is unavailable.

Testing

  • Full test suite on macOS: 281 passed, 9 skipped.
  • RuboCop passes for all changed Ruby files.
  • Documentation coverage remains 100%: 93/93 definitions.
  • Dedicated Ubuntu CI builds liburing 2.6 and requires both Futex.wait_any and selector futex_waitv support.
  • Linux tests exercise synchronous no-scheduler waits, scheduler-driven io_uring waits, value mismatches, independent futex words, the exported wait-vector limit, and vector wake indices.

The local Colima VM does not permit io_uring setup under its seccomp policy, so the native asynchronous runtime path is covered by the dedicated Linux CI job.

@samuel-williams-shopify samuel-williams-shopify changed the title Add IO::Event::Futex using io_uring Add Linux IO::Event::Futex support Aug 21, 2026
Comment thread .github/workflows/test-futex.yaml Outdated
Assisted-By: devx/065220da-7d48-4279-a513-aedd3bbfa4da
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants