scheduler.rb in async-2.20.0

- old
+ new

@@ -25,18 +25,18 @@
 				super
 			end
 		end
 		
 		# Whether the fiber scheduler is supported.
-		# @public Since `stable-v1`.
+		# @public Since *Async v1*.
 		def self.supported?
 			true
 		end
 		
 		# Create a new scheduler.
 		#
-		# @public Since `stable-v1`.
+		# @public Since *Async v1*.
 		# @parameter parent [Node | Nil] The parent node to use for task hierarchy.
 		# @parameter selector [IO::Event::Selector] The selector to use for event handling.
 		def initialize(parent = nil, selector: nil)
 			super(parent)
 			
@@ -50,10 +50,11 @@
 			
 			@timers = ::IO::Event::Timers.new
 		end
 		
 		# Compute the scheduler load according to the busy and idle times that are updated by the run loop.
+		#
 		# @returns [Float] The load of the scheduler. 0.0 means no load, 1.0 means fully loaded or over-loaded.
 		def load
 			total_time = @busy_time + @idle_time
 			
 			# If the total time is zero, then the load is zero:
@@ -93,11 +94,11 @@
 			
 			return @children.nil?
 		end
 		
 		# Terminate all child tasks and close the scheduler.
-		# @public Since `stable-v1`.
+		# @public Since *Async v1*.
 		def close
 			self.run_loop do
 				until self.terminate
 					self.run_once!
 				end
@@ -113,11 +114,11 @@
 			
 			consume
 		end
 		
 		# @returns [Boolean] Whether the scheduler has been closed.
-		# @public Since `stable-v1`.
+		# @public Since *Async v1*.
 		def closed?
 			@selector.nil?
 		end
 		
 		# @returns [String] A description of the scheduler.
@@ -165,10 +166,12 @@
 		def resume(fiber, *arguments)
 			@selector.resume(fiber, *arguments)
 		end
 		
 		# Invoked when a fiber tries to perform a blocking operation which cannot continue. A corresponding call {unblock} must be performed to allow this fiber to continue.
+		#
+
 		# @asynchronous May only be called on same thread as fiber scheduler.
 		def block(blocker, timeout)
 			# $stderr.puts "block(#{blocker}, #{Fiber.current}, #{timeout})"
 			fiber = Fiber.current
 			
@@ -188,50 +191,72 @@
 			end
 		ensure
 			timer&.cancel!
 		end
 		
+		# Unblock a fiber that was previously blocked.
+		#
+		# @public Since *Async v2* and *Ruby v3.1*.
 		# @asynchronous May be called from any thread.
+		#
+		# @parameter blocker [Object] The object that was blocking the fiber.
+		# @parameter fiber [Fiber] The fiber to unblock.
 		def unblock(blocker, fiber)
 			# $stderr.puts "unblock(#{blocker}, #{fiber})"
 			
 			# This operation is protected by the GVL:
 			if selector = @selector
 				selector.push(fiber)
 				selector.wakeup
 			end
 		end
 		
-		# @asynchronous May be non-blocking..
+		# Sleep for the specified duration.
+		#
+		# @public Since *Async v2* and *Ruby v3.1*.
+		# @asynchronous May be non-blocking.
+		#
+		# @parameter duration [Numeric | Nil] The time in seconds to sleep, or if nil, indefinitely.
 		def kernel_sleep(duration = nil)
 			if duration
 				self.block(nil, duration)
 			else
 				self.transfer
 			end
 		end
 		
-		# @asynchronous May be non-blocking..
+		# Resolve the address of the given hostname.
+		#
+		# @public Since *Async v2*.
+		# @asynchronous May be non-blocking.
+		#
+		# @parameter hostname [String] The hostname to resolve.
 		def address_resolve(hostname)
 			# On some platforms, hostnames may contain a device-specific suffix (e.g. %en0). We need to strip this before resolving.
 			# See <https://github.com/socketry/async/issues/180> for more details.
 			hostname = hostname.split("%", 2).first
 			::Resolv.getaddresses(hostname)
 		end
 		
-		
 		if IO.method_defined?(:timeout)
 			private def get_timeout(io)
 				io.timeout
 			end
 		else
 			private def get_timeout(io)
 				nil
 			end
 		end
 		
-		# @asynchronous May be non-blocking..
+		# Wait for the specified IO to become ready for the specified events.
+		#
+		# @public Since *Async v2*.
+		# @asynchronous May be non-blocking.
+		#
+		# @parameter io [IO] The IO object to wait on.
+		# @parameter events [Integer] The events to wait for, e.g. `IO::READABLE`, `IO::WRITABLE`, etc.
+		# @parameter timeout [Float | Nil] The maximum time to wait, or if nil, indefinitely.
 		def io_wait(io, events, timeout = nil)
 			fiber = Fiber.current
 			
 			if timeout
 				# If an explicit timeout is specified, we expect that the user will handle it themselves:
@@ -249,10 +274,19 @@
 		ensure
 			timer&.cancel!
 		end
 		
 		if ::IO::Event::Support.buffer?
+			# Read from the specified IO into the buffer.
+			#
+			# @public Since *Async v2* and Ruby with `IO::Buffer` support.
+			# @asynchronous May be non-blocking.
+			#
+			# @parameter io [IO] The IO object to read from.
+			# @parameter buffer [IO::Buffer] The buffer to read into.
+			# @parameter length [Integer] The minimum number of bytes to read.
+			# @parameter offset [Integer] The offset within the buffer to read into.
 			def io_read(io, buffer, length, offset = 0)
 				fiber = Fiber.current
 				
 				if timeout = get_timeout(io)
 					timer = @timers.after(timeout) do
@@ -264,10 +298,19 @@
 			ensure
 				timer&.cancel!
 			end
 			
 			if RUBY_ENGINE != "ruby" || RUBY_VERSION >= "3.3.1"
+				# Write the specified buffer to the IO.
+				#
+				# @public Since *Async v2* and *Ruby v3.3.1* with `IO::Buffer` support.
+				# @asynchronous May be non-blocking.
+				#
+				# @parameter io [IO] The IO object to write to.
+				# @parameter buffer [IO::Buffer] The buffer to write from.
+				# @parameter length [Integer] The minimum number of bytes to write.
+				# @parameter offset [Integer] The offset within the buffer to write from.
 				def io_write(io, buffer, length, offset = 0)
 					fiber = Fiber.current
 					
 					if timeout = get_timeout(io)
 						timer = @timers.after(timeout) do
@@ -281,10 +324,14 @@
 				end
 			end
 		end
 		
 		# Wait for the specified process ID to exit.
+		#
+		# @public Since *Async v2*.
+		# @asynchronous May be non-blocking.
+		#
 		# @parameter pid [Integer] The process ID to wait for.
 		# @parameter flags [Integer] A bit-mask of flags suitable for `Process::Status.wait`.
 		# @returns [Process::Status] A process status instance.
 		# @asynchronous May be non-blocking..
 		def process_wait(pid, flags)
@@ -333,11 +380,14 @@
 			# The reactor still has work to do:
 			return true
 		end
 		
 		# Run one iteration of the event loop.
-		# Does not handle interrupts.
+		#
+		# @public Since *Async v1*.
+		# @asynchronous Must be invoked from blocking (root) fiber.
+		#
 		# @parameter timeout [Float | Nil] The maximum timeout, or if nil, indefinite.
 		# @returns [Boolean] Whether there is more work to do.
 		def run_once(timeout = nil)
 			Kernel.raise "Running scheduler on non-blocking fiber!" unless Fiber.blocking?
 			
@@ -352,10 +402,11 @@
 			
 			return run_once!(timeout)
 		end
 		
 		# Checks and clears the interrupted state of the scheduler.
+		#
 		# @returns [Boolean] Whether the reactor has been interrupted.
 		private def interrupted?
 			if @interrupted
 				@interrupted = false
 				return true
@@ -366,11 +417,13 @@
 			end
 			
 			return false
 		end
 		
-		# Stop all children, including transient children, ignoring any signals.
+		# Stop all children, including transient children.
+		#
+		# @public Since *Async v1*.
 		def stop
 			@children&.each do |child|
 				child.stop
 			end
 		end
@@ -385,10 +438,11 @@
 						# If we are finished, we need to exit:
 						break unless yield
 					end
 				end
 			rescue Interrupt => interrupt
+				# If an interrupt did occur during an iteration of the event loop, we need to handle it. More specifically, `self.stop` is not safe to interrupt without potentially corrupting the task tree.
 				Thread.handle_interrupt(::SignalException => :never) do
 					Console.debug(self) do |buffer|
 						buffer.puts "Scheduler interrupted: #{interrupt.inspect}"
 						self.print_hierarchy(buffer)
 					end
@@ -404,10 +458,17 @@
 				Kernel.raise(interrupt)
 			end
 		end
 		
 		# Run the reactor until all tasks are finished. Proxies arguments to {#async} immediately before entering the loop, if a block is provided.
+		#
+		# Forwards all parameters to {#async} if a block is given.
+		#
+		# @public Since *Async v1*.
+		#
+		# @yields {|task| ...} The top level task, if a block is given.
+		# @returns [Task] The initial task that was scheduled into the reactor.
 		def run(...)
 			Kernel.raise ClosedError if @selector.nil?
 			
 			initial_task = self.async(...) if block_given?
 			
@@ -416,43 +477,43 @@
 			end
 			
 			return initial_task
 		end
 		
-		# Start an asynchronous task within the specified reactor. The task will be
-		# executed until the first blocking call, at which point it will yield and
-		# and this method will return.
+		# Start an asynchronous task within the specified reactor. The task will be executed until the first blocking call, at which point it will yield and and this method will return.
 		#
-		# This is the main entry point for scheduling asynchronus tasks.
+		# @public Since *Async v1*.
+		# @asynchronous May context switch immediately to new task.
+		# @deprecated Use {#run} or {Task#async} instead.
 		#
 		# @yields {|task| ...} Executed within the task.
 		# @returns [Task] The task that was scheduled into the reactor.
-		# @deprecated With no replacement.
 		def async(*arguments, **options, &block)
+			# warn "Async::Scheduler#async is deprecated. Use `run` or `Task#async` instead.", uplevel: 1, category: :deprecated
+			
 			Kernel.raise ClosedError if @selector.nil?
 			
 			task = Task.new(Task.current? || self, **options, &block)
 			
-			# I want to take a moment to explain the logic of this.
-			# When calling an async block, we deterministically execute it until the
-			# first blocking operation. We don't *have* to do this - we could schedule
-			# it for later execution, but it's useful to:
-			# - Fail at the point of the method call where possible.
-			# - Execute determinstically where possible.
-			# - Avoid scheduler overhead if no blocking operation is performed.
 			task.run(*arguments)
 			
-			# Console.debug "Initial execution of task #{fiber} complete (#{result} -> #{fiber.alive?})..."
 			return task
 		end
 		
 		def fiber(...)
 			return async(...).fiber
 		end
 		
 		# Invoke the block, but after the specified timeout, raise {TimeoutError} in any currenly blocking operation. If the block runs to completion before the timeout occurs or there are no non-blocking operations after the timeout expires, the code will complete without any exception.
+		#
+		# @public Since *Async v1*.
+		# @asynchronous May raise an exception at any interruption point (e.g. blocking operations).
+		#
 		# @parameter duration [Numeric] The time in seconds, in which the task should complete.
+		# @parameter exception [Class] The exception class to raise.
+		# @parameter message [String] The message to pass to the exception.
+		# @yields {|duration| ...} The block to execute with a timeout.
 		def with_timeout(duration, exception = TimeoutError, message = "execution expired", &block)
 			fiber = Fiber.current
 			
 			timer = @timers.after(duration) do
 				if fiber.alive?
@@ -463,9 +524,18 @@
 			yield timer
 		ensure
 			timer&.cancel!
 		end
 		
+		# Invoke the block, but after the specified timeout, raise the specified exception with the given message. If the block runs to completion before the timeout occurs or there are no non-blocking operations after the timeout expires, the code will complete without any exception.
+		#
+		# @public Since *Async v1* and *Ruby v3.1*. May be invoked from `Timeout.timeout`.
+		# @asynchronous May raise an exception at any interruption point (e.g. blocking operations).
+		#
+		# @parameter duration [Numeric] The time in seconds, in which the task should complete.
+		# @parameter exception [Class] The exception class to raise.
+		# @parameter message [String] The message to pass to the exception.
+		# @yields {|duration| ...} The block to execute with a timeout.
 		def timeout_after(duration, exception, message, &block)
 			with_timeout(duration, exception, message) do |timer|
 				yield duration
 			end
 		end