io-event 1.6.5 → 1.7.5

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

@@ -35,10 +35,9 @@
 enum {
 	DEBUG = 0,
 	DEBUG_COMPLETION = 0,
+	DEBUG_IO_READ = 1,
 };
 
-static VALUE IO_Event_Selector_URing = Qnil;
-
 enum {URING_ENTRIES = 64};
 
 #pragma mark - Data Type
@@ -140,6 +139,7 @@ size_t IO_Event_Selector_URing_Type_size(const void *_selector)
 	
 	return sizeof(struct IO_Event_Selector_URing)
 		+ IO_Event_Array_memory_size(&selector->completions)
+		+ IO_Event_List_memory_size(&selector->free_list)
 	;
 }
 
@@ -152,7 +152,7 @@ static const rb_data_type_t IO_Event_Selector_URing_Type = {
 		.dsize = IO_Event_Selector_URing_Type_size,
 	},
 	.data = NULL,
-	.flags = RUBY_TYPED_FREE_IMMEDIATELY,
+	.flags = RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED,
 };
 
 inline static
@@ -228,7 +228,7 @@ VALUE IO_Event_Selector_URing_allocate(VALUE self) {
 	struct IO_Event_Selector_URing *selector = NULL;
 	VALUE instance = TypedData_Make_Struct(self, struct IO_Event_Selector_URing, &IO_Event_Selector_URing_Type, selector);
 	
-	IO_Event_Selector_initialize(&selector->backend, Qnil);
+	IO_Event_Selector_initialize(&selector->backend, self, Qnil);
 	selector->ring.ring_fd = -1;
 	
 	selector->pending = 0;
@@ -238,7 +238,10 @@ VALUE IO_Event_Selector_URing_allocate(VALUE self) {
 	
 	selector->completions.element_initialize = IO_Event_Selector_URing_Completion_initialize;
 	selector->completions.element_free = IO_Event_Selector_URing_Completion_free;
-	IO_Event_Array_allocate(&selector->completions, 1024, sizeof(struct IO_Event_Selector_URing_Completion));
+	int result = IO_Event_Array_allocate(&selector->completions, IO_EVENT_ARRAY_DEFAULT_COUNT, sizeof(struct IO_Event_Selector_URing_Completion));
+	if (result < 0) {
+		rb_sys_fail("IO_Event_Selector_URing_allocate:IO_Event_Array_allocate");
+	}
 	
 	return instance;
 }
@@ -249,7 +252,7 @@ VALUE IO_Event_Selector_URing_initialize(VALUE self, VALUE loop) {
 	struct IO_Event_Selector_URing *selector = NULL;
 	TypedData_Get_Struct(self, struct IO_Event_Selector_URing, &IO_Event_Selector_URing_Type, selector);
 	
-	IO_Event_Selector_initialize(&selector->backend, loop);
+	IO_Event_Selector_initialize(&selector->backend, self, loop);
 	int result = io_uring_queue_init(URING_ENTRIES, &selector->ring, 0);
 	
 	if (result < 0) {
@@ -484,6 +487,8 @@ VALUE IO_Event_Selector_URing_process_wait(VALUE self, VALUE fiber, VALUE _pid,
 		.fiber = fiber,
 	};
 	
+	RB_OBJ_WRITTEN(self, Qundef, fiber);
+	
 	struct IO_Event_Selector_URing_Completion *completion = IO_Event_Selector_URing_Completion_acquire(selector, &waiting);
 	
 	struct process_wait_arguments process_wait_arguments = {
@@ -587,6 +592,8 @@ VALUE IO_Event_Selector_URing_io_wait(VALUE self, VALUE fiber, VALUE io, VALUE e
 		.fiber = fiber,
 	};
 	
+	RB_OBJ_WRITTEN(self, Qundef, fiber);
+	
 	struct IO_Event_Selector_URing_Completion *completion = IO_Event_Selector_URing_Completion_acquire(selector, &waiting);
 	
 	struct io_uring_sqe *sqe = io_get_sqe(selector);
@@ -630,6 +637,7 @@ struct io_read_arguments {
 	struct IO_Event_Selector_URing *selector;
 	struct IO_Event_Selector_URing_Waiting *waiting;
 	int descriptor;
+	off_t offset;
 	char *buffer;
 	size_t length;
 };
@@ -643,7 +651,7 @@ io_read_submit(VALUE _arguments)
 	if (DEBUG) fprintf(stderr, "io_read_submit:io_uring_prep_read(waiting=%p, completion=%p, descriptor=%d, buffer=%p, length=%ld)\n", (void*)arguments->waiting, (void*)arguments->waiting->completion, arguments->descriptor, arguments->buffer, arguments->length);
 	
 	struct io_uring_sqe *sqe = io_get_sqe(selector);
-	io_uring_prep_read(sqe, arguments->descriptor, arguments->buffer, arguments->length, io_seekable(arguments->descriptor));
+	io_uring_prep_read(sqe, arguments->descriptor, arguments->buffer, arguments->length, arguments->offset);
 	io_uring_sqe_set_data(sqe, arguments->waiting->completion);
 	io_uring_submit_now(selector);
 	
@@ -673,18 +681,21 @@ io_read_ensure(VALUE _arguments)
 }
 
 static int
-io_read(struct IO_Event_Selector_URing *selector, VALUE fiber, int descriptor, char *buffer, size_t length)
+io_read(struct IO_Event_Selector_URing *selector, VALUE fiber, int descriptor, char *buffer, size_t length, off_t offset)
 {
 	struct IO_Event_Selector_URing_Waiting waiting = {
 		.fiber = fiber,
 	};
 	
+	RB_OBJ_WRITTEN(selector->backend.self, Qundef, fiber);
+	
 	IO_Event_Selector_URing_Completion_acquire(selector, &waiting);
 	
 	struct io_read_arguments io_read_arguments = {
 		.selector = selector,
 		.waiting = &waiting,
 		.descriptor = descriptor,
+		.offset = offset,
 		.buffer = buffer,
 		.length = length
 	};
@@ -707,10 +718,11 @@ VALUE IO_Event_Selector_URing_io_read(VALUE self, VALUE fiber, VALUE io, VALUE b
 	size_t length = NUM2SIZET(_length);
 	size_t offset = NUM2SIZET(_offset);
 	size_t total = 0;
+	off_t from = io_seekable(descriptor);
 	
 	size_t maximum_size = size - offset;
 	while (maximum_size) {
-		int result = io_read(selector, fiber, descriptor, (char*)base+offset, maximum_size);
+		int result = io_read(selector, fiber, descriptor, (char*)base+offset, maximum_size, from);
 		
 		if (result > 0) {
 			total += result;
@@ -744,12 +756,52 @@ static VALUE IO_Event_Selector_URing_io_read_compatible(int argc, VALUE *argv, V
 	return IO_Event_Selector_URing_io_read(self, argv[0], argv[1], argv[2], argv[3], _offset);
 }
 
+VALUE IO_Event_Selector_URing_io_pread(VALUE self, VALUE fiber, VALUE io, VALUE buffer, VALUE _from, VALUE _length, VALUE _offset) {
+	struct IO_Event_Selector_URing *selector = NULL;
+	TypedData_Get_Struct(self, struct IO_Event_Selector_URing, &IO_Event_Selector_URing_Type, selector);
+	
+	int descriptor = IO_Event_Selector_io_descriptor(io);
+	
+	void *base;
+	size_t size;
+	rb_io_buffer_get_bytes_for_writing(buffer, &base, &size);
+	
+	size_t length = NUM2SIZET(_length);
+	size_t offset = NUM2SIZET(_offset);
+	size_t total = 0;
+	off_t from = NUM2OFFT(_from);
+	
+	size_t maximum_size = size - offset;
+	while (maximum_size) {
+		int result = io_read(selector, fiber, descriptor, (char*)base+offset, maximum_size, from);
+		
+		if (result > 0) {
+			total += result;
+			offset += result;
+			from += result;
+			if ((size_t)result >= length) break;
+			length -= result;
+		} else if (result == 0) {
+			break;
+		} else if (length > 0 && IO_Event_try_again(-result)) {
+			IO_Event_Selector_URing_io_wait(self, fiber, io, RB_INT2NUM(IO_EVENT_READABLE));
+		} else {
+			return rb_fiber_scheduler_io_result(-1, -result);
+		}
+		
+		maximum_size = size - offset;
+	}
+	
+	return rb_fiber_scheduler_io_result(total, 0);
+}
+
 #pragma mark - IO#write
 
 struct io_write_arguments {
 	struct IO_Event_Selector_URing *selector;
 	struct IO_Event_Selector_URing_Waiting *waiting;
 	int descriptor;
+	off_t offset;
 	char *buffer;
 	size_t length;
 };
@@ -763,7 +815,7 @@ io_write_submit(VALUE _argument)
 	if (DEBUG) fprintf(stderr, "io_write_submit:io_uring_prep_write(waiting=%p, completion=%p, descriptor=%d, buffer=%p, length=%ld)\n", (void*)arguments->waiting, (void*)arguments->waiting->completion, arguments->descriptor, arguments->buffer, arguments->length);
 	
 	struct io_uring_sqe *sqe = io_get_sqe(selector);
-	io_uring_prep_write(sqe, arguments->descriptor, arguments->buffer, arguments->length, io_seekable(arguments->descriptor));
+	io_uring_prep_write(sqe, arguments->descriptor, arguments->buffer, arguments->length, arguments->offset);
 	io_uring_sqe_set_data(sqe, arguments->waiting->completion);
 	io_uring_submit_pending(selector);
 	
@@ -793,18 +845,21 @@ io_write_ensure(VALUE _argument)
 }
 
 static int
-io_write(struct IO_Event_Selector_URing *selector, VALUE fiber, int descriptor, char *buffer, size_t length)
+io_write(struct IO_Event_Selector_URing *selector, VALUE fiber, int descriptor, char *buffer, size_t length, off_t offset)
 {
 	struct IO_Event_Selector_URing_Waiting waiting = {
 		.fiber = fiber,
 	};
 	
+	RB_OBJ_WRITTEN(selector->backend.self, Qundef, fiber);
+	
 	IO_Event_Selector_URing_Completion_acquire(selector, &waiting);
 	
 	struct io_write_arguments arguments = {
 		.selector = selector,
 		.waiting = &waiting,
 		.descriptor = descriptor,
+		.offset = offset,
 		.buffer = buffer,
 		.length = length,
 	};
@@ -827,6 +882,7 @@ VALUE IO_Event_Selector_URing_io_write(VALUE self, VALUE fiber, VALUE io, VALUE
 	size_t length = NUM2SIZET(_length);
 	size_t offset = NUM2SIZET(_offset);
 	size_t total = 0;
+	off_t from = io_seekable(descriptor);
 	
 	if (length > size) {
 		rb_raise(rb_eRuntimeError, "Length exceeds size of buffer!");
@@ -834,7 +890,7 @@ VALUE IO_Event_Selector_URing_io_write(VALUE self, VALUE fiber, VALUE io, VALUE
 
 	size_t maximum_size = size - offset;
 	while (maximum_size) {
-		int result = io_write(selector, fiber, descriptor, (char*)base+offset, maximum_size);
+		int result = io_write(selector, fiber, descriptor, (char*)base+offset, maximum_size, from);
 		
 		if (result > 0) {
 			total += result;
@@ -868,6 +924,49 @@ static VALUE IO_Event_Selector_URing_io_write_compatible(int argc, VALUE *argv,
 	return IO_Event_Selector_URing_io_write(self, argv[0], argv[1], argv[2], argv[3], _offset);
 }
 
+VALUE IO_Event_Selector_URing_io_pwrite(VALUE self, VALUE fiber, VALUE io, VALUE buffer, VALUE _from, VALUE _length, VALUE _offset) {
+	struct IO_Event_Selector_URing *selector = NULL;
+	TypedData_Get_Struct(self, struct IO_Event_Selector_URing, &IO_Event_Selector_URing_Type, selector);
+	
+	int descriptor = IO_Event_Selector_io_descriptor(io);
+	
+	const void *base;
+	size_t size;
+	rb_io_buffer_get_bytes_for_reading(buffer, &base, &size);
+	
+	size_t length = NUM2SIZET(_length);
+	size_t offset = NUM2SIZET(_offset);
+	size_t total = 0;
+	off_t from = NUM2OFFT(_from);
+	
+	if (length > size) {
+		rb_raise(rb_eRuntimeError, "Length exceeds size of buffer!");
+	}
+
+	size_t maximum_size = size - offset;
+	while (maximum_size) {
+		int result = io_write(selector, fiber, descriptor, (char*)base+offset, maximum_size, from);
+		
+		if (result > 0) {
+			total += result;
+			offset += result;
+			from += result;
+			if ((size_t)result >= length) break;
+			length -= result;
+		} else if (result == 0) {
+			break;
+		} else if (length > 0 && IO_Event_try_again(-result)) {
+			IO_Event_Selector_URing_io_wait(self, fiber, io, RB_INT2NUM(IO_EVENT_WRITABLE));
+		} else {
+			return rb_fiber_scheduler_io_result(-1, -result);
+		}
+		
+		maximum_size = size - offset;
+	}
+	
+	return rb_fiber_scheduler_io_result(total, 0);
+}
+
 #endif
 
 #pragma mark - IO#close
@@ -1094,8 +1193,7 @@ VALUE IO_Event_Selector_URing_wakeup(VALUE self) {
 #pragma mark - Native Methods
 
 void Init_IO_Event_Selector_URing(VALUE IO_Event_Selector) {
-	IO_Event_Selector_URing = rb_define_class_under(IO_Event_Selector, "URing", rb_cObject);
-	rb_gc_register_mark_object(IO_Event_Selector_URing);
+	VALUE IO_Event_Selector_URing = rb_define_class_under(IO_Event_Selector, "URing", rb_cObject);
 	
 	rb_define_alloc_func(IO_Event_Selector_URing, IO_Event_Selector_URing_allocate);
 	rb_define_method(IO_Event_Selector_URing, "initialize", IO_Event_Selector_URing_initialize, 1);
@@ -1120,6 +1218,8 @@ void Init_IO_Event_Selector_URing(VALUE IO_Event_Selector) {
 #ifdef HAVE_RUBY_IO_BUFFER_H
 	rb_define_method(IO_Event_Selector_URing, "io_read", IO_Event_Selector_URing_io_read_compatible, -1);
 	rb_define_method(IO_Event_Selector_URing, "io_write", IO_Event_Selector_URing_io_write_compatible, -1);
+	rb_define_method(IO_Event_Selector_URing, "io_pread", IO_Event_Selector_URing_io_pread, 6);
+	rb_define_method(IO_Event_Selector_URing, "io_pwrite", IO_Event_Selector_URing_io_pwrite, 6);
 #endif
 	
 	rb_define_method(IO_Event_Selector_URing, "io_close", IO_Event_Selector_URing_io_close, 1);

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

@@ -3,22 +3,33 @@
 # Released under the MIT License.
 # Copyright, 2021-2024, by Samuel Williams.
 
-require_relative '../support'
+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
 				
-				if log_path = env['IO_EVENT_DEBUG_SELECTOR_LOG']
-					log = File.open(log_path, 'w')
+				if log_path = env["IO_EVENT_DEBUG_SELECTOR_LOG"]
+					log = File.open(log_path, "w")
 				end
 				
 				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/interrupt.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2021-2023, by Samuel Williams.
+# Copyright, 2021-2024, by Samuel Williams.
 
 module IO::Event
 	# A thread safe synchronisation primative.
@@ -27,7 +27,7 @@ module IO::Event
 		
 		# Send a sigle byte interrupt.
 		def signal
-			@output.write('.')
+			@output.write(".")
 			@output.flush
 		rescue IOError
 			# Ignore.

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

@@ -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)