io-event 1.10.2 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 643309e8464f787b038f0d7a83470e1b4750989455329081a59924c8ba4c1f43
-  data.tar.gz: 449bd6b5a87a17f826eaaa6f8d62102641a1722d8a49d4cf3f3036bbff6252c1
+  metadata.gz: e5601614e57f23e24edb8f34dfdaf5b87ca33e902312c27fa51dc9af375ab76c
+  data.tar.gz: c791965fb7be4525b4894de46f1a14787a19ea68920d4009e89713e3aebc1001
 SHA512:
-  metadata.gz: 34cd0ddcba1cc3a67cbf586cacb12a87b07c7f12a2b32d05f6d6a2d288ec50c6f7a53df5be6b8458f479e887831ec74ff395253021a0a5b6af0b7166bbb41f58
-  data.tar.gz: 1e13343fea3e66597dc67e4f671df961fa967d8bb09d3c9b5b706e866b250431ec9bac01c49df994c3e7859497ed14a4b8cfe31aa03856dc66bc43aff18f7a5e
+  metadata.gz: 6f662e6208b30d95aeb68d68ea9e3459bd51b6dc920d7bfcaa4794ffa455316443d2da3c6e954805bd8daadd0339341aab09c225054d9e81903866d63b39d9f0
+  data.tar.gz: 0016b73d68044784ec52d270725d7f4a8bde5064bfd54c5fd3d685f36771d235ae16719fa1ca0a3f9d4dd246894e84d74e8e5025605ebcfc86fb9b5d6be39696

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/worker_pool.c

@@ -0,0 +1,464 @@
+// 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;
+	while (true) {
+		rb_protect(worker_pool_work_begin, (VALUE)&work, &state);
+
+		if (work.completed) {
+			break;
+		} else {
+			if (DEBUG) fprintf(stderr, "worker_pool_call:rb_fiber_scheduler_blocking_operation_cancel\n");
+			rb_fiber_scheduler_blocking_operation_cancel(blocking_operation);
+			// The work was not completed, we need to wait for it to be completed.
+		}
+	}
+	
+	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,200 @@
+// 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 <sys/select.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/version.rb

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

data/readme.md

@@ -18,6 +18,10 @@ 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.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,31 @@
 # Releases
 
+## 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.11.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -75,6 +75,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
@@ -109,7 +113,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !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: []