io-event 1.16.1 → 1.16.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd552a5bb53e9a2e9169c55a7f789e84f761a2707c83edd5955512818ad55e25
-  data.tar.gz: 97a35fef870d94f7c596d612fdd6664c2e65cff9b14a8cf6b9035b12584f0833
+  metadata.gz: 7823ee584acc17c23f0f464a60271449a4298733efa62623653420b9181a5201
+  data.tar.gz: c71e15d6f35113a68bf31442621d2a4b9f8e8ca8d9b0d27dae234c30005f4ae0
 SHA512:
-  metadata.gz: e187b07cc91e2ecf7fb641a61f481fbb9ba42a1a52c14532fa659ede0a6723dde5ac63e35d7a584d549ca52a94462131f5755b9da7bce1b06abd99f1ea6b3f24
-  data.tar.gz: '090f2023d28eac6b05386727f0497bbd02db76b6a3bf0b43f9e068e5e5d36edb543a16c94806fea736c319298b491b1d13e069c7f89bf41a89dd86171b183c96'
+  metadata.gz: 60764fbe8a01ce3a77d8ad796473934f41a92edf30772265d4f0abbaf89bb9b1b79e1776cd9071111e0ff2590fc9402892cbaea1e22c779f9f3fdfe5ca18b9e9
+  data.tar.gz: 452f83f2b2a7550b6aa01f1d5094b62171e2a6179d8760651c3275397be65fb653adf12c8db1c3470d5cdcdbacf88e48dd208f01b53e2f0ed50eac91d104c06e

data/ext/extconf.rb

@@ -55,7 +55,7 @@ have_func("rb_io_descriptor")
 have_func("&rb_process_status_wait")
 have_func("rb_fiber_current")
 have_func("&rb_fiber_raise")
-have_func("epoll_pwait2") if enable_config("epoll_pwait2", true)
+have_func("epoll_pwait2(0, 0, 0, 0, 0)", "sys/epoll.h") if enable_config("epoll_pwait2", true)
 
 have_header("ruby/io/buffer.h")
 

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

@@ -107,6 +107,8 @@ module IO::Event
 				
 				@selector.close
 				@selector = nil
+				
+				@log&.flush
 			end
 			
 			# Transfer from the calling fiber to the selector.

data/lib/io/event/interrupt.rb

@@ -20,6 +20,8 @@ module IO::Event
 						@input.read_nonblock(1)
 					end
 				end
+			rescue IOError
+				# This is expected on shutdown.
 			end
 			
 			@fiber.transfer
@@ -36,7 +38,6 @@ module IO::Event
 		def close
 			@input.close
 			@output.close
-			# @fiber.raise(::Interrupt)
 		end
 	end
 	

data/lib/io/event/priority_heap.rb

@@ -10,6 +10,8 @@ class IO
 		# of its contents to determine priority.
 		# See <https://en.wikipedia.org/wiki/Binary_heap> for explanations of the main methods.
 		class PriorityHeap
+			HEAPIFY_INSERT_RATIO = 2
+			
 			# Initializes the heap.
 			def initialize
 				# The heap is represented with an array containing a binary tree. See
@@ -79,18 +81,34 @@ class IO
 				return self
 			end
 			
-			# Add multiple elements to the heap efficiently in O(n) time.
-			# This is more efficient than calling push multiple times (O(n log n)).
+			# Add multiple elements to the heap efficiently.
 			#
 			# @parameter elements [Array] The elements to add to the heap.
 			# @returns [self] Returns self for method chaining.
 			def concat(elements)
 				return self if elements.empty?
 				
-				# Add all elements to the array without maintaining heap property - O(n)
-				@contents.concat(elements)
+				# Rebuilding the whole heap is `O(n + m)`, where `n` is the existing heap size and `m` is the appended batch size. Incremental `push` is `O(m log(n))`, but is often closer to `O(m)` when appended elements are later than the existing entries and do not bubble far. Prefer `heapify` only when building from empty or when the batch dominates the existing heap.
+				if @contents.empty? || elements.size > @contents.size * HEAPIFY_INSERT_RATIO
+					@contents.concat(elements)
+					heapify!
+				else
+					elements.each{|element| push(element)}
+				end
+				
+				return self
+			end
+			
+			# Mutate the heap contents directly, then rebuild the heap property.
+			#
+			# This supports batched operations that can be completed with a single `O(n)` heapify instead of multiple `O(log n)` heap operations.
+			#
+			# @yields {|contents| ...} The heap contents array.
+			# @returns [self] Returns self for method chaining.
+			def heapify
+				yield @contents
 				
-				# Rebuild the heap property for the entire array - O(n)
+				# The block may arbitrarily append, delete or reorder contents, so repair the invariant with one `O(n)` bottom-up heapify pass.
 				heapify!
 				
 				return self

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

@@ -52,15 +52,19 @@ module IO::Event
 				@waiting = nil
 			end
 			
+			# An optional reference to a fiber which can be cleared before it is resumed.
 			Optional = Struct.new(:fiber) do
+				# Transfer control to the fiber if it is still available.
 				def transfer(*arguments)
 					fiber&.transfer(*arguments)
 				end
 				
+				# @returns [Boolean | Nil] Whether the referenced fiber is still alive.
 				def alive?
 					fiber&.alive?
 				end
 				
+				# Clear the referenced fiber.
 				def nullify
 					self.fiber = nil
 				end
@@ -111,7 +115,9 @@ module IO::Event
 				!@ready.empty?
 			end
 			
+			# A linked list node used to track fibers waiting for IO events.
 			Waiter = Struct.new(:fiber, :events, :tail) do
+				# @returns [Boolean | Nil] Whether the waiting fiber is still alive.
 				def alive?
 					self.fiber&.alive?
 				end
@@ -138,10 +144,12 @@ module IO::Event
 					tail&.dispatch(events, &reactivate)
 				end
 				
+				# Clear the waiting fiber so it will not be resumed.
 				def invalidate
 					self.fiber = nil
 				end
 				
+				# Iterate over each active waiting fiber and its requested events.
 				def each(&block)
 					if fiber = self.fiber
 						yield fiber, self.events

data/lib/io/event/selector.rb

@@ -3,12 +3,17 @@
 # Released under the MIT License.
 # Copyright, 2021-2026, by Samuel Williams.
 
+require_relative "native"
 require_relative "selector/select"
 require_relative "debug/selector"
 
 module IO::Event
 	# @namespace
 	module Selector
+		selectors = [:URing, :EPoll, :KQueue, :Select]
+		BEST = const_get(selectors.find{|name| const_defined?(name)})
+		private_constant :BEST
+		
 		# The default selector implementation, which is chosen based on the environment and available implementations.
 		#
 		# @parameter env [Hash] The environment to read configuration from.
@@ -16,16 +21,8 @@ module IO::Event
 		def self.default(env = ENV)
 			if name = env["IO_EVENT_SELECTOR"]&.to_sym
 				return const_get(name)
-			end
-			
-			if self.const_defined?(:URing)
-				URing
-			elsif self.const_defined?(:EPoll)
-				EPoll
-			elsif self.const_defined?(:KQueue)
-				KQueue
 			else
-				Select
+				BEST
 			end
 		end
 		

data/lib/io/event/timers.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2024-2025, by Samuel Williams.
+# Copyright, 2024-2026, by Samuel Williams.
 
 require_relative "priority_heap"
 
@@ -9,6 +9,8 @@ class IO
 	module Event
 		# An efficient sorted set of timers.
 		class Timers
+			COMPACT_MINIMUM_COUNT = 128
+			
 			# A handle to a scheduled timer.
 			class Handle
 				# Initialize the handle with the given time and block.
@@ -16,6 +18,7 @@ class IO
 				# @parameter time [Float] The time at which the block should be called.
 				# @parameter block [Proc] The block to call.
 				def initialize(time, block)
+					@timers = nil
 					@time = time
 					@block = block
 				end
@@ -26,6 +29,16 @@ class IO
 				# @attribute [Proc | Nil] The block to call when the timer fires.
 				attr :block
 				
+				# Mark the timer as inserted into the heap.
+				def schedule!(timers)
+					@timers = timers
+				end
+				
+				# Mark the timer as removed from the heap.
+				def removed!
+					@timers = nil
+				end
+				
 				# Compare the handle with another handle.
 				#
 				# @parameter other [Handle] The other handle to compare with.
@@ -49,7 +62,14 @@ class IO
 				
 				# Cancel the timer.
 				def cancel!
+					return if @block.nil?
+					
 					@block = nil
+					
+					if timers = @timers
+						@timers = nil
+						timers.cancelled!(self)
+					end
 				end
 				
 				# @returns [Boolean] Whether the timer has been cancelled.
@@ -62,6 +82,7 @@ class IO
 			def initialize
 				@heap = PriorityHeap.new
 				@scheduled = []
+				@cancelled = 0
 			end
 			
 			# @returns [Integer] The number of timers in the heap.
@@ -101,6 +122,8 @@ class IO
 				while handle = @heap.peek
 					if handle.cancelled?
 						@heap.pop
+						handle.removed!
+						@cancelled -= 1 if @cancelled > 0
 					else
 						return handle.time - now
 					end
@@ -123,9 +146,12 @@ class IO
 				while handle = @heap.peek
 					if handle.cancelled?
 						@heap.pop
+						handle.removed!
+						@cancelled -= 1 if @cancelled > 0
 					elsif handle.time <= now
 						# Remove the earliest timer from the heap:
 						@heap.pop
+						handle.removed!
 						
 						# Call the block:
 						handle.call(now)
@@ -137,11 +163,53 @@ class IO
 			
 			# Flush all scheduled timers into the heap.
 			#
-			# This is a small optimization which assumes that most timers (timeouts) will be cancelled.
+			# Scheduling appends to `@scheduled` and cancellation is `O(1)`. We pay the cost of filtering and heap repair here, where we can batch work and choose between incremental insertion and one `heapify` pass.
 			protected def flush!
-				while handle = @scheduled.pop
-					@heap.push(handle) unless handle.cancelled?
+				# Once cancelled handles are both numerous and a large fraction of the heap, rebuild the heap. This is `O(n + m)`, but it removes retained cancelled handles and appends live scheduled handles in the same `heapify` pass instead of paying for separate filtering and insertion.
+				if @cancelled >= COMPACT_MINIMUM_COUNT && @cancelled * 2 > @heap.size
+					@heap.heapify do |contents|
+						contents.delete_if do |handle|
+							if handle.cancelled?
+								handle.removed!
+								true
+							end
+						end
+						
+						@scheduled.each do |handle|
+							unless handle.cancelled?
+								handle.schedule!(self)
+								contents << handle
+							end
+						end
+					end
+					
+					@cancelled = 0
+				else
+					# If we are not compacting the heap, filter scheduled handles in place before insertion. This keeps cancelled scheduled handles out of the heap without adding cancellation-time heap deletion.
+					@scheduled.delete_if do |handle|
+						if handle.cancelled?
+							true
+						else
+							handle.schedule!(self)
+							false
+						end
+					end
+					
+					# Small heaps can become entirely cancelled before reaching the compaction threshold. Clear those immediately so `size` does not retain cancelled handles indefinitely.
+					if @cancelled == @heap.size && @scheduled.empty?
+						@heap.clear!
+						@cancelled = 0
+					else
+						@heap.concat(@scheduled)
+					end
 				end
+				
+				@scheduled.clear
+			end
+			
+			# Track cancelled timers that are still retained in the heap.
+			def cancelled!(handle)
+				@cancelled += 1
 			end
 		end
 	end

data/lib/io/event/version.rb

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

data/readme.md

@@ -18,6 +18,14 @@ 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.16.3
+
+  - Handle `IOError` raised while shutting down the pure Ruby interrupt pipe, so `IO::Event::Interrupt#close` does not leak expected shutdown errors from the interrupt fiber.
+
+### v1.16.2
+
+  - Improve timer heap performance by batching scheduled timer insertion, compacting cancelled timers during flush, and avoiding unnecessary heap rebuilds for small incremental inserts.
+
 ### v1.16.1
 
   - Ensure the pure Ruby `Select` selector returns `false`, not `nil`, when `io_wait` resumes without any ready events.
@@ -56,14 +64,6 @@ Please see the [project releases](https://socketry.github.io/io-event/releases/i
 
   - 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.)
-
 ## Contributing
 
 We welcome contributions to this project.

data/releases.md

@@ -1,5 +1,13 @@
 # Releases
 
+## v1.16.3
+
+  - Handle `IOError` raised while shutting down the pure Ruby interrupt pipe, so `IO::Event::Interrupt#close` does not leak expected shutdown errors from the interrupt fiber.
+
+## v1.16.2
+
+  - Improve timer heap performance by batching scheduled timer insertion, compacting cancelled timers during flush, and avoiding unnecessary heap rebuilds for small incremental inserts.
+
 ## v1.16.1
 
   - Ensure the pure Ruby `Select` selector returns `false`, not `nil`, when `io_wait` resumes without any ready events.

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: io-event
 version: !ruby/object:Gem::Version
-  version: 1.16.1
+  version: 1.16.3
 platform: ruby
 authors:
 - Samuel Williams
 - Math Ieu
 - Wander Hillen
 - Jean Boussier
+- Tavian Barnes
 - Benoit Daloze
 - Bruno Sutic
 - Shizuo Fujita
-- Tavian Barnes
 - Alex Matchneer
 - Anthony Ross
 - Delton Ding