io-event 1.22.1 → 1.22.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a02e2dca1e03b9cb6e7a23525af5e35bac78cb0d3661ff0d219d4f5f115baac3
-  data.tar.gz: aaaf14ed6534424afca5f46cf867c3b5d9e323a12328e58c0c28ab0e7578e06c
+  metadata.gz: 01f54cee2259c78ebfd5c7c55614d8bc0a4d5509e410c0b5e1729838dba13a5c
+  data.tar.gz: 5879a047f144aeb781e3ee2f159b2bd53770ff6a6fa1f5eeb44e6800e598a9a4
 SHA512:
-  metadata.gz: cd3db9299b34ec8e6143b1fb303da42002ec263cfd90987d5ec693889ab03edc8b3deeee7137596ae17e327e2efa42a89fbc6d89e70c718121ed5780900362fc
-  data.tar.gz: f0821c42ff1a0f135a11e59700229236b6d64a408a4dde1c18c9ee637b775c2701d9df877656070d3c312829f3b46c7679129d928839825fb70dd60fc434f6a5
+  metadata.gz: 7eabcaf11cb0467cc87270cae4db7532473d0bf1ed0eee7b709d0792214f416d217af1c2ef1cfccefcaa856444f1ed50fcd2cbecdbe55725eb44f4765c283329
+  data.tar.gz: 904d807808513f5e6d36a70eef168ec1a972e0c31395529b50e014ca9a47e080eddd14494b3e06f485ed33682c94df19394b5000c217be63523879e9d19eedae

data/context/futex.md

@@ -0,0 +1,208 @@
+# Futex Notifications
+
+This guide explains how to use `IO::Event::Futex` to notify threads or processes when shared state changes, without continuously polling it.
+
+Shared state describes what changed; the futex tells you to check it. A wake-up does not transfer a message, reserve a worker, or grant ownership of a permit.
+
+## Availability
+
+`IO::Event::Futex` is available on Linux with Ruby 4.1 or later and the required Linux build headers. It uses Ruby's counted buffer locks to retain an aligned, writable 32-bit word. The class itself does not require `io_uring`.
+
+There are two ways to wait:
+
+- Without an active fiber scheduler for the calling fiber, waits release the GVL and block the calling thread using Linux futex syscalls.
+- With a scheduler, waits invoke its optional `futex_wait` or `futex_waitv` hook. A missing hook raises `NotImplementedError`; it does not silently block the event loop.
+
+Only the URing selector provides asynchronous futex waits. EPoll, KQueue, and Select do not. URing exposes each method only when the build's liburing and the running kernel support the corresponding operation. Check the selected backend before choosing an IPC mechanism:
+
+```ruby
+require "io/event"
+
+selector = IO::Event::Selector.new(Fiber.current)
+begin
+	futex_available = IO::Event.const_defined?(:Futex, false)
+	puts "Single waits: #{futex_available && selector.respond_to?(:futex_wait)}"
+	puts "Vector waits: #{futex_available && selector.respond_to?(:futex_waitv)}"
+ensure
+	selector.close
+end
+```
+
+Creating a selector does not install a fiber scheduler. A scheduler integration must forward the following hooks to its own selector, and should only expose hooks that selector supports:
+
+| Scheduler hook | Selector call |
+| --- | --- |
+| `futex_wait(futex, expected)` | `selector.futex_wait(Fiber.current, futex, expected)` |
+| `futex_waitv(entries)` | `selector.futex_waitv(Fiber.current, entries)` |
+
+For blocking vector waits, `IO::Event::Futex.respond_to?(:wait_any)` indicates build support, not running-kernel support; the syscall can still raise `Errno::ENOSYS`. Deployment restrictions can also prevent kernel operations. Negotiate capabilities before peers begin waiting, and choose a socket, pipe, or an IPC protocol such as `async-bus` when asynchronous futex waits are unavailable. There is no automatic IPC fallback in `Futex`.
+
+## Binding Shared Memory
+
+Each futex refers to four bytes at a byte offset within an `IO::Buffer`. The address must be aligned to four bytes, and the buffer must have at least four bytes remaining at that offset. The default offset is zero. Constructing a futex preserves the word's existing value.
+
+```ruby
+require "io/event"
+
+buffer = IO::Buffer.new(8)
+first = IO::Event::Futex.new(buffer)
+second = IO::Event::Futex.new(buffer, offset: 4)
+
+begin
+	first.value = 0
+	second.value = 0
+	first.signal
+	puts first.value # => 1
+ensure
+	first.close
+	second.close
+	buffer.free
+end
+```
+
+An ordinary `IO::Buffer.new` allocation is suitable for threads in one process. Forking does not make that allocation shared between processes. For IPC, map shared storage instead: for example, each process can use `IO::Buffer.map(file, size)` on the same pre-sized file opened for reading and writing, without `IO::Buffer::PRIVATE`. Bind futexes at matching offsets in that mapping; virtual addresses need not match between processes.
+
+Initialize the shared words once, before peers attach. Attaching peers must not reset live state. Futexes do not discover peers or transport Ruby objects; the application supplies the shared-state layout and synchronization protocol.
+
+## Atomic Operations and Notifications
+
+| Operation | Effect and return value |
+| --- | --- |
+| `value` | Atomically reads the word. |
+| `value = n` | Atomically stores `n`. |
+| `increment(amount = 1)` | Adds `amount` and returns the new value. |
+| `decrement(amount = 1)` | Subtracts `amount` and returns the new value. |
+| `compare_exchange(expected, desired)` | Stores `desired` only if the word equals `expected`; returns whether it succeeded. |
+| `wake(count = 1)` | Wakes at most `count` waiters without changing the word; returns the number woken. |
+| `signal(count = 1)` | For a positive count, increments the word by one, then wakes at most `count` waiters; returns the word value. |
+
+Loads use acquire ordering, stores use release ordering, and read-modify-write operations use acquire-release ordering. A failed compare-and-exchange uses acquire ordering. Arithmetic wraps modulo `2**32`; a notification counter is not an indefinitely increasing event history.
+
+Only `wake` and `signal` notify sleeping waiters. Assignment, increment, decrement, and compare-and-exchange do not wake them. For a positive count, `signal` performs an atomic increment followed by a wake syscall, not one indivisible increment-and-wake operation. Its argument is the waiter count, not the increment amount. Wake counts must be nonnegative integers that fit in a C `int`.
+
+Both `wake(0)` and `signal(0)` are no-ops: they leave the word and waiters unchanged. `wake(0)` returns `0`; `signal(0)` returns the current word value. Closed or uninitialized futexes still raise `IOError`.
+
+Publish application state before notifying consumers. A futex does not make other memory accesses atomic or provide a queue's synchronization. Use atomic operations or another suitable synchronization protocol for that state, and do not mix concurrent non-atomic buffer accesses with atomic accesses to the futex word.
+
+## Waiting Without Missing Notifications
+
+`futex.wait(expected)` requires an explicit expected value and asks the kernel to wait only if the word still equals it. Comparing the word and beginning the wait is atomic with respect to futex operations. If the value has already changed, the call returns `false` without sleeping; a successful wake returns `true`. Omitting `expected` raises `ArgumentError`.
+
+Always recheck application state after a wait. Wake-ups can be spurious, another consumer may have taken the available work, and waking a waiter does not guarantee FIFO ordering or ownership. System errors raise exceptions. Neither wait API currently accepts a timeout argument.
+
+When the word is a notification counter for separate application state, the consumer must:
+
+1. Read the notification counter.
+2. Check or attempt to consume the synchronized application state.
+3. If no work is available, wait using the saved counter value.
+4. Repeat after the wait returns.
+
+The producer publishes work before incrementing the counter and waking consumers. If a producer publishes between steps 2 and 3, the changed counter prevents the consumer from sleeping.
+
+### Why the Expected Value Is Required
+
+Reading the counter *after* checking for work can miss a notification:
+
+1. The consumer finds the queue empty. The notification counter is `0`.
+2. The producer adds work and signals, changing the counter to `1`. Nobody is waiting yet.
+3. The consumer reads the counter and gets `1`.
+4. The consumer calls `wait(1)`. Since the counter is still `1`, it sleeps despite available work. Without another notification, it can remain asleep indefinitely.
+
+An argument-free `wait` would hide step 3 inside the method. Requiring `expected` makes the snapshot explicit: the consumer should capture `0` before checking the queue, then call `wait(0)`. In the same sequence, the kernel sees that the counter is now `1` and returns immediately. If the consumer starts waiting before the producer signals, the signal wakes it instead.
+
+The required argument does not enforce the ordering by itself. Calling `wait(futex.value)` after checking for work has the same race. The intended sequence is **snapshot, check state, then wait using that snapshot**, followed by another state check after the wait returns.
+
+### Producer and Consumer
+
+This example uses a thread-safe Ruby `Queue` for application state and a futex for notifications. `Queue` already supports blocking `pop`; the explicit wait here demonstrates the protocol you would use with your own shared state. This particular queue is local to one process, not an IPC queue.
+
+```ruby
+require "io/event"
+
+buffer = IO::Buffer.new(4)
+notification = IO::Event::Futex.new(buffer)
+notification.value = 0
+queue = Thread::Queue.new
+
+producer = Thread.new do
+	["first", "second", "third", nil].each do |message|
+		queue << message
+		notification.signal
+	end
+end
+
+begin
+	loop do
+		# Snapshot before checking application state:
+		expected = notification.value
+		
+		begin
+			message = queue.pop(true)
+		rescue ThreadError
+			notification.wait(expected)
+			next
+		end
+		
+		# A nil message marks the end of this example:
+		break if message.nil?
+		puts message
+	end
+ensure
+	producer.join
+	notification.close
+	buffer.free
+end
+```
+
+The queue retains work even when a notification wakes nobody. Notifications may be coalesced; consumers must inspect the state rather than count wake-ups. A 32-bit counter can wrap back to a saved value, so protocols must account for wraparound if a consumer could miss an entire counter cycle between its snapshot and wait.
+
+## Waiting on Several Words
+
+When supported, `IO::Event::Futex.wait_any(entries)` waits on a vector of `[futex, expected]` pairs. Supply between one and `IO::Event::Futex::WAITV_LIMIT` entries. It returns a zero-based index when woken, or `nil` if any word does not match its expected value. The index is a notification hint, not an exhaustive list of changes or a claim on the associated resource.
+
+For example, wait until either of two initially-zero words is nonzero:
+
+```ruby
+require "io/event"
+
+buffer = IO::Buffer.new(8)
+first = IO::Event::Futex.new(buffer)
+second = IO::Event::Futex.new(buffer, offset: 4)
+first.value = second.value = 0
+
+producer = Thread.new{second.signal}
+
+begin
+	while first.value == 0 && second.value == 0
+		IO::Event::Futex.wait_any([[first, 0], [second, 0]])
+	end
+	puts "At least one word changed."
+ensure
+	producer.join
+	first.close
+	second.close
+	buffer.free
+end
+```
+
+For notification counters alongside separate state, snapshot all counters before checking that state, just as with a single wait. Vector waits retain a private snapshot of the supplied futex references; mutating the original entries does not change an already-pending wait.
+
+## Lifetime and Cancellation
+
+Each futex owns one counted allocation lock from construction until `close` or finalization. Slices lock their root allocation, and multiple words can independently retain the same allocation. The lock prevents freeing, resizing, or transferring that allocation; it does not prevent writing shared state.
+
+`close` is idempotent, and `closed?` reports whether the futex has been released. Word operations and waits on closed or uninitialized instances raise `IOError`. Futexes cannot be copied or reinitialized. A finalizer releases the lock if a futex is collected, but explicit `close` makes release deterministic. Avoid application references from the retained buffer back to its futex, which would keep it reachable through the finalizer.
+
+A futex with pending waits cannot be closed: `close` raises `IOError` rather than cancelling or waking those waits. For orderly shutdown:
+
+1. Publish shutdown state and notify the necessary waiters, or cancel them through the scheduler.
+2. Let the waits finish, including cancellation cleanup.
+3. Close all futexes, then free or unmap the buffer.
+
+URing cancellation drains the original kernel operation before releasing its retained references or wait vector. Keep the event loop running until that cleanup completes. Exceptions still propagate; if a wait is resumed out of band without an exception, it can instead return `false` for a single wait or `nil` for a vector wait. These returns still require rechecking application state.
+
+Allocation locks cannot protect against an external owner releasing memory or another process truncating a mapped file. The application must preserve the underlying storage for every process that can still access it.
+
+## Further Reading
+
+The Linux [futex overview](https://man7.org/linux/man-pages/man2/futex.2.html), [FUTEX_WAIT](https://man7.org/linux/man-pages/man2/FUTEX_WAIT.2const.html), and [FUTEX_WAKE](https://man7.org/linux/man-pages/man2/FUTEX_WAKE.2const.html) documentation describe the underlying shared-memory and notification semantics.

data/context/getting-started.md

@@ -76,6 +76,12 @@ puts "[main] Done"
 # [main] Done
 ```
 
+## Shared-Memory Notifications
+
+On Linux with Ruby 4.1 or later, `IO::Event::Futex` provides atomic operations and notifications on an aligned 32-bit word in an `IO::Buffer`. It supports blocking thread waits and optional asynchronous waits through the URing selector.
+
+See the [Futex Notifications guide](../futex/index) for capability detection, shared-memory setup, wait/recheck examples, vector waits, and buffer lifetime management.
+
 ## Debugging
 
 The {ruby IO::Event::Debug::Selector} class adds extra validations and checks at the expense of performance. It can also log all operations. You can use this by setting the following environment variables:

data/context/index.yaml

@@ -9,3 +9,7 @@ files:
 - path: getting-started.md
   title: Getting Started
   description: This guide explains how to use `io-event` for non-blocking IO.
+- path: futex.md
+  title: Futex Notifications
+  description: This guide explains how to use `IO::Event::Futex` to notify threads
+    or processes when shared state changes, without continuously polling it.

data/ext/extconf.rb

@@ -31,9 +31,16 @@ $VPATH << "$(srcdir)/io/event/selector"
 
 have_func("rb_ext_ractor_safe")
 have_func("&rb_fiber_transfer")
+have_io_buffer = have_header("ruby/io/buffer.h")
+
+if RUBY_PLATFORM.include?("linux") && have_io_buffer && have_header("linux/futex.h") && have_header("sys/syscall.h")
+	$srcs << "io/event/futex.c"
+end
 
 if have_library("uring") and have_header("liburing.h")
 	have_func("io_uring_prep_waitid", "liburing.h")
+	have_func("io_uring_prep_futex_wait", "liburing.h")
+	have_func("io_uring_prep_futex_waitv", "liburing.h")
 	$srcs << "io/event/selector/uring.c"
 end
 
@@ -57,8 +64,6 @@ have_func("rb_fiber_current")
 have_func("&rb_fiber_raise")
 have_func("epoll_pwait2(0, 0, 0, 0, 0)", "sys/epoll.h") if enable_config("epoll_pwait2", true)
 
-have_header("ruby/io/buffer.h")
-
 # Feature detection for blocking operation support
 if have_func("rb_fiber_scheduler_blocking_operation_extract")
 	# Feature detection for pthread support (needed for WorkerPool)

data/ext/io/event/event.c

@@ -3,6 +3,7 @@
 
 #include "event.h"
 #include "fiber.h"
+#include "futex.h"
 #include "selector/selector.h"
 
 void Init_IO_Event(void)
@@ -15,6 +16,10 @@ void Init_IO_Event(void)
 	
 	Init_IO_Event_Fiber(IO_Event);
 
+	#ifdef IO_EVENT_FUTEX
+	Init_IO_Event_Futex(IO_Event);
+	#endif
+
 	#ifdef HAVE_IO_EVENT_WORKER_POOL
 	Init_IO_Event_WorkerPool(IO_Event);
 	#endif