io-event 1.16.1 → 1.16.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd552a5bb53e9a2e9169c55a7f789e84f761a2707c83edd5955512818ad55e25
-  data.tar.gz: 97a35fef870d94f7c596d612fdd6664c2e65cff9b14a8cf6b9035b12584f0833
+  metadata.gz: 8cc6abcf010ce881e4623a5736241660d1ebf6a84883767d761616ddcb23bf4e
+  data.tar.gz: 4a438756e87e8feaefaafb40014f36c2b240fbbd837d4581c657eb310cb9b95a
 SHA512:
-  metadata.gz: e187b07cc91e2ecf7fb641a61f481fbb9ba42a1a52c14532fa659ede0a6723dde5ac63e35d7a584d549ca52a94462131f5755b9da7bce1b06abd99f1ea6b3f24
-  data.tar.gz: '090f2023d28eac6b05386727f0497bbd02db76b6a3bf0b43f9e068e5e5d36edb543a16c94806fea736c319298b491b1d13e069c7f89bf41a89dd86171b183c96'
+  metadata.gz: b910e009ff697f179290d916e5914621d25a5478e0f09ac806563a0c3808b30fc28ca652042608e60625830468f37088943559c590112dfadb0d3a48d3b54688
+  data.tar.gz: c7501e4ef87e5c9744d666e43494b60b2b3c490d9e9cb55b75a87f7de199e1421b49ba0ce5e176cbaf230d6f3b8f838a5745cff81bac6f826328e7665de7a9e9

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

@@ -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.2"
 	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.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.
@@ -60,10 +64,6 @@ Please see the [project releases](https://socketry.github.io/io-event/releases/i
 
   - 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,9 @@
 # Releases
 
+## 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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: io-event
 version: !ruby/object:Gem::Version
-  version: 1.16.1
+  version: 1.16.2
 platform: ruby
 authors:
 - Samuel Williams