io-event 1.9.0 → 1.12.0

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
@@ -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:
@@ -421,19 +346,25 @@ module IO::Event
 				writable = Array.new
 				priority = Array.new
 				
-				@waiting.each do |io, waiter|
-					waiter.each do |fiber, events|
-						if (events & IO::READABLE) > 0
-							readable << io
-						end
-						
-						if (events & IO::WRITABLE) > 0
-							writable << io
-						end
-						
-						if (events & IO::PRIORITY) > 0
-							priority << io
+				@waiting.delete_if do |io, waiter|
+					if io.closed?
+						true
+					else
+						waiter.each do |fiber, events|
+							if (events & IO::READABLE) > 0
+								readable << io
+							end
+							
+							if (events & IO::WRITABLE) > 0
+								writable << io
+							end
+							
+							if (events & IO::PRIORITY) > 0
+								priority << io
+							end
 						end
+
+						false
 					end
 				end
 				

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/timers.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024, by Samuel Williams.
+# Copyright, 2024-2025, by Samuel Williams.
 
 require_relative "priority_heap"
 
@@ -91,7 +91,6 @@ class IO
 				schedule(self.now + offset.to_f, block)
 			end
 			
-			
 			# Compute the time interval until the next timer fires.
 			#
 			# @parameter now [Float] The current time.

data/lib/io/event/version.rb

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

data/license.md

@@ -9,8 +9,9 @@ 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.  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/readme.md

@@ -1,4 +1,4 @@
-# ![Event](logo.svg)
+# ![IO::Event](logo.svg)
 
 Provides low level cross-platform primitives for constructing event loops, with support for `select`, `kqueue`, `epoll` and `io_uring`.
 
@@ -18,13 +18,34 @@ 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`.
+
+### v1.10.0
+
+  - `IO::Event::Profiler` is moved to dedicated gem: [fiber-profiler](https://github.com/socketry/fiber-profiler).
+  - Perform runtime checks for native selectors to ensure they are supported in the current environment. While compile-time checks determine availability, restrictions like seccomp and SELinux may still prevent them from working.
+
 ### v1.9.0
 
-  - [Improved `IO::Event::Profiler` for detecting stalls.](https://socketry.github.io/io-event/releases/index#improved-io::event::profiler-for-detecting-stalls.)
+  - Improved `IO::Event::Profiler` for detecting stalls.
 
 ### v1.8.0
 
-  - [Detecting fibers that are stalling the event loop.](https://socketry.github.io/io-event/releases/index#detecting-fibers-that-are-stalling-the-event-loop.)
+  - Detecting fibers that are stalling the event loop.
 
 ### v1.7.5
 

data/releases.md

@@ -1,56 +1,55 @@
 # Releases
 
-## v1.9.0
+## v1.11.2
 
-### Improved `IO::Event::Profiler` for detecting stalls.
+  - Fix Windows build.
 
-A new `IO::Event::Profiler` class has been added to help detect stalls in the event loop. The previous approach was insufficient to detect all possible stalls. This new approach uses the `RUBY_EVENT_FIBER_SWITCH` event to track context switching by the scheduler, and can detect stalls no matter how they occur.
+## v1.11.1
 
-``` ruby
-profiler = IO::Event::Profiler.new
+  - 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
 
-profiler.start
-		
-Fiber.new do
-	sleep 1.0
-end.transfer
+### Introduce `IO::Event::WorkerPool` for off-loading blocking operations.
 
-profiler.stop
+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()
 ```
 
-A default profiler is exposed using `IO::Event::Profiler.default` which is controlled by the following environment variables:
+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`.
 
-  - `IO_EVENT_PROFILER=true` - Enable the profiler, otherwise `IO::Event::Profiler.default` will return `nil`.
-  - `IO_EVENT_PROFILER_LOG_THRESHOLD` - Specify the threshold in seconds for logging a stall. Defaults to `0.01`.
-  - `IO_EVENT_PROFILER_TRACK_CALLS` - Track the method call for each event, in order to log specifically which method is causing the stall. Defaults to `true`.
+## v1.10.2
+
+  - Improved consistency of handling closed IO when invoking `#select`.
+
+## v1.10.0
+
+  - `IO::Event::Profiler` is moved to dedicated gem: [fiber-profiler](https://github.com/socketry/fiber-profiler).
+  - Perform runtime checks for native selectors to ensure they are supported in the current environment. While compile-time checks determine availability, restrictions like seccomp and SELinux may still prevent them from working.
+
+## v1.9.0
 
-The previous environment variables `IO_EVENT_SELECTOR_STALL_LOG_THRESHOLD` and `IO_EVENT_SELECTOR_STALL_LOG` no longer have any effect.
+  - Improved `IO::Event::Profiler` for detecting stalls.
 
 ## v1.8.0
 
-### Detecting fibers that are stalling the event loop.
-
-A new (experimental) feature for detecting fiber stalls has been added. This feature is disabled by default and can be enabled by setting the `IO_EVENT_SELECTOR_STALL_LOG_THRESHOLD` to `true` or a floating point number representing the threshold in seconds.
-
-When enabled, the event loop will measure and profile user code when resuming a fiber. If the fiber takes too long to return back to the event loop, the event loop will log a warning message with a profile of the fiber's execution.
-
-    > cat test.rb 
-    #!/usr/bin/env ruby
-    
-    require_relative "lib/async"
-    
-    Async do
-    	Fiber.blocking do
-    		sleep 1
-    	end
-    end
-    
-    > IO_EVENT_SELECTOR_STALL_LOG_THRESHOLD=true bundle exec ./test.rb
-    Fiber stalled for 1.003 seconds
-    	/home/samuel/Developer/socketry/async/test.rb:6 in '#<Class:Fiber>#blocking' (1s)
-    		/home/samuel/Developer/socketry/async/test.rb:7 in 'Kernel#sleep' (1s)
-
-There is a performance overhead to this feature, so it is recommended to only enable it when debugging performance issues.
+  - Detecting fibers that are stalling the event loop.
 
 ## v1.7.5
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: io-event
 version: !ruby/object:Gem::Version
-  version: 1.9.0
+  version: 1.12.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -10,11 +10,12 @@ 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:
 - |
@@ -46,13 +47,14 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2025-02-10 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 executables: []
 extensions:
 - ext/extconf.rb
 extra_rdoc_files: []
 files:
+- agent.md
 - design.md
 - ext/extconf.rb
 - ext/io/event/array.h
@@ -63,8 +65,6 @@ files:
 - ext/io/event/interrupt.c
 - ext/io/event/interrupt.h
 - ext/io/event/list.h
-- ext/io/event/profiler.c
-- ext/io/event/profiler.h
 - ext/io/event/selector/epoll.c
 - ext/io/event/selector/epoll.h
 - ext/io/event/selector/kqueue.c
@@ -76,12 +76,15 @@ 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
 - lib/io/event/native.rb
 - lib/io/event/priority_heap.rb
-- lib/io/event/profiler.rb
 - lib/io/event/selector.rb
 - lib/io/event/selector/nonblock.rb
 - lib/io/event/selector/select.rb
@@ -104,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.6.2
+rubygems_version: 3.6.7
 specification_version: 4
 summary: An event loop.
 test_files: []