io-event 1.12.1 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15970f96a2af0de9aa23889ee6ff50217b53216334de39ad5b4692ebf945942b
-  data.tar.gz: 5f44f0dbcdf09106e342e3fda71f56f8a0208dc5a435e82f8c80b1fdb8826fae
+  metadata.gz: 53a9942daf957580fe332adea530a3bba659c0ec5405560078233ead0b893d11
+  data.tar.gz: d6eea90381836e4f1bf62430ae95ea0f7f2b1693683d2a114b5193f0c7a1d3f8
 SHA512:
-  metadata.gz: 0b72815ede642358071d66b9720935603493b6a09a34fcf2eec6930c8648a7d2b6498358f630554f40c6537f2bd0fb3cb6b58334ad58dfbaacc5d6c1f0e407cf
-  data.tar.gz: a5eb4e8396cd510aa71e8ee45f8ebf60829ca707a96bded1104ce0c3f74c47e9343225d826c58e4ec7bcfed6aed81051d7c14a10f304c42fa61fe930e1099fef
+  metadata.gz: 9bfd04d670380038ec6a57a212f0f927b3fd748f93ac95c26e04adb1ed829a999fc02ebca56a27812c84be402b9fef576ba5d53be0df7b8f5e06bb516c70f2b6
+  data.tar.gz: ca71eac94412be0bbb953d32eb60ef1654fe24535012bc3f6f9a1a5375377175a71641c28e5ab92a5f3d44418ab50c3ef177a552cc0abe57f633e718cb2b4bc4

data/context/getting-started.md

@@ -0,0 +1,61 @@
+# Getting Started
+
+This guide explains how to use `io-event` for non-blocking IO.
+
+## Installation
+
+Add the gem to your project:
+
+~~~ bash
+$ bundle add io-event
+~~~
+
+## Core Concepts
+
+`io-event` has several core concepts:
+
+- A {ruby IO::Event::Selector} implementation which provides the primitive operations for implementation an event loop.
+- A {ruby IO::Event::Debug::Selector} which adds extra validations and checks at the expense of performance. You should generally use this during tests.
+
+## Basic Event Loop
+
+This example shows how to perform a blocking operation 
+
+```ruby
+require 'fiber'
+require 'io/event'
+
+selector = IO::Event::Selector.new(Fiber.current)
+input, output = IO.pipe
+
+writer = Fiber.new do
+	output.write("Hello World")
+	output.close
+end
+
+reader = Fiber.new do
+	selector.io_wait(Fiber.current, input, IO::READABLE)
+	pp read: input.read
+end
+
+# The reader will be blocked until the IO has data available:
+reader.transfer
+
+# Write some data to the pipe and close the writing end:
+writer.transfer
+
+selector.select(1)
+
+# Results in:
+# {:read=>"Hello World"}
+```
+
+## Debugging
+
+The {ruby IO::Event::Debug::Selector} class adds extra validations and checks at the expense of performance. It can also log all operations. You can use this by setting the following environment variables:
+
+```shell
+$ IO_EVENT_SELECTOR_DEBUG=y IO_EVENT_SELECTOR_DEBUG_LOG=/dev/stderr bundle exec ./my_script.rb
+```
+
+The format of the log is subject to change, but it may be useful for debugging.

data/context/index.yaml

@@ -0,0 +1,11 @@
+# Automatically generated context index for Utopia::Project guides.
+# Do not edit then files in this directory directly, instead edit the guides and then run `bake utopia:project:agent:context:update`.
+---
+description: An event loop.
+metadata:
+  documentation_uri: https://socketry.github.io/io-event/
+  source_code_uri: https://github.com/socketry/io-event.git
+files:
+- path: getting-started.md
+  title: Getting Started
+  description: This guide explains how to use `io-event` for non-blocking IO.

data/ext/extconf.rb

@@ -19,7 +19,7 @@ append_cflags(["-Wall", "-Wno-unknown-pragmas", "-std=c99"])
 
 if ENV.key?("RUBY_DEBUG")
 	$stderr.puts "Enabling debug mode..."
-
+	
 	append_cflags(["-DRUBY_DEBUG", "-O0"])
 end
 
@@ -33,7 +33,7 @@ have_func("&rb_fiber_transfer")
 if have_library("uring") and have_header("liburing.h")
 	# We might want to consider using this in the future:
 	# have_func("io_uring_submit_and_wait_timeout", "liburing.h")
-
+	
 	$srcs << "io/event/selector/uring.c"
 end
 
@@ -70,7 +70,7 @@ end
 
 if ENV.key?("RUBY_SANITIZE")
 	$stderr.puts "Enabling sanitizers..."
-
+	
 	# Add address and undefined behaviour sanitizers:
 	append_cflags(["-fsanitize=address", "-fsanitize=undefined", "-fno-omit-frame-pointer"])
 	$LDFLAGS << " -fsanitize=address -fsanitize=undefined"

data/lib/io/event/debug/selector.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.
 
 require_relative "../support"
 

data/lib/io/event/priority_heap.rb

@@ -2,7 +2,7 @@
 
 # Released under the MIT License.
 # Copyright, 2021, by Wander Hillen.
-# Copyright, 2021-2024, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
 
 class IO
 	module Event
@@ -28,6 +28,11 @@ class IO
 				@contents.size
 			end
 			
+			# @returns [Boolean] true if the heap is empty, false otherwise.
+			def empty?
+				@contents.empty?
+			end
+			
 			# Removes and returns the smallest element in the heap, or nil if the heap is empty.
 			#
 			# @returns [Object | Nil] The smallest element in the heap, or nil if the heap is empty.
@@ -74,19 +79,112 @@ 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)).
+			#
+			# @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)
+				
+				# Rebuild the heap property for the entire array - O(n)
+				heapify!
+				
+				return self
+			end
+			
 			# Empties out the heap, discarding all elements
 			def clear!
 				@contents = []
 			end
 			
+			# Remove a specific element from the heap.
+			#
+			# O(n) where n is the number of elements in the heap.
+			#
+			# @parameter element [Object] The element to remove.
+			# @returns [Object | Nil] The removed element, or nil if not found.
+			def delete(element)
+				# Find the index of the element - O(n) linear search
+				index = @contents.index(element)
+				return nil unless index
+				
+				# If it's the last element, just remove it
+				if index == @contents.size - 1
+					return @contents.pop
+				end
+				
+				# Store the value we're removing
+				removed_value = @contents[index]
+				
+				# Replace with the last element
+				last = @contents.pop
+				@contents[index] = last
+				
+				# Restore heap property - might need to bubble up or down
+				if index > 0 && @contents[index] < @contents[(index - 1) / 2]
+					# New element is smaller than parent, bubble up
+					bubble_up(index)
+				else
+					# New element might be larger than children, bubble down
+					bubble_down(index)
+				end
+				
+				# validate!
+				
+				return removed_value
+			end
+			
+			# Remove elements matching the given block condition by rebuilding the heap.
+			#
+			# This is more efficient than multiple delete operations when removing many elements.
+			#
+			# O(n) where n is the number of elements in the heap.
+			#
+			# @yields [Object] Each element in the heap for testing
+			# @returns [Integer] The number of elements removed
+			def delete_if
+				return enum_for(:delete_if) unless block_given?
+				
+				original_size = @contents.size
+				
+				# Filter out elements that match the condition - O(n)
+				@contents.reject! {|element| yield(element)}
+				
+				# If we removed elements, rebuild the heap - O(n)
+				if @contents.size < original_size
+					heapify!
+				end
+				
+				# Return number of elements removed
+				original_size - @contents.size
+			end
+			
 			# 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
+				# Notice we skip index 0 on purpose, because it has no parent:
 				(1..(@contents.size - 1)).all? {|index| @contents[index] >= @contents[(index - 1) / 2]}
 			end
 			
 			private
 			
+			# Rebuild the heap property from an arbitrary array in O(n) time.
+			# Uses bottom-up heapify algorithm starting from the last non-leaf node.
+			def heapify!
+				return if @contents.size <= 1
+				
+				# Start from the last non-leaf node and work backwards to root:
+				last_non_leaf_index = (@contents.size / 2) - 1
+				last_non_leaf_index.downto(0) do |index|
+					bubble_down(index)
+				end
+				
+				# validate!
+			end
+			
 			# Left here for reference, but unused.
 			# def swap(i, j)
 			# 	@contents[i], @contents[j] = @contents[j], @contents[i]

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

@@ -363,7 +363,7 @@ module IO::Event
 								priority << io
 							end
 						end
-
+						
 						false
 					end
 				end

data/lib/io/event/support.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2024, by Samuel Williams.
+# Copyright, 2022-2025, by Samuel Williams.
 
 class IO
 	module Event

data/lib/io/event/version.rb

@@ -7,6 +7,6 @@
 class IO
 	# @namespace
 	module Event
-		VERSION = "1.12.1"
+		VERSION = "1.14.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.14.0
+
+  - [Enhanced `IO::Event::PriorityHeap` with deletion and bulk insertion methods](https://socketry.github.io/io-event/releases/index#enhanced-io::event::priorityheap-with-deletion-and-bulk-insertion-methods)
+
 ### v1.11.2
 
   - Fix Windows build.

data/releases.md

@@ -1,5 +1,37 @@
 # Releases
 
+## v1.14.0
+
+### Enhanced `IO::Event::PriorityHeap` with deletion and bulk insertion methods
+
+The {ruby IO::Event::PriorityHeap} now supports efficient element removal and bulk insertion:
+
+  - **`delete(element)`**: Remove a specific element from the heap in O(n) time
+  - **`delete_if(&block)`**: Remove elements matching a condition with O(n) amortized bulk deletion
+  - **`concat(elements)`**: Add multiple elements efficiently in O(n) time
+
+<!-- end list -->
+
+``` ruby
+heap = IO::Event::PriorityHeap.new
+
+# Efficient bulk insertion - O(n) instead of O(n log n)
+heap.concat([5, 2, 8, 1, 9, 3])
+
+# Remove specific element
+removed = heap.delete(5)  # Returns 5, heap maintains order
+
+# Bulk removal with condition
+count = heap.delete_if { |x| x.even? }  # Removes 2, 8 efficiently
+```
+
+The `delete_if` and `concat` methods are particularly efficient for bulk operations, using bottom-up heapification to maintain the heap property in O(n) time. This provides significant performance improvements:
+
+  - **Bulk insertion**: O(n log n) → O(n) for adding multiple elements
+  - **Bulk deletion**: O(k×n) → O(n) for removing k elements
+
+Both methods maintain the heap invariant and include comprehensive test coverage with edge case validation.
+
 ## v1.11.2
 
   - Fix Windows build.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: io-event
 version: !ruby/object:Gem::Version
-  version: 1.12.1
+  version: 1.14.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -55,6 +55,8 @@ extensions:
 extra_rdoc_files: []
 files:
 - agent.md
+- context/getting-started.md
+- context/index.yaml
 - design.md
 - ext/extconf.rb
 - ext/io/event/array.h
@@ -114,7 +116,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.7.0.dev
 specification_version: 4
 summary: An event loop.
 test_files: []