io-event 1.10.2 → 1.12.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 643309e8464f787b038f0d7a83470e1b4750989455329081a59924c8ba4c1f43
-  data.tar.gz: 449bd6b5a87a17f826eaaa6f8d62102641a1722d8a49d4cf3f3036bbff6252c1
+  metadata.gz: 15970f96a2af0de9aa23889ee6ff50217b53216334de39ad5b4692ebf945942b
+  data.tar.gz: 5f44f0dbcdf09106e342e3fda71f56f8a0208dc5a435e82f8c80b1fdb8826fae
 SHA512:
-  metadata.gz: 34cd0ddcba1cc3a67cbf586cacb12a87b07c7f12a2b32d05f6d6a2d288ec50c6f7a53df5be6b8458f479e887831ec74ff395253021a0a5b6af0b7166bbb41f58
-  data.tar.gz: 1e13343fea3e66597dc67e4f671df961fa967d8bb09d3c9b5b706e866b250431ec9bac01c49df994c3e7859497ed14a4b8cfe31aa03856dc66bc43aff18f7a5e
+  metadata.gz: 0b72815ede642358071d66b9720935603493b6a09a34fcf2eec6930c8648a7d2b6498358f630554f40c6537f2bd0fb3cb6b58334ad58dfbaacc5d6c1f0e407cf
+  data.tar.gz: a5eb4e8396cd510aa71e8ee45f8ebf60829ca707a96bded1104ce0c3f74c47e9343225d826c58e4ec7bcfed6aed81051d7c14a10f304c42fa61fe930e1099fef

data/agent.md

@@ -0,0 +1,47 @@
+# Agent
+
+## Context
+
+This section provides links to documentation from installed packages. It is automatically generated and may be updated by running `bake agent:context:install`.
+
+**Important:** Before performing any code, documentation, or analysis tasks, always read and apply the full content of any relevant documentation referenced in the following sections. These context files contain authoritative standards and best practices for documentation, code style, and project-specific workflows. **Do not proceed with any actions until you have read and incorporated the guidance from relevant context files.**
+
+### agent-context
+
+Install and manage context files from Ruby gems.
+
+#### [Usage Guide](.context/agent-context/usage.md)
+
+`agent-context` is a tool that helps you discover and install contextual information from Ruby gems for AI agents. Gems can provide additional documentation, examples, and guidance in a `context/` ...
+
+### decode
+
+Code analysis for documentation generation.
+
+#### [Getting Started with Decode](.context/decode/getting-started.md)
+
+The Decode gem provides programmatic access to Ruby code structure and metadata. It can parse Ruby files and extract definitions, comments, and documentation pragmas, enabling code analysis, docume...
+
+#### [Documentation Coverage](.context/decode/coverage.md)
+
+This guide explains how to test and monitor documentation coverage in your Ruby projects using the Decode gem's built-in bake tasks.
+
+#### [Ruby Documentation](.context/decode/ruby-documentation.md)
+
+This guide covers documentation practices and pragmas supported by the Decode gem for documenting Ruby code. These pragmas provide structured documentation that can be parsed and used to generate A...
+
+### sus
+
+A fast and scalable test runner.
+
+#### [Using Sus Testing Framework](.context/sus/usage.md)
+
+Sus is a modern Ruby testing framework that provides a clean, BDD-style syntax for writing tests. It's designed to be fast, simple, and expressive.
+
+#### [Mocking](.context/sus/mocking.md)
+
+There are two types of mocking in sus: `receive` and `mock`. The `receive` matcher is a subset of full mocking and is used to set expectations on method calls, while `mock` can be used to replace m...
+
+#### [Shared Test Behaviors and Fixtures](.context/sus/shared.md)
+
+Sus provides shared test contexts which can be used to define common behaviours or tests that can be reused across one or more test files.

data/ext/extconf.rb

@@ -58,6 +58,16 @@ have_func("epoll_pwait2")
 
 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)
+	if have_header("pthread.h")
+		append_cflags(["-DHAVE_IO_EVENT_WORKER_POOL"])
+		$srcs << "io/event/worker_pool.c"
+		$srcs << "io/event/worker_pool_test.c"
+	end
+end
+
 if ENV.key?("RUBY_SANITIZE")
 	$stderr.puts "Enabling sanitizers..."
 

data/ext/io/event/event.c

@@ -14,7 +14,11 @@ void Init_IO_Event(void)
 	VALUE IO_Event = rb_define_module_under(rb_cIO, "Event");
 	
 	Init_IO_Event_Fiber(IO_Event);
-	
+
+	#ifdef HAVE_IO_EVENT_WORKER_POOL
+	Init_IO_Event_WorkerPool(IO_Event);
+	#endif
+
 	VALUE IO_Event_Selector = rb_define_module_under(IO_Event, "Selector");
 	Init_IO_Event_Selector(IO_Event_Selector);
 	

data/ext/io/event/event.h

@@ -18,3 +18,7 @@ void Init_IO_Event(void);
 #ifdef HAVE_SYS_EVENT_H
 #include "selector/kqueue.h"
 #endif
+
+#ifdef HAVE_IO_EVENT_WORKER_POOL
+#include "worker_pool.h"
+#endif

data/ext/io/event/fiber.c

@@ -35,7 +35,7 @@ VALUE IO_Event_Fiber_raise(VALUE fiber, int argc, VALUE *argv) {
 #ifndef HAVE_RB_FIBER_CURRENT
 static ID id_current;
 
-static VALUE IO_Event_Fiber_current(void) {
+VALUE IO_Event_Fiber_current(void) {
 	return rb_funcall(rb_cFiber, id_current, 0);
 }
 #endif

data/ext/io/event/selector/epoll.c

@@ -38,6 +38,10 @@ struct IO_Event_Selector_EPoll
 {
 	struct IO_Event_Selector backend;
 	int descriptor;
+	
+	// Flag indicating whether the selector is currently blocked in a system call.
+	// Set to 1 when blocked in epoll_wait() without GVL, 0 otherwise.
+	// Used by wakeup() to determine if an interrupt signal is needed.
 	int blocked;
 	
 	struct timespec idle_duration;

data/ext/io/event/selector/kqueue.c

@@ -47,6 +47,10 @@ struct IO_Event_Selector_KQueue
 {
 	struct IO_Event_Selector backend;
 	int descriptor;
+	
+	// Flag indicating whether the selector is currently blocked in a system call.
+	// Set to 1 when blocked in kevent() without GVL, 0 otherwise.
+	// Used by wakeup() to determine if an interrupt signal is needed.
 	int blocked;
 	
 	struct timespec idle_duration;

data/ext/io/event/selector/selector.c

@@ -29,10 +29,7 @@ VALUE IO_Event_Selector_process_status_wait(rb_pid_t pid, int flags)
 int IO_Event_Selector_nonblock_set(int file_descriptor)
 {
 #ifdef _WIN32
-	u_long nonblock = 1;
-	ioctlsocket(file_descriptor, FIONBIO, &nonblock);
-	// Windows does not provide any way to know this, so we always restore it back to unset:
-	return 0;
+	rb_w32_set_nonblock(file_descriptor);
 #else
 	// Get the current mode:
 	int flags = fcntl(file_descriptor, F_GETFL, 0);
@@ -50,8 +47,6 @@ void IO_Event_Selector_nonblock_restore(int file_descriptor, int flags)
 {
 #ifdef _WIN32
 	// Yolo...
-	u_long nonblock = flags;
-	ioctlsocket(file_descriptor, FIONBIO, &nonblock);
 #else
 	// The flags didn't have O_NONBLOCK set, so it would have been set, so we need to restore it:
 	if (!(flags & O_NONBLOCK)) {

data/ext/io/event/selector/uring.c

@@ -30,6 +30,10 @@ struct IO_Event_Selector_URing
 	struct IO_Event_Selector backend;
 	struct io_uring ring;
 	size_t pending;
+	
+	// Flag indicating whether the selector is currently blocked in a system call.
+	// Set to 1 when blocked in io_uring_wait_cqe_timeout() without GVL, 0 otherwise.
+	// Used by wakeup() to determine if an interrupt signal is needed.
 	int blocked;
 	
 	struct timespec idle_duration;
@@ -707,6 +711,20 @@ VALUE IO_Event_Selector_URing_io_read(VALUE self, VALUE fiber, VALUE io, VALUE b
 	off_t from = io_seekable(descriptor);
 	
 	size_t maximum_size = size - offset;
+	
+	// Are we performing a non-blocking read?
+	if (!length) {
+		// If the (maximum) length is zero, that indicates we just want to read whatever is available without blocking.
+		// If we schedule this read into the URing, it will block until data is available, rather than returning immediately.
+		int state = IO_Event_Selector_nonblock_set(descriptor);
+		
+		int result = read(descriptor, (char*)base+offset, maximum_size);
+		int error = errno;
+		
+		IO_Event_Selector_nonblock_restore(descriptor, state);
+		return rb_fiber_scheduler_io_result(result, error);
+	}
+	
 	while (maximum_size) {
 		int result = io_read(selector, fiber, descriptor, (char*)base+offset, maximum_size, from);
 		
@@ -1093,7 +1111,7 @@ unsigned select_process_completions(struct IO_Event_Selector_URing *selector) {
 		}
 	}
 	
-	if (DEBUG && completed > 0) fprintf(stderr, "select_process_completions(completed=%d)\n", completed);
+	if (DEBUG && completed > 0) fprintf(stderr, "select_process_completions: completed=%d\n", completed);
 	
 	return completed;
 }

data/ext/io/event/worker_pool.c

@@ -0,0 +1,477 @@
+// Released under the MIT License.
+// Copyright, 2025, by Samuel Williams.
+
+#include "worker_pool.h"
+#include "worker_pool_test.h"
+#include "fiber.h"
+
+#include <ruby/thread.h>
+#include <ruby/fiber/scheduler.h>
+
+#include <pthread.h>
+#include <stdbool.h>
+#include <stdlib.h>
+#include <errno.h>
+#include <string.h>
+
+enum {
+	DEBUG = 0,
+};
+
+static VALUE IO_Event_WorkerPool;
+static ID id_maximum_worker_count;
+
+// Thread pool structure
+struct IO_Event_WorkerPool_Worker {
+	VALUE thread;
+	
+	// Flag to indicate this specific worker should exit:
+	bool interrupted;
+
+	// Currently executing operation:
+	rb_fiber_scheduler_blocking_operation_t *current_blocking_operation;
+
+	struct IO_Event_WorkerPool *pool;
+	struct IO_Event_WorkerPool_Worker *next;
+};
+
+// Work item structure
+struct IO_Event_WorkerPool_Work {
+	rb_fiber_scheduler_blocking_operation_t *blocking_operation;
+	
+	bool completed;
+	
+	VALUE scheduler;
+	VALUE blocker;
+	VALUE fiber;
+	
+	struct IO_Event_WorkerPool_Work *next;
+};
+
+// Worker pool structure
+struct IO_Event_WorkerPool {
+	pthread_mutex_t mutex;
+	pthread_cond_t work_available;
+	
+	struct IO_Event_WorkerPool_Work *work_queue;
+	struct IO_Event_WorkerPool_Work *work_queue_tail;
+	
+	struct IO_Event_WorkerPool_Worker *workers;
+	size_t current_worker_count;
+	size_t maximum_worker_count;
+	
+	size_t call_count;
+	size_t completed_count;
+	size_t cancelled_count;
+	
+	bool shutdown;
+};
+
+// Free functions for Ruby GC
+static void worker_pool_free(void *ptr) {
+	struct IO_Event_WorkerPool *pool = (struct IO_Event_WorkerPool *)ptr;
+	
+	if (pool) {
+		// Signal shutdown to all workers
+		if (!pool->shutdown) {
+			pthread_mutex_lock(&pool->mutex);
+			pool->shutdown = true;
+			pthread_cond_broadcast(&pool->work_available);
+			pthread_mutex_unlock(&pool->mutex);
+		}
+		
+		// Note: We don't free worker structures or wait for threads during GC
+		// as this can cause deadlocks. The Ruby GC will handle the thread objects.
+		// Workers will see the shutdown flag and exit cleanly.
+	}
+}
+
+// Size functions for Ruby GC
+static size_t worker_pool_size(const void *ptr) {
+	return sizeof(struct IO_Event_WorkerPool);
+}
+
+// Ruby TypedData structures
+static const rb_data_type_t IO_Event_WorkerPool_type = {
+	"IO::Event::WorkerPool",
+	{0, worker_pool_free, worker_pool_size,},
+	0, 0, RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+// Helper function to enqueue work (must be called with mutex held)
+static void enqueue_work(struct IO_Event_WorkerPool *pool, struct IO_Event_WorkerPool_Work *work) {
+	if (pool->work_queue_tail) {
+		pool->work_queue_tail->next = work;
+	} else {
+		pool->work_queue = work;
+	}
+	pool->work_queue_tail = work;
+}
+
+// Helper function to dequeue work (must be called with mutex held)
+static struct IO_Event_WorkerPool_Work *dequeue_work(struct IO_Event_WorkerPool *pool) {
+	struct IO_Event_WorkerPool_Work *work = pool->work_queue;
+	if (work) {
+		pool->work_queue = work->next;
+		if (!pool->work_queue) {
+			pool->work_queue_tail = NULL;
+		}
+		work->next = NULL; // Clear the next pointer for safety
+	}
+	return work;
+}
+
+// Unblock function to interrupt a specific worker.
+static void worker_unblock_func(void *_worker) {
+	struct IO_Event_WorkerPool_Worker *worker = (struct IO_Event_WorkerPool_Worker *)_worker;
+	struct IO_Event_WorkerPool *pool = worker->pool;
+	
+	// Mark this specific worker as interrupted
+	pthread_mutex_lock(&pool->mutex);
+	worker->interrupted = true;
+	pthread_cond_broadcast(&pool->work_available);
+	pthread_mutex_unlock(&pool->mutex);
+	
+	// If there's a currently executing blocking operation, cancel it
+	if (worker->current_blocking_operation) {
+		rb_fiber_scheduler_blocking_operation_cancel(worker->current_blocking_operation);
+	}
+}
+
+// Function to wait for work and execute it without GVL.
+static void *worker_wait_and_execute(void *_worker) {
+	struct IO_Event_WorkerPool_Worker *worker = (struct IO_Event_WorkerPool_Worker *)_worker;
+	struct IO_Event_WorkerPool *pool = worker->pool;
+	
+	while (true) {
+		struct IO_Event_WorkerPool_Work *work = NULL;
+		
+		pthread_mutex_lock(&pool->mutex);
+		
+		// Wait for work, shutdown, or interruption
+		while (!pool->work_queue && !pool->shutdown && !worker->interrupted) {
+			pthread_cond_wait(&pool->work_available, &pool->mutex);
+		}
+		
+		if (pool->shutdown || worker->interrupted) {
+			pthread_mutex_unlock(&pool->mutex);
+			break;
+		}
+		
+		work = dequeue_work(pool);
+		
+		pthread_mutex_unlock(&pool->mutex);
+		
+		// Execute work WITHOUT GVL (this is the whole point!)
+		if (work) {
+			worker->current_blocking_operation = work->blocking_operation;
+			rb_fiber_scheduler_blocking_operation_execute(work->blocking_operation);
+			worker->current_blocking_operation = NULL;
+		}
+
+		return work;
+	}
+	
+	return NULL; // Shutdown signal
+}
+
+static VALUE worker_thread_func(void *_worker) {
+	struct IO_Event_WorkerPool_Worker *worker = (struct IO_Event_WorkerPool_Worker *)_worker;
+	
+	while (true) {
+		// Wait for work and execute it without holding GVL
+		struct IO_Event_WorkerPool_Work *work = (struct IO_Event_WorkerPool_Work *)rb_thread_call_without_gvl(worker_wait_and_execute, worker, worker_unblock_func, worker);
+		
+		if (!work) {
+			// Shutdown signal received
+			break;
+		}
+
+		// Protected by GVL:
+		work->completed = true;
+		worker->pool->completed_count++;
+		
+		// Work was executed without GVL, now unblock the waiting fiber (we have GVL here)
+		rb_fiber_scheduler_unblock(work->scheduler, work->blocker, work->fiber);
+	}
+	
+	return Qnil;
+}
+
+// Create a new worker thread
+static int create_worker_thread(struct IO_Event_WorkerPool *pool) {
+	if (pool->current_worker_count >= pool->maximum_worker_count) {
+		return -1;
+	}
+	
+		struct IO_Event_WorkerPool_Worker *worker = malloc(sizeof(struct IO_Event_WorkerPool_Worker));
+	if (!worker) {
+		return -1;
+	}
+	
+	worker->pool = pool;
+	worker->interrupted = false;
+	worker->current_blocking_operation = NULL;
+	worker->next = pool->workers;
+	
+	worker->thread = rb_thread_create(worker_thread_func, worker);
+	if (NIL_P(worker->thread)) {
+		free(worker);
+		return -1;
+	}
+	
+	pool->workers = worker;
+	pool->current_worker_count++;
+	
+	return 0;
+}
+
+// Ruby constructor for WorkerPool
+static VALUE worker_pool_initialize(int argc, VALUE *argv, VALUE self) {
+	size_t maximum_worker_count = 1; // Default
+	
+	// Extract keyword arguments
+	VALUE kwargs = Qnil;
+	VALUE rb_maximum_worker_count = Qnil;
+	
+	rb_scan_args(argc, argv, "0:", &kwargs);
+	
+	if (!NIL_P(kwargs)) {
+		VALUE kwvals[1];
+		ID kwkeys[1] = {id_maximum_worker_count};
+		rb_get_kwargs(kwargs, kwkeys, 0, 1, kwvals);
+		rb_maximum_worker_count = kwvals[0];
+	}
+	
+	if (!NIL_P(rb_maximum_worker_count)) {
+		maximum_worker_count = NUM2SIZET(rb_maximum_worker_count);
+		if (maximum_worker_count == 0) {
+			rb_raise(rb_eArgError, "maximum_worker_count must be greater than 0!");
+		}
+	}
+	
+	// Get the pool that was allocated by worker_pool_allocate
+	struct IO_Event_WorkerPool *pool;
+	TypedData_Get_Struct(self, struct IO_Event_WorkerPool, &IO_Event_WorkerPool_type, pool);
+	
+	if (!pool) {
+		rb_raise(rb_eRuntimeError, "WorkerPool allocation failed!");
+	}
+	
+	pthread_mutex_init(&pool->mutex, NULL);
+	pthread_cond_init(&pool->work_available, NULL);
+	
+	pool->work_queue = NULL;
+	pool->work_queue_tail = NULL;
+	pool->workers = NULL;
+	pool->current_worker_count = 0;
+	pool->maximum_worker_count = maximum_worker_count;
+	pool->call_count = 0;
+	pool->completed_count = 0;
+	pool->cancelled_count = 0;
+	pool->shutdown = false;
+	
+	// Create initial workers
+	for (size_t i = 0; i < maximum_worker_count; i++) {
+		if (create_worker_thread(pool) != 0) {
+			// Just set the maximum_worker_count for debugging, don't fail completely
+			// worker_pool_free(pool);
+			// rb_raise(rb_eRuntimeError, "Failed to create workers");
+			break;
+		}
+	}
+	
+	return self;
+}
+
+static VALUE worker_pool_work_begin(VALUE _work) {
+	struct IO_Event_WorkerPool_Work *work = (void*)_work;
+
+	if (DEBUG) fprintf(stderr, "worker_pool_work_begin:rb_fiber_scheduler_block work=%p\n", work);
+	rb_fiber_scheduler_block(work->scheduler, work->blocker, Qnil);
+
+	return Qnil;
+}
+
+// Ruby method to submit work and wait for completion
+static VALUE worker_pool_call(VALUE self, VALUE _blocking_operation) {
+	struct IO_Event_WorkerPool *pool;
+	TypedData_Get_Struct(self, struct IO_Event_WorkerPool, &IO_Event_WorkerPool_type, pool);
+	
+	if (pool->shutdown) {
+		rb_raise(rb_eRuntimeError, "Worker pool is shut down!");
+	}
+	
+	// Increment call count (protected by GVL)
+	pool->call_count++;
+	
+	// Get current fiber and scheduler
+	VALUE fiber = rb_fiber_current();
+	VALUE scheduler = rb_fiber_scheduler_current();
+	if (NIL_P(scheduler)) {
+		rb_raise(rb_eRuntimeError, "WorkerPool requires a fiber scheduler!");
+	}
+	
+	// Extract blocking operation handle
+	rb_fiber_scheduler_blocking_operation_t *blocking_operation = rb_fiber_scheduler_blocking_operation_extract(_blocking_operation);
+	
+	if (!blocking_operation) {
+		rb_raise(rb_eArgError, "Invalid blocking operation!");
+	}
+	
+	// Create work item
+	struct IO_Event_WorkerPool_Work work = {
+		.blocking_operation = blocking_operation,
+		.completed = false,
+		.scheduler = scheduler,
+		.blocker = self,
+		.fiber = fiber,
+		.next = NULL
+	};
+		
+	// Enqueue work:
+	pthread_mutex_lock(&pool->mutex);
+	enqueue_work(pool, &work);
+	pthread_cond_signal(&pool->work_available);
+	pthread_mutex_unlock(&pool->mutex);
+	
+	// Block the current fiber until work is completed:
+	int state = 0;
+	while (true) {
+		int current_state = 0;
+		rb_protect(worker_pool_work_begin, (VALUE)&work, &current_state);
+		if (DEBUG) fprintf(stderr, "-- worker_pool_call:work completed=%d, current_state=%d, state=%d\n", work.completed, current_state, state);
+		
+		// Store the first exception state:
+		if (!state) {
+			state = current_state;
+		}
+		
+		// If the work is still in the queue, we must wait for a worker to complete it (even if cancelled):
+		if (work.completed) {
+			// The work was completed, we can exit the loop:
+			break;
+		} else {
+			if (DEBUG) fprintf(stderr, "worker_pool_call:rb_fiber_scheduler_blocking_operation_cancel\n");
+			// Ensure the blocking operation is cancelled:
+			rb_fiber_scheduler_blocking_operation_cancel(blocking_operation);
+			
+			// The work was not completed, we need to wait for it to be completed, so we go around the loop again.
+		}
+	}
+	
+	if (DEBUG) fprintf(stderr, "<- worker_pool_call:work completed=%d, state=%d\n", work.completed, state);
+	
+	if (state) {
+		rb_jump_tag(state);
+	} else {
+		return Qtrue;
+	}
+}
+
+static VALUE worker_pool_allocate(VALUE klass) {
+	struct IO_Event_WorkerPool *pool;
+	VALUE self = TypedData_Make_Struct(klass, struct IO_Event_WorkerPool, &IO_Event_WorkerPool_type, pool);
+	
+	// Initialize to NULL/zero so we can detect uninitialized pools
+	memset(pool, 0, sizeof(struct IO_Event_WorkerPool));
+	
+	return self;
+}
+
+// Ruby method to close the worker pool
+static VALUE worker_pool_close(VALUE self) {
+	struct IO_Event_WorkerPool *pool;
+	TypedData_Get_Struct(self, struct IO_Event_WorkerPool, &IO_Event_WorkerPool_type, pool);
+	
+	if (!pool) {
+		rb_raise(rb_eRuntimeError, "WorkerPool not initialized!");
+	}
+	
+	if (pool->shutdown) {
+		return Qnil; // Already closed
+	}
+	
+	// Signal shutdown to all workers
+	pthread_mutex_lock(&pool->mutex);
+	pool->shutdown = true;
+	pthread_cond_broadcast(&pool->work_available);
+	pthread_mutex_unlock(&pool->mutex);
+	
+	// Wait for all worker threads to finish
+	struct IO_Event_WorkerPool_Worker *worker = pool->workers;
+	while (worker) {
+		if (!NIL_P(worker->thread)) {
+			rb_funcall(worker->thread, rb_intern("join"), 0);
+		}
+		worker = worker->next;
+	}
+	
+	// Clean up worker structures
+	worker = pool->workers;
+	while (worker) {
+		struct IO_Event_WorkerPool_Worker *next = worker->next;
+		free(worker);
+		worker = next;
+	}
+	pool->workers = NULL;
+	pool->current_worker_count = 0;
+	
+	// Clean up mutex and condition variable
+	pthread_mutex_destroy(&pool->mutex);
+	pthread_cond_destroy(&pool->work_available);
+	
+	return Qnil;
+}
+
+// Test helper: get pool statistics for debugging/testing
+static VALUE worker_pool_statistics(VALUE self) {
+	struct IO_Event_WorkerPool *pool;
+	TypedData_Get_Struct(self, struct IO_Event_WorkerPool, &IO_Event_WorkerPool_type, pool);
+	
+	if (!pool) {
+		rb_raise(rb_eRuntimeError, "WorkerPool not initialized!");
+	}
+	
+	VALUE stats = rb_hash_new();
+	rb_hash_aset(stats, ID2SYM(rb_intern("current_worker_count")), SIZET2NUM(pool->current_worker_count));
+	rb_hash_aset(stats, ID2SYM(rb_intern("maximum_worker_count")), SIZET2NUM(pool->maximum_worker_count));
+	rb_hash_aset(stats, ID2SYM(rb_intern("call_count")), SIZET2NUM(pool->call_count));
+	rb_hash_aset(stats, ID2SYM(rb_intern("completed_count")), SIZET2NUM(pool->completed_count));
+	rb_hash_aset(stats, ID2SYM(rb_intern("cancelled_count")), SIZET2NUM(pool->cancelled_count));
+	rb_hash_aset(stats, ID2SYM(rb_intern("shutdown")), pool->shutdown ? Qtrue : Qfalse);
+	
+	// Count work items in queue (only if properly initialized)
+	if (pool->maximum_worker_count > 0) {
+		pthread_mutex_lock(&pool->mutex);
+		size_t current_queue_size = 0;
+		struct IO_Event_WorkerPool_Work *work = pool->work_queue;
+		while (work) {
+			current_queue_size++;
+			work = work->next;
+		}
+		pthread_mutex_unlock(&pool->mutex);
+		rb_hash_aset(stats, ID2SYM(rb_intern("current_queue_size")), SIZET2NUM(current_queue_size));
+	} else {
+		rb_hash_aset(stats, ID2SYM(rb_intern("current_queue_size")), SIZET2NUM(0));
+	}
+	
+	return stats;
+}
+
+void Init_IO_Event_WorkerPool(VALUE IO_Event) {
+	// Initialize symbols
+	id_maximum_worker_count = rb_intern("maximum_worker_count");
+	
+	IO_Event_WorkerPool = rb_define_class_under(IO_Event, "WorkerPool", rb_cObject);
+	rb_define_alloc_func(IO_Event_WorkerPool, worker_pool_allocate);
+
+	rb_define_method(IO_Event_WorkerPool, "initialize", worker_pool_initialize, -1);
+	rb_define_method(IO_Event_WorkerPool, "call", worker_pool_call, 1);
+	rb_define_method(IO_Event_WorkerPool, "close", worker_pool_close, 0);
+	
+	rb_define_method(IO_Event_WorkerPool, "statistics", worker_pool_statistics, 0);
+	
+	// Initialize test functions
+	Init_IO_Event_WorkerPool_Test(IO_Event_WorkerPool);
+}

data/ext/io/event/worker_pool.h

@@ -0,0 +1,8 @@
+// Released under the MIT License.
+// Copyright, 2025, by Samuel Williams.
+
+#pragma once
+
+#include <ruby.h>
+
+void Init_IO_Event_WorkerPool(VALUE IO_Event); 

data/ext/io/event/worker_pool_test.c

@@ -0,0 +1,199 @@
+// worker_pool_test.c - Test functions for WorkerPool cancellation
+// Released under the MIT License.
+// Copyright, 2025, by Samuel Williams.
+
+#include "worker_pool_test.h"
+
+#include <ruby/thread.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include <unistd.h>
+#include <errno.h>
+#include <time.h>
+
+static ID id_duration;
+
+struct BusyOperationData {
+  int read_fd;
+  int write_fd;
+  volatile int cancelled;
+  double duration;  // How long to wait (for testing)
+  clock_t start_time;
+  clock_t end_time;
+  int operation_result;
+  VALUE exception;
+};
+
+// The actual blocking operation that can be cancelled
+static void* busy_blocking_operation(void *data) {
+	struct BusyOperationData *busy_data = (struct BusyOperationData*)data;
+	
+	// Use select() to wait for the pipe to become readable
+	fd_set read_fds;
+	struct timeval timeout;
+	
+	FD_ZERO(&read_fds);
+	FD_SET(busy_data->read_fd, &read_fds);
+	
+	// Set timeout based on duration
+	timeout.tv_sec = (long)busy_data->duration;
+	timeout.tv_usec = ((busy_data->duration - timeout.tv_sec) * 1000000);
+	
+	// This will block until:
+	// 1. The pipe becomes readable (cancellation)
+	// 2. The timeout expires
+	// 3. An error occurs
+	int result = select(busy_data->read_fd + 1, &read_fds, NULL, NULL, &timeout);
+
+	if (result > 0 && FD_ISSET(busy_data->read_fd, &read_fds)) {
+		// Pipe became readable - we were cancelled
+		char buffer;
+		read(busy_data->read_fd, &buffer, 1);  // Consume the byte
+		busy_data->cancelled = 1;
+		return (void*)-1;  // Indicate cancellation
+	} else if (result == 0) {
+		// Timeout - operation completed normally
+		return (void*)0;  // Indicate success
+	} else {
+		// Error occurred
+		return (void*)-2;  // Indicate error
+	}
+}
+
+// Unblock function that writes to the pipe to cancel the operation
+static void busy_unblock_function(void *data) {
+	struct BusyOperationData *busy_data = (struct BusyOperationData*)data;
+	
+	busy_data->cancelled = 1;
+
+	// Write a byte to the pipe to wake up the select()
+	char wake_byte = 1;
+	write(busy_data->write_fd, &wake_byte, 1);
+}
+
+// Function for the main operation execution (for rb_rescue)
+static VALUE busy_operation_execute(VALUE data_value) {
+	struct BusyOperationData *busy_data = (struct BusyOperationData*)data_value;
+	
+	// Record start time
+	busy_data->start_time = clock();
+	
+	// Execute the blocking operation
+	void *block_result = rb_nogvl(
+		busy_blocking_operation,
+		busy_data,
+		busy_unblock_function,
+		busy_data,
+		RB_NOGVL_UBF_ASYNC_SAFE | RB_NOGVL_OFFLOAD_SAFE
+	);
+	
+	// Record end time
+	busy_data->end_time = clock();
+	
+	// Store the operation result
+	busy_data->operation_result = (int)(intptr_t)block_result;
+	
+	return Qnil;
+}
+
+// Function for exception handling (for rb_rescue)
+static VALUE busy_operation_rescue(VALUE data_value, VALUE exception) {
+	struct BusyOperationData *busy_data = (struct BusyOperationData*)data_value;
+	
+	// Record end time even in case of exception
+	busy_data->end_time = clock();
+	
+	// Mark that an exception was caught
+	busy_data->exception = exception;
+	
+	return exception;
+}
+
+// Ruby method: IO::Event::WorkerPool.busy(duration: 1.0)
+// This creates a cancellable blocking operation for testing
+static VALUE worker_pool_test_busy(int argc, VALUE *argv, VALUE self) {
+	double duration = 1.0;  // Default 1 second
+	
+	// Extract keyword arguments
+	VALUE kwargs = Qnil;
+	VALUE rb_duration = Qnil;
+	
+	rb_scan_args(argc, argv, "0:", &kwargs);
+	
+	if (!NIL_P(kwargs)) {
+		VALUE kwvals[1];
+		ID kwkeys[1] = {id_duration};
+		rb_get_kwargs(kwargs, kwkeys, 0, 1, kwvals);
+		rb_duration = kwvals[0];
+	}
+	
+	if (!NIL_P(rb_duration)) {
+		duration = NUM2DBL(rb_duration);
+	}
+	
+	// Create pipe for cancellation
+	int pipe_fds[2];
+	if (pipe(pipe_fds) != 0) {
+		rb_sys_fail("pipe creation failed");
+	}
+	
+	// Stack allocate operation data
+	struct BusyOperationData busy_data = {
+		.read_fd = pipe_fds[0],
+		.write_fd = pipe_fds[1],
+		.cancelled = 0,
+		.duration = duration,
+		.start_time = 0,
+		.end_time = 0,
+		.operation_result = 0,
+		.exception = Qnil
+	};
+	
+	// Execute the blocking operation with exception handling using function pointers
+	rb_rescue(
+		busy_operation_execute,
+		(VALUE)&busy_data,
+		busy_operation_rescue,
+		(VALUE)&busy_data
+	);
+	
+	// Calculate elapsed time from the state stored in busy_data
+	double elapsed = ((double)(busy_data.end_time - busy_data.start_time)) / CLOCKS_PER_SEC;
+	
+	// Create result hash using the state from busy_data
+	VALUE result = rb_hash_new();
+	rb_hash_aset(result, ID2SYM(rb_intern("duration")), DBL2NUM(duration));
+	rb_hash_aset(result, ID2SYM(rb_intern("elapsed")), DBL2NUM(elapsed));
+	
+	// Determine result based on operation outcome
+	if (busy_data.exception != Qnil) {
+		rb_hash_aset(result, ID2SYM(rb_intern("result")), ID2SYM(rb_intern("exception")));
+		rb_hash_aset(result, ID2SYM(rb_intern("cancelled")), Qtrue);
+		rb_hash_aset(result, ID2SYM(rb_intern("exception")), busy_data.exception);
+	} else if (busy_data.operation_result == -1) {
+		rb_hash_aset(result, ID2SYM(rb_intern("result")), ID2SYM(rb_intern("cancelled")));
+		rb_hash_aset(result, ID2SYM(rb_intern("cancelled")), Qtrue);
+	} else if (busy_data.operation_result == 0) {
+		rb_hash_aset(result, ID2SYM(rb_intern("result")), ID2SYM(rb_intern("completed")));
+		rb_hash_aset(result, ID2SYM(rb_intern("cancelled")), Qfalse);
+	} else {
+		rb_hash_aset(result, ID2SYM(rb_intern("result")), ID2SYM(rb_intern("error")));
+		rb_hash_aset(result, ID2SYM(rb_intern("cancelled")), Qfalse);
+	}
+	
+	// Clean up pipe file descriptors
+	close(pipe_fds[0]);
+	close(pipe_fds[1]);
+	
+	return result;
+}
+
+// Initialize the test functions
+void Init_IO_Event_WorkerPool_Test(VALUE IO_Event_WorkerPool) {
+	// Initialize symbols
+	id_duration = rb_intern("duration");
+	
+	// Add test methods to IO::Event::WorkerPool class
+	rb_define_singleton_method(IO_Event_WorkerPool, "busy", worker_pool_test_busy, -1);
+} 

data/ext/io/event/worker_pool_test.h

@@ -0,0 +1,9 @@
+// worker_pool_test.h - Header for WorkerPool test functions
+// Released under the MIT License.
+// Copyright, 2025, by Samuel Williams.
+
+#pragma once
+
+#include <ruby.h>
+
+void Init_IO_Event_WorkerPool_Test(VALUE IO_Event_WorkerPool);

data/lib/io/event/debug/selector.rb

@@ -116,9 +116,9 @@ module IO::Event
 			#
 			# @parameter fiber [Fiber] The fiber to raise the exception on.
 			# @parameter arguments [Array] The arguments to use when raising the exception.
-			def raise(fiber, *arguments)
+			def raise(fiber, *arguments, **options)
 				log("Raising exception on fiber #{fiber.inspect} with #{arguments.inspect}")
-				@selector.raise(fiber, *arguments)
+				@selector.raise(fiber, *arguments, **options)
 			end
 			
 			# Check if the selector is ready.

data/lib/io/event/priority_heap.rb

@@ -82,7 +82,7 @@ class IO
 			# Validate the heap invariant. Every element except the root must not be smaller than its parent element. Note that it MAY be equal.
 			def valid?
 				# Notice we skip index 0 on purpose, because it has no parent
-				(1..(@contents.size - 1)).all? { |e| @contents[e] >= @contents[(e - 1) / 2] }
+				(1..(@contents.size - 1)).all? {|index| @contents[index] >= @contents[(index - 1) / 2]}
 			end
 			
 			private

data/lib/io/event/selector/select.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2024, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
 # Copyright, 2023, by Math Ieu.
 
 require_relative "../interrupt"
@@ -17,6 +17,9 @@ module IO::Event
 				
 				@waiting = Hash.new.compare_by_identity
 				
+				# Flag indicating whether the selector is currently blocked in a system call.
+				# Set to true when blocked in ::IO.select, false otherwise.
+				# Used by wakeup() to determine if an interrupt signal is needed.
 				@blocked = false
 				
 				@ready = Queue.new
@@ -95,11 +98,11 @@ module IO::Event
 			end
 			
 			# Transfer to the given fiber and raise an exception. Put the current fiber into the ready list.
-			def raise(fiber, *arguments)
+			def raise(fiber, *arguments, **options)
 				optional = Optional.new(Fiber.current)
 				@ready.push(optional)
 				
-				fiber.raise(*arguments)
+				fiber.raise(*arguments, **options)
 			ensure
 				optional.nullify
 			end
@@ -196,7 +199,7 @@ module IO::Event
 							result = Fiber.blocking{buffer.read(io, 0, offset)}
 							
 							if result < 0
-								if again?(result)
+								if length > 0 and again?(result)
 									self.io_wait(fiber, io, IO::READABLE)
 								else
 									return result
@@ -226,7 +229,7 @@ module IO::Event
 							result = Fiber.blocking{buffer.write(io, 0, offset)}
 							
 							if result < 0
-								if again?(result)
+								if length > 0 and again?(result)
 									self.io_wait(fiber, io, IO::READABLE)
 								else
 									return result
@@ -302,96 +305,14 @@ module IO::Event
 					
 					return total
 				end
-			elsif Support.fiber_scheduler_v1?
-				# Ruby <= 3.1, limited IO::Buffer support.
-				def io_read(fiber, _io, buffer, length, offset = 0)
-					# We need to avoid any internal buffering, so we use a duplicated IO object:
-					io = IO.for_fd(_io.fileno, autoclose: false)
-					
-					total = 0
-					
-					maximum_size = buffer.size - offset
-					while maximum_size > 0
-						case result = blocking{io.read_nonblock(maximum_size, exception: false)}
-						when :wait_readable
-							if length > 0
-								self.io_wait(fiber, io, IO::READABLE)
-							else
-								return EWOULDBLOCK
-							end
-						when :wait_writable
-							if length > 0
-								self.io_wait(fiber, io, IO::WRITABLE)
-							else
-								return EWOULDBLOCK
-							end
-						when nil
-							break
-						else
-							buffer.set_string(result, offset)
-							
-							size = result.bytesize
-							total += size
-							offset += size
-							break if size >= length
-							length -= size
-						end
-						
-						maximum_size = buffer.size - offset
-					end
-					
-					return total
-				rescue IOError => error
-					return -Errno::EBADF::Errno
-				rescue SystemCallError => error
-					return -error.errno
-				end
-				
-				def io_write(fiber, _io, buffer, length, offset = 0)
-					# We need to avoid any internal buffering, so we use a duplicated IO object:
-					io = IO.for_fd(_io.fileno, autoclose: false)
-					
-					total = 0
-					
-					maximum_size = buffer.size - offset
-					while maximum_size > 0
-						chunk = buffer.get_string(offset, maximum_size)
-						case result = blocking{io.write_nonblock(chunk, exception: false)}
-						when :wait_readable
-							if length > 0
-								self.io_wait(fiber, io, IO::READABLE)
-							else
-								return EWOULDBLOCK
-							end
-						when :wait_writable
-							if length > 0
-								self.io_wait(fiber, io, IO::WRITABLE)
-							else
-								return EWOULDBLOCK
-							end
-						else
-							total += result
-							offset += result
-							break if result >= length
-							length -= result
-						end
-						
-						maximum_size = buffer.size - offset
-					end
-					
-					return total
-				rescue IOError => error
-					return -Errno::EBADF::Errno
-				rescue SystemCallError => error
-					return -error.errno
-				end
-				
-				def blocking(&block)
-					fiber = Fiber.new(blocking: true, &block)
-					return fiber.resume(fiber)
-				end
 			end
 			
+			# Wait for a process to change state.
+			#
+			# @parameter fiber [Fiber] The fiber to resume after waiting.
+			# @parameter pid [Integer] The process ID to wait for.
+			# @parameter flags [Integer] Flags to pass to Process::Status.wait.
+			# @returns [Process::Status] The status of the waited process.
 			def process_wait(fiber, pid, flags)
 				Thread.new do
 					Process::Status.wait(pid, flags)
@@ -411,6 +332,10 @@ module IO::Event
 				end
 			end
 			
+			# Wait for IO events or a timeout.
+			#
+			# @parameter duration [Numeric | Nil] The maximum time to wait, or nil for no timeout.
+			# @returns [Integer] The number of ready IO objects.
 			def select(duration = nil)
 				if pop_ready
 					# If we have popped items from the ready list, they may influence the duration calculation, so we don't delay the event loop:

data/lib/io/event/support.rb

@@ -14,35 +14,28 @@ class IO
 				IO.const_defined?(:Buffer)
 			end
 			
-			# The basic fiber scheduler was introduced along side the IO::Buffer class.
-			#
-			# @returns [Boolean] Whether the IO::Buffer class is available.
-			#
-			# To be removed on 31 Mar 2025.
-			def self.fiber_scheduler_v1?
-				IO.const_defined?(:Buffer)
-			end
-			
 			# More advanced read/write methods and blocking controls were introduced in Ruby 3.2.
 			#
 			# To be removed on 31 Mar 2026.
 			def self.fiber_scheduler_v2?
-				# Some interface changes were back-ported incorrectly:
-				# https://github.com/ruby/ruby/pull/10778
-				# Specifically "Improvements to IO::Buffer read/write/pread/pwrite."
-				# Missing correct size calculation.
-				return false if RUBY_VERSION >= "3.2.5"
-				
-				IO.const_defined?(:Buffer) and Fiber.respond_to?(:blocking) and IO::Buffer.instance_method(:read).arity == -1
+				if RUBY_VERSION >= "3.2"
+					return true if RUBY_VERSION >= "3.2.6"
+					
+					# Some interface changes were back-ported incorrectly and released in 3.2.5 <https://github.com/ruby/ruby/pull/10778> - Specifically "Improvements to IO::Buffer read/write/pread/pwrite." is missing correct size calculation.
+					return false if RUBY_VERSION >= "3.2.5"
+					
+					# Feature detection:
+					IO.const_defined?(:Buffer) and Fiber.respond_to?(:blocking) and IO::Buffer.instance_method(:read).arity == -1
+				end
 			end
 			
 			# Updated inferfaces for read/write and IO::Buffer were introduced in Ruby 3.3, including pread/pwrite.
 			#
 			# To become the default 31 Mar 2026.
 			def self.fiber_scheduler_v3?
+				return true if RUBY_VERSION >= "3.3"
+				
 				if fiber_scheduler_v2?
-					return true if RUBY_VERSION >= "3.3"
-					
 					# Feature detection if required:
 					begin
 						IO::Buffer.new.slice(0, 0).write(STDOUT)

data/lib/io/event/version.rb

@@ -7,6 +7,6 @@
 class IO
 	# @namespace
 	module Event
-		VERSION = "1.10.2"
+		VERSION = "1.12.1"
 	end
 end

data/license.md

@@ -9,7 +9,7 @@ Copyright, 2022, by Bruno Sutic.
 Copyright, 2023, by Math Ieu.  
 Copyright, 2024, by Pavel Rosický.  
 Copyright, 2024, by Anthony Ross.  
-Copyright, 2024, by Shizuo Fujita.  
+Copyright, 2024-2025, by Shizuo Fujita.  
 Copyright, 2024, by Jean Boussier.  
 Copyright, 2025, by Stanislav (Stas) Katkov.  
 

data/readme.md

@@ -18,6 +18,18 @@ Please see the [project documentation](https://socketry.github.io/io-event/) for
 
 Please see the [project releases](https://socketry.github.io/io-event/releases/index) for all releases.
 
+### v1.11.2
+
+  - Fix Windows build.
+
+### v1.11.1
+
+  - Fix `read_nonblock` when using the `URing` selector, which was not handling zero-length reads correctly. This allows reading available data without blocking.
+
+### v1.11.0
+
+  - [Introduce `IO::Event::WorkerPool` for off-loading blocking operations.](https://socketry.github.io/io-event/releases/index#introduce-io::event::workerpool-for-off-loading-blocking-operations.)
+
 ### v1.10.2
 
   - Improved consistency of handling closed IO when invoking `#select`.

data/releases.md

@@ -1,5 +1,39 @@
 # Releases
 
+## v1.11.2
+
+  - Fix Windows build.
+
+## v1.11.1
+
+  - Fix `read_nonblock` when using the `URing` selector, which was not handling zero-length reads correctly. This allows reading available data without blocking.
+
+## v1.11.0
+
+### Introduce `IO::Event::WorkerPool` for off-loading blocking operations.
+
+The {ruby IO::Event::WorkerPool} provides a mechanism for executing blocking operations on separate OS threads while properly integrating with Ruby's fiber scheduler and GVL (Global VM Lock) management. This enables true parallelism for CPU-intensive or blocking operations that would otherwise block the event loop.
+
+``` ruby
+# Fiber scheduler integration via blocking_operation_wait hook
+class MyScheduler
+	def initialize
+		@worker_pool = IO::Event::WorkerPool.new
+	end
+
+  def blocking_operation_wait(operation)
+    @worker_pool.call(operation)
+  end
+end
+
+# Usage with automatic offloading
+Fiber.set_scheduler(MyScheduler.new)
+# Automatically offload `rb_nogvl(..., RB_NOGVL_OFFLOAD_SAFE)` to a background thread:
+result = some_blocking_operation()
+```
+
+The implementation uses one or more background threads and a list of pending blocking operations. Those operations either execute through to completion or may be cancelled, which executes the "unblock function" provided to `rb_nogvl`.
+
 ## v1.10.2
 
   - Improved consistency of handling closed IO when invoking `#select`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: io-event
 version: !ruby/object:Gem::Version
-  version: 1.10.2
+  version: 1.12.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -10,11 +10,11 @@ authors:
 - Jean Boussier
 - Benoit Daloze
 - Bruno Sutic
+- Shizuo Fujita
 - Alex Matchneer
 - Anthony Ross
 - Delton Ding
 - Pavel Rosický
-- Shizuo Fujita
 - Stanislav (Stas) Katkov
 bindir: bin
 cert_chain:
@@ -54,6 +54,7 @@ extensions:
 - ext/extconf.rb
 extra_rdoc_files: []
 files:
+- agent.md
 - design.md
 - ext/extconf.rb
 - ext/io/event/array.h
@@ -75,6 +76,10 @@ files:
 - ext/io/event/selector/uring.h
 - ext/io/event/time.c
 - ext/io/event/time.h
+- ext/io/event/worker_pool.c
+- ext/io/event/worker_pool.h
+- ext/io/event/worker_pool_test.c
+- ext/io/event/worker_pool_test.h
 - lib/io/event.rb
 - lib/io/event/debug/selector.rb
 - lib/io/event/interrupt.rb
@@ -102,14 +107,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: 3.2.6
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.0.dev
+rubygems_version: 3.6.7
 specification_version: 4
 summary: An event loop.
 test_files: []