io-event 1.6.5 → 1.7.5

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

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

data/lib/io/event.rb

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

data/license.md

@@ -8,6 +8,9 @@ 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,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
 
@@ -24,8 +34,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,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.6.5
+  version: 1.7.5
 platform: ruby
 authors:
 - Samuel Williams
@@ -10,6 +10,7 @@ authors:
 - Benoit Daloze
 - Bruno Sutic
 - Alex Matchneer
+- Anthony Ross
 - Delton Ding
 - Pavel Rosický
 autorequire:
@@ -44,7 +45,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-06-23 00:00:00.000000000 Z
+date: 2024-12-15 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -82,10 +83,13 @@ files:
 - lib/io/event/version.rb
 - license.md
 - readme.md
+- releases.md
 homepage: https://github.com/socketry/io-event
 licenses:
 - MIT
-metadata: {}
+metadata:
+  documentation_uri: https://socketry.github.io/io-event/
+  source_code_uri: https://github.com/socketry/io-event.git
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -101,7 +105,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: An event loop.