io-event 1.12.1 → 1.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15970f96a2af0de9aa23889ee6ff50217b53216334de39ad5b4692ebf945942b
-  data.tar.gz: 5f44f0dbcdf09106e342e3fda71f56f8a0208dc5a435e82f8c80b1fdb8826fae
+  metadata.gz: a32ca73de2138ec23628217095bdfd7414f9b898e2af962922e449b297b20821
+  data.tar.gz: 67d4d9f80ec4195efdda39dc71ed5c84772336bcf1701d691115212143fd6912
 SHA512:
-  metadata.gz: 0b72815ede642358071d66b9720935603493b6a09a34fcf2eec6930c8648a7d2b6498358f630554f40c6537f2bd0fb3cb6b58334ad58dfbaacc5d6c1f0e407cf
-  data.tar.gz: a5eb4e8396cd510aa71e8ee45f8ebf60829ca707a96bded1104ce0c3f74c47e9343225d826c58e4ec7bcfed6aed81051d7c14a10f304c42fa61fe930e1099fef
+  metadata.gz: 12e19eb71a5f491b3513f2506474e2b184e9b4231e70cd9282b8ebdb38a214133c2d1b4fdf77d1a502c2758b29b1fe2160f55b47e060e6cd24fe36a5ed646405
+  data.tar.gz: 6ad9a898bb51eea78a28160b1d12ba8ffea073842971741c264ffad4f71e96d722289ebd840f5a2f365361926e98819b4e45014860dc4cd1eaa0f96c4fd540a1

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.

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.13.0"
 	end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: io-event
 version: !ruby/object:Gem::Version
-  version: 1.12.1
+  version: 1.13.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.6.9
 specification_version: 4
 summary: An event loop.
 test_files: []