io-event 1.6.5 → 1.9.0

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "native"
+
+module IO::Event
+	unless self.const_defined?(:Profiler)
+		module Profiler
+			# The default profiler, if the platform supports it.
+			# Use `IO_EVENT_PROFILER=true` to enable it.
+			def self.default
+				nil
+			end
+		end
+	end
+end

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

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2023, by Samuel Williams.
+# Copyright, 2022-2024, by Samuel Williams.
 
-require 'io/nonblock'
+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

@@ -4,12 +4,14 @@
 # Copyright, 2021-2024, by Samuel Williams.
 # Copyright, 2023, by Math Ieu.
 
-require_relative '../interrupt'
-require_relative '../support'
+require_relative "../interrupt"
+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,13 +176,16 @@ 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
 			
 			if Support.fiber_scheduler_v3?
 				# Ruby 3.3+, full IO::Buffer support.
 				
+				# Read from the given IO to the buffer.
+				#
 				# @parameter length [Integer] The minimum number of bytes to read.
 				# @parameter offset [Integer] The offset into the buffer to read to.
 				def io_read(fiber, io, buffer, length, offset = 0)
@@ -196,6 +214,8 @@ module IO::Event
 					return total
 				end
 				
+				# Write to the given IO from the buffer.
+				#
 				# @parameter length [Integer] The minimum number of bytes to write.
 				# @parameter offset [Integer] The offset into the buffer to write from.
 				def io_write(fiber, io, buffer, length, offset = 0)

data/lib/io/event/selector.rb

@@ -3,14 +3,19 @@
 # Released under the MIT License.
 # Copyright, 2021-2024, by Samuel Williams.
 
-require_relative 'selector/select'
-require_relative 'debug/selector'
-require_relative 'support'
+require_relative "selector/select"
+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
+			if name = env["IO_EVENT_SELECTOR"]&.to_sym
 				return const_get(name)
 			end
 			
@@ -25,10 +30,15 @@ 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)
 			
-			if debug = env['IO_EVENT_DEBUG_SELECTOR']
+			if debug = env["IO_EVENT_DEBUG_SELECTOR"]
 				selector = Debug::Selector.wrap(selector, env)
 			end
 			

data/lib/io/event/support.rb

@@ -1,23 +1,44 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2022-2023, by Samuel Williams.
+# Copyright, 2022-2024, by Samuel Williams.
 
 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) and !Fiber.respond_to?(:blocking)
+				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
 			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?
 					return true if RUBY_VERSION >= "3.3"

data/lib/io/event/timers.rb

@@ -3,46 +3,68 @@
 # Released under the MIT License.
 # Copyright, 2024, by Samuel Williams.
 
-require_relative 'priority_heap'
+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

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2024, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
 
+# @namespace
 class IO
+	# @namespace
 	module Event
-		VERSION = "1.6.5"
+		VERSION = "1.9.0"
 	end
 end

data/lib/io/event.rb

@@ -1,15 +1,9 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2024, by Samuel Williams.
+# Copyright, 2021-2025, by Samuel Williams.
 
-require_relative 'event/version'
-require_relative 'event/selector'
-require_relative 'event/timers'
-
-begin
-	require 'IO_Event'
-rescue LoadError => error
-	warn "Could not load native event selector: #{error}"
-	require_relative 'event/selector/nonblock'
-end
+require_relative "event/version"
+require_relative "event/selector"
+require_relative "event/timers"
+require_relative "event/native"

data/license.md

@@ -1,13 +1,16 @@
 # MIT License
 
 Copyright, 2021, by Wander Hillen.  
-Copyright, 2021-2024, by Samuel Williams.  
+Copyright, 2021-2025, by Samuel Williams.  
 Copyright, 2021, by Delton Ding.  
 Copyright, 2021-2024, by Benoit Daloze.  
 Copyright, 2022, by Alex Matchneer.  
 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, by Jean Boussier.  
 
 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

@@ -10,7 +10,25 @@ 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.9.0
+
+  - [Improved `IO::Event::Profiler` for detecting stalls.](https://socketry.github.io/io-event/releases/index#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.)
+
+### v1.7.5
+
+  - Fix `process_wait` race condition on EPoll that could cause a hang.
 
 ## Contributing
 
@@ -24,8 +42,8 @@ We welcome contributions to this project.
 
 ### Developer Certificate of Origin
 
-This project uses the [Developer Certificate of Origin](https://developercertificate.org/). All contributors to this project must agree to this document to have their contributions accepted.
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
 
-### Contributor Covenant
+### Community Guidelines
 
-This project is governed by the [Contributor Covenant](https://www.contributor-covenant.org/). All contributors and participants agree to abide by its terms.
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

data/releases.md

@@ -0,0 +1,57 @@
+# Releases
+
+## v1.9.0
+
+### Improved `IO::Event::Profiler` for detecting stalls.
+
+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.
+
+``` ruby
+profiler = IO::Event::Profiler.new
+
+profiler.start
+		
+Fiber.new do
+	sleep 1.0
+end.transfer
+
+profiler.stop
+```
+
+A default profiler is exposed using `IO::Event::Profiler.default` which is controlled by the following environment variables:
+
+  - `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`.
+
+The previous environment variables `IO_EVENT_SELECTOR_STALL_LOG_THRESHOLD` and `IO_EVENT_SELECTOR_STALL_LOG` no longer have any effect.
+
+## 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.
+
+## v1.7.5
+
+  - Fix `process_wait` race condition on EPoll that could cause a hang.

metadata

@@ -1,18 +1,20 @@
 --- !ruby/object:Gem::Specification
 name: io-event
 version: !ruby/object:Gem::Version
-  version: 1.6.5
+  version: 1.9.0
 platform: ruby
 authors:
 - Samuel Williams
 - Math Ieu
 - Wander Hillen
+- Jean Boussier
 - Benoit Daloze
 - Bruno Sutic
 - Alex Matchneer
+- Anthony Ross
 - Delton Ding
 - Pavel Rosický
-autorequire:
+- Shizuo Fujita
 bindir: bin
 cert_chain:
 - |
@@ -44,10 +46,8 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-06-23 00:00:00.000000000 Z
+date: 2025-02-10 00:00:00.000000000 Z
 dependencies: []
-description:
-email:
 executables: []
 extensions:
 - ext/extconf.rb
@@ -55,25 +55,33 @@ extra_rdoc_files: []
 files:
 - design.md
 - ext/extconf.rb
+- ext/io/event/array.h
 - ext/io/event/event.c
 - ext/io/event/event.h
+- ext/io/event/fiber.c
+- ext/io/event/fiber.h
 - ext/io/event/interrupt.c
 - ext/io/event/interrupt.h
-- ext/io/event/selector/array.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
 - ext/io/event/selector/kqueue.h
-- ext/io/event/selector/list.h
 - ext/io/event/selector/pidfd.c
 - ext/io/event/selector/selector.c
 - ext/io/event/selector/selector.h
 - ext/io/event/selector/uring.c
 - ext/io/event/selector/uring.h
+- ext/io/event/time.c
+- ext/io/event/time.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
@@ -82,11 +90,13 @@ files:
 - lib/io/event/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/io-event
 licenses:
 - MIT
-metadata: {}
-post_install_message:
+metadata:
+  documentation_uri: https://socketry.github.io/io-event/
+  source_code_uri: https://github.com/socketry/io-event.git
 rdoc_options: []
 require_paths:
 - lib
@@ -101,8 +111,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: An event loop.
 test_files: []