io-event 1.7.4 → 1.7.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9761a366e91db284c56c77d2ec19db8b6d652d98f2fe39750108e685ff3c2b12
-  data.tar.gz: 3d9d1fab942ec257073a317cecefb06248952e5e7c2518f0298d60b476ec1905
+  metadata.gz: ab271a1de3eb0f5d21b0b7c92cafcc226e5ca218e7b87ebaa80f93a54fd7b945
+  data.tar.gz: fa6227d0b4218b277903fb1c6f1889e51bcfb7e8d8f83086edc30a336a065eff
 SHA512:
-  metadata.gz: 4e7c4790ad17bb655136e1ce25b006c4bc97906b7b46eac2abddddd100eb882d19569da27ae195455b457ea3f243bd8ebe6475a9d0255f1bd11bf33cf66edd15
-  data.tar.gz: 00b9bc9c8ad79828b50b67fdf9fb9a9d25664fb5d9b8c77eb70aa708ee719974b07ba6ed4c3098d76c9b33132061070d36bc39c2c5c707448a9400cef0f2a4ed
+  metadata.gz: d5afc83ef6364791d86b14bdf130d68fda3a7a1c720349dce6bb2140a2ee9f69015e542dbf5c724a0daa338e5f13c87f1dee566e8a36a1b0847ce5e86e1fa92b
+  data.tar.gz: 7d09237e5141123bf251fe686e25fca7d8391a7c25fe331e8882d7e43bf87ff9c5e89bc5c5f90d0731705b923eade10c4667344ad06d04a08544bb9a944baa28

data/ext/io/event/selector/epoll.c

@@ -519,7 +519,7 @@ VALUE IO_Event_Selector_EPoll_process_wait(VALUE self, VALUE fiber, VALUE _pid,
 	
 	RB_OBJ_WRITTEN(self, Qundef, fiber);
 	
-	int result = IO_Event_Selector_EPoll_Waiting_register(selector, 0, descriptor, &waiting);
+	int result = IO_Event_Selector_EPoll_Waiting_register(selector, _pid, descriptor, &waiting);
 	
 	if (result == -1) {
 		close(descriptor);

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

@@ -6,9 +6,16 @@
 require_relative "../support"
 
 module IO::Event
+	# @namespace
 	module Debug
 		# Enforces the selector interface and delegates operations to a wrapped selector instance.
+		#
+		# You can enable this in the default selector by setting the `IO_EVENT_DEBUG_SELECTOR` environment variable. In addition, you can log all selector operations to a file by setting the `IO_EVENT_DEBUG_SELECTOR_LOG` environment variable. This is useful for debugging and understanding the behavior of the event loop.
 		class Selector
+			# Wrap the given selector with debugging.
+			#
+			# @parameter selector [Selector] The selector to wrap.
+			# @parameter env [Hash] The environment to read configuration from.
 			def self.wrap(selector, env = ENV)
 				log = nil
 				
@@ -19,6 +26,10 @@ module IO::Event
 				return self.new(selector, log: log)
 			end
 			
+			# Initialize the debug selector with the given selector and optional log.
+			#
+			# @parameter selector [Selector] The selector to wrap.
+			# @parameter log [IO] The log to write debug messages to.
 			def initialize(selector, log: nil)
 				@selector = selector
 				
@@ -33,14 +44,23 @@ module IO::Event
 				@log = log
 			end
 			
+			# The idle duration of the underlying selector.
+			#
+			# @returns [Numeric] The idle duration.
 			def idle_duration
 				@selector.idle_duration
 			end
 			
+			# The current time.
+			#
+			# @returns [Numeric] The current time.
 			def now
 				Process.clock_gettime(Process::CLOCK_MONOTONIC)
 			end
 			
+			# Log the given message.
+			#
+			# @asynchronous Will block the calling fiber and the entire event loop.
 			def log(message)
 				return unless @log
 				
@@ -49,10 +69,12 @@ module IO::Event
 				end
 			end
 			
+			# Wakeup the the selector.
 			def wakeup
 				@selector.wakeup
 			end
 			
+			# Close the selector.
 			def close
 				log("Closing selector")
 				
@@ -64,60 +86,78 @@ module IO::Event
 				@selector = nil
 			end
 			
-			# Transfer from the calling fiber to the event loop.
+			# Transfer from the calling fiber to the selector.
 			def transfer
 				log("Transfering to event loop")
 				@selector.transfer
 			end
 			
+			# Resume the given fiber with the given arguments.
 			def resume(*arguments)
 				log("Resuming fiber with #{arguments.inspect}")
 				@selector.resume(*arguments)
 			end
 			
+			# Yield to the selector.
 			def yield
 				log("Yielding to event loop")
 				@selector.yield
 			end
 			
+			# Push the given fiber to the selector ready list, such that it will be resumed on the next call to {select}.
+			#
+			# @parameter fiber [Fiber] The fiber that is ready.
 			def push(fiber)
 				log("Pushing fiber #{fiber.inspect} to ready list")
 				@selector.push(fiber)
 			end
 			
+			# Raise the given exception on the given fiber.
+			#
+			# @parameter fiber [Fiber] The fiber to raise the exception on.
+			# @parameter arguments [Array] The arguments to use when raising the exception.
 			def raise(fiber, *arguments)
 				log("Raising exception on fiber #{fiber.inspect} with #{arguments.inspect}")
 				@selector.raise(fiber, *arguments)
 			end
 			
+			# Check if the selector is ready.
+			#
+			# @returns [Boolean] Whether the selector is ready.
 			def ready?
 				@selector.ready?
 			end
 			
+			# Wait for the given process, forwarded to the underlying selector.
 			def process_wait(*arguments)
 				log("Waiting for process with #{arguments.inspect}")
 				@selector.process_wait(*arguments)
 			end
 			
+			# Wait for the given IO, forwarded to the underlying selector.
 			def io_wait(fiber, io, events)
 				log("Waiting for IO #{io.inspect} for events #{events.inspect}")
 				@selector.io_wait(fiber, io, events)
 			end
 			
+			# Read from the given IO, forwarded to the underlying selector.
 			def io_read(fiber, io, buffer, length, offset = 0)
 				log("Reading from IO #{io.inspect} with buffer #{buffer}; length #{length} offset #{offset}")
 				@selector.io_read(fiber, io, buffer, length, offset)
 			end
 			
+			# Write to the given IO, forwarded to the underlying selector.
 			def io_write(fiber, io, buffer, length, offset = 0)
 				log("Writing to IO #{io.inspect} with buffer #{buffer}; length #{length} offset #{offset}")
 				@selector.io_write(fiber, io, buffer, length, offset)
 			end
 			
+			# Forward the given method to the underlying selector.
 			def respond_to?(name, include_private = false)
 				@selector.respond_to?(name, include_private)
 			end
 			
+			# Select for the given duration, forwarded to the underlying selector.
 			def select(duration = nil)
 				log("Selecting for #{duration.inspect}")
 				unless Fiber.current == @selector.loop

data/lib/io/event/priority_heap.rb

@@ -10,6 +10,7 @@ class IO
 		# of its contents to determine priority.
 		# See <https://en.wikipedia.org/wiki/Binary_heap> for explanations of the main methods.
 		class PriorityHeap
+			# Initializes the heap.
 			def initialize
 				# The heap is represented with an array containing a binary tree. See
 				# https://en.wikipedia.org/wiki/Binary_heap#Heap_implementation for how this array
@@ -17,18 +18,19 @@ class IO
 				@contents = []
 			end
 			
-			# Returns the earliest timer or nil if the heap is empty.
+			# @returns [Object | Nil] the smallest element in the heap without removing it, or nil if the heap is empty.
 			def peek
 				@contents[0]
 			end
 			
-			# Returns the number of elements in the heap
+			# @returns [Integer] the number of elements in the heap.
 			def size
 				@contents.size
 			end
 			
-			# Returns the earliest timer if the heap is non-empty and removes it from the heap.
-			# Returns nil if the heap is empty. (and doesn't change the heap in that case)
+			# 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.
 			def pop
 				# If the heap is empty:
 				if @contents.empty?
@@ -57,7 +59,9 @@ class IO
 				return value
 			end
 			
-			# Inserts a new timer into the heap, then rearranges elements until the heap invariant is true again.
+			# Add a new element to the heap, then rearrange elements until the heap invariant is true again.
+			#
+			# @parameter element [Object] The element to add to the heap.
 			def push(element)
 				# Insert the item at the end of the heap:
 				@contents.push(element)
@@ -75,10 +79,9 @@ class IO
 				@contents = []
 			end
 			
-			# Validate the heap invariant. Every element except the root must not be smaller than
-			# its parent element. Note that it MAY be equal.
+			# 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? { |e| @contents[e] >= @contents[(e - 1) / 2] }
 			end
 			
@@ -93,10 +96,7 @@ class IO
 				parent_index = (index - 1) / 2 # watch out, integer division!
 				
 				while index > 0 && @contents[index] < @contents[parent_index]
-					# if the node has a smaller value than its parent, swap these nodes
-					# to uphold the minheap invariant and update the index of the 'current'
-					# node. If the node is already at index 0, we can also stop because that
-					# is the root of the heap.
+					# If the node has a smaller value than its parent, swap these nodes to uphold the minheap invariant and update the index of the 'current' node. If the node is already at index 0, we can also stop because that is the root of the heap.
 					# swap(index, parent_index)
 					@contents[index], @contents[parent_index] = @contents[parent_index], @contents[index]
 					
@@ -114,8 +114,7 @@ class IO
 					left_value = @contents[left_index]
 					
 					if left_value.nil?
-						# This node has no children so it can't bubble down any further.
-						# We're done here!
+						# This node has no children so it can't bubble down any further. We're done here!
 						return
 					end
 					

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

@@ -7,6 +7,10 @@ require "io/nonblock"
 
 module IO::Event
 	module Selector
+		# Execute the given block in non-blocking mode.
+		#
+		# @parameter io [IO] The IO object to operate on.
+		# @yields {...} The block to execute.
 		def self.nonblock(io, &block)
 			io.nonblock(&block)
 		rescue Errno::EBADF

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

@@ -9,7 +9,9 @@ require_relative "../support"
 
 module IO::Event
 	module Selector
+		# A pure-Ruby implementation of the event selector.
 		class Select
+			# Initialize the selector with the given event loop fiber.
 			def initialize(loop)
 				@loop = loop
 				
@@ -23,12 +25,13 @@ module IO::Event
 				@idle_duration = 0.0
 			end
 			
+			# @attribute [Fiber] The event loop fiber.
 			attr :loop
 			
-			# This is the amount of time the event loop was idle during the last select call.
+			# @attribute [Float] This is the amount of time the event loop was idle during the last select call.
 			attr :idle_duration
 			
-			# If the event loop is currently sleeping, wake it up.
+			# Wake up the event loop if it is currently sleeping.
 			def wakeup
 				if @blocked
 					@interrupt.signal
@@ -39,6 +42,7 @@ module IO::Event
 				return false
 			end
 			
+			# Close the selector and release any resources.
 			def close
 				@interrupt.close
 				
@@ -100,6 +104,7 @@ module IO::Event
 				optional.nullify
 			end
 			
+			# @returns [Boolean] Whether the ready list is not empty, i.e. there are fibers ready to be resumed.
 			def ready?
 				!@ready.empty?
 			end
@@ -144,6 +149,11 @@ module IO::Event
 				end
 			end
 			
+			# Wait for the given IO to become readable or writable.
+			#
+			# @parameter fiber [Fiber] The fiber that is waiting.
+			# @parameter io [IO] The IO object to wait on.
+			# @parameter events [Integer] The events to wait for.
 			def io_wait(fiber, io, events)
 				waiter = @waiting[io] = Waiter.new(fiber, events, @waiting[io])
 				
@@ -152,6 +162,11 @@ module IO::Event
 				waiter&.invalidate
 			end
 			
+			# Wait for multiple IO objects to become readable or writable.
+			#
+			# @parameter readable [Array(IO)] The list of IO objects to wait for readability.
+			# @parameter writable [Array(IO)] The list of IO objects to wait for writability.
+			# @parameter priority [Array(IO)] The list of IO objects to wait for priority events.
 			def io_select(readable, writable, priority, timeout)
 				Thread.new do
 					IO.select(readable, writable, priority, timeout)
@@ -161,7 +176,8 @@ module IO::Event
 			EAGAIN = -Errno::EAGAIN::Errno
 			EWOULDBLOCK = -Errno::EWOULDBLOCK::Errno
 			
-			def again?(errno)
+			# Whether the given error code indicates that the operation should be retried.
+			protected def again?(errno)
 				errno == EAGAIN or errno == EWOULDBLOCK
 			end
 			

data/lib/io/event/selector.rb

@@ -8,7 +8,12 @@ require_relative "debug/selector"
 require_relative "support"
 
 module IO::Event
+	# @namespace
 	module Selector
+		# The default selector implementation, which is chosen based on the environment and available implementations.
+		#
+		# @parameter env [Hash] The environment to read configuration from.
+		# @returns [Class] The default selector implementation.
 		def self.default(env = ENV)
 			if name = env["IO_EVENT_SELECTOR"]&.to_sym
 				return const_get(name)
@@ -25,6 +30,11 @@ module IO::Event
 			end
 		end
 		
+		# Create a new selector instance, according to the best available implementation.
+		#
+		# @parameter loop [Fiber] The event loop fiber.
+		# @parameter env [Hash] The environment to read configuration from.
+		# @returns [Selector] The new selector instance.
 		def self.new(loop, env = ENV)
 			selector = default(env).new(loop)
 			

data/lib/io/event/support.rb

@@ -5,16 +5,26 @@
 
 class IO
 	module Event
+		# Helper methods for detecting support for various features.
 		module Support
+			# Some features are only availble if the IO::Buffer class is available.
+			#
+			# @returns [Boolean] Whether the IO::Buffer class is available.
 			def self.buffer?
 				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:
@@ -26,6 +36,8 @@ class IO
 				IO.const_defined?(:Buffer) and Fiber.respond_to?(:blocking) and IO::Buffer.instance_method(:read).arity == -1
 			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?
 				if fiber_scheduler_v2?

data/lib/io/event/timers.rb

@@ -7,42 +7,64 @@ require_relative "priority_heap"
 
 class IO
 	module Event
+		# An efficient sorted set of timers.
 		class Timers
+			# A handle to a scheduled timer.
 			class Handle
+				# Initialize the handle with the given time and block.
+				#
+				# @parameter time [Float] The time at which the block should be called.
+				# @parameter block [Proc] The block to call.
 				def initialize(time, block)
 					@time = time
 					@block = block
 				end
 				
+				# @attribute [Float] The time at which the block should be called.
+				attr :time
+				
+				# @attribute [Proc | Nil] The block to call when the timer fires.
+				attr :block
+				
+				# Compare the handle with another handle.
+				#
+				# @parameter other [Handle] The other handle to compare with.
+				# @returns [Boolean] Whether the handle is less than the other handle.
 				def < other
 					@time < other.time
 				end
 				
+				# Compare the handle with another handle.
+				#
+				# @parameter other [Handle] The other handle to compare with.
+				# @returns [Boolean] Whether the handle is greater than the other handle.
 				def > other
 					@time > other.time
 				end
 				
-				attr :time
-				attr :block
-				
+				# Invoke the block.
 				def call(...)
 					@block.call(...)
 				end
 				
+				# Cancel the timer.
 				def cancel!
 					@block = nil
 				end
 				
+				# @returns [Boolean] Whether the timer has been cancelled.
 				def cancelled?
 					@block.nil?
 				end
 			end
 			
+			# Initialize the timers.
 			def initialize
 				@heap = PriorityHeap.new
 				@scheduled = []
 			end
 			
+			# @returns [Integer] The number of timers in the heap.
 			def size
 				flush!
 				
@@ -50,7 +72,9 @@ class IO
 			end
 			
 			# Schedule a block to be called at a specific time in the future.
+			#
 			# @parameter time [Float] The time at which the block should be called, relative to {#now}.
+			# @parameter block [Proc] The block to call.
 			def schedule(time, block)
 				handle = Handle.new(time, block)
 				
@@ -60,11 +84,18 @@ class IO
 			end
 			
 			# Schedule a block to be called after a specific time offset, relative to the current time as returned by {#now}.
+			#
 			# @parameter offset [#to_f] The time offset from the current time at which the block should be called.
+			# @yields {|now| ...} When the timer fires.
 			def after(offset, &block)
 				schedule(self.now + offset.to_f, block)
 			end
 			
+			
+			# Compute the time interval until the next timer fires.
+			#
+			# @parameter now [Float] The current time.
+			# @returns [Float | Nil] The time interval until the next timer fires, if any.
 			def wait_interval(now = self.now)
 				flush!
 				
@@ -77,10 +108,14 @@ class IO
 				end
 			end
 			
+			# @returns [Float] The current time.
 			def now
 				::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
 			end
 			
+			# Fire all timers that are ready to fire.
+			#
+			# @parameter now [Float] The current time.
 			def fire(now = self.now)
 				# Flush scheduled timers into the heap:
 				flush!
@@ -101,6 +136,9 @@ class IO
 				end
 			end
 			
+			# Flush all scheduled timers into the heap.
+			#
+			# This is a small optimization which assumes that most timers (timeouts) will be cancelled.
 			protected def flush!
 				while handle = @scheduled.pop
 					@heap.push(handle) unless handle.cancelled?

data/lib/io/event/version.rb

@@ -3,8 +3,10 @@
 # Released under the MIT License.
 # Copyright, 2021-2024, by Samuel Williams.
 
+# @namespace
 class IO
+	# @namespace
 	module Event
-		VERSION = "1.7.4"
+		VERSION = "1.7.5"
 	end
 end

data/readme.md

@@ -10,7 +10,17 @@ The initial proof-of-concept [Async](https://github.com/socketry/async) was buil
 
 ## Usage
 
-Please see the [project documentation](https://socketry.github.io/io-event/).
+Please see the [project documentation](https://socketry.github.io/io-event/) for more details.
+
+  - [Getting Started](https://socketry.github.io/io-event/guides/getting-started/index) - This guide explains how to use `io-event` for non-blocking IO.
+
+## Releases
+
+Please see the [project releases](https://socketry.github.io/io-event/releases/index) for all releases.
+
+### v1.7.5
+
+  - Fix `process_wait` race condition on EPoll that could cause a hang.
 
 ## Contributing
 

data/releases.md

@@ -0,0 +1,5 @@
+# Releases
+
+## v1.7.5
+
+  - Fix `process_wait` race condition on EPoll that could cause a hang.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: io-event
 version: !ruby/object:Gem::Version
-  version: 1.7.4
+  version: 1.7.5
 platform: ruby
 authors:
 - Samuel Williams
@@ -45,7 +45,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-11-24 00:00:00.000000000 Z
+date: 2024-12-15 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -83,6 +83,7 @@ files:
 - lib/io/event/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/io-event
 licenses:
 - MIT