class Async::Task

@public Since ‘stable-v1`.

def self.current

@raises[RuntimeError] If task was not {set!} for the current fiber.
@returns [Task]
Lookup the {Task} for the current fiber. Raise `RuntimeError` if none is available.
def self.current
	Thread.current[:async_task] or raise RuntimeError, "No async task available!"
end

def self.current?

@returns [Task | Nil]
Check if there is a task defined for the current fiber.
def self.current?
	Thread.current[:async_task]
end

def self.yield

Deprecated:
  • With no replacement.
def self.yield
	Fiber.scheduler.transfer
end

def alive?

Whether the internal fiber is alive, i.e. it
def alive?
	@fiber&.alive?
end

def annotate(annotation, &block)

def annotate(annotation, &block)
	if @fiber
		@fiber.annotate(annotation, &block)
	else
		super
	end
end

def annotation

def annotation
	if @fiber
		@fiber.annotation
	else
		super
	end
end

def async(*arguments, **options, &block)

Run an asynchronous task as a child of the current task.
def async(*arguments, **options, &block)
	raise FinishedError if self.finished?
	
	task = Task.new(self, **options, &block)
	
	task.run(*arguments)
	
	return task
end

def backtrace(*arguments)

def backtrace(*arguments)
	@fiber&.backtrace(*arguments)
end

def completed!(result)

State transition into the completed state.
def completed!(result)
	@result = result
	@status = :completed
end

def completed?

The task has completed execution and generated a result.
def completed?
	@status == :completed
end

def current?

def current?
	Fiber.current.equal?(@fiber)
end

def failed!(exception = false, propagate = true)

This is a very tricky aspect of tasks to get right. I've modelled it after `Thread` but it's slightly different in that the exception can propagate back up through the reactor. If the user writes code which raises an exception, that exception should always be visible, i.e. cause a failure. If it's not visible, such code fails silently and can be very difficult to debug.
def failed!(exception = false, propagate = true)
	@result = exception
	@status = :failed
	
	if exception
		if propagate
			raise exception
		elsif @finished.nil?
			# If no one has called wait, we log this as a warning:
			Console.logger.warn(self, "Task may have ended with unhandled exception.", exception)
		else
			Console.logger.debug(self, exception)
		end
	end
end

def failed?

def failed?
	@status == :failed
end

def finish!

Finish the current task, moving any children to the parent.
def finish!
	# Don't hold references to the fiber or block after the task has finished:
	@fiber = nil
	@block = nil # If some how we went directly from initialized to finished.
	
	# Attempt to remove this node from the task tree.
	consume
	
	# If this task was being used as a future, signal completion here:
	if @finished
		@finished.signal(self)
		@finished = nil
	end
end

def finished?

@returns [Boolean]
Whether we can remove this node from the reactor graph.
def finished?
	# If the block is nil and the fiber is nil, it means the task has finished execution. This becomes true after `finish!` is called.
	super && @block.nil? && @fiber.nil?
end

def initialize(parent = Task.current?, finished: nil, **options, &block)

@parameter parent [Task] the parent task.
@parameter reactor [Reactor] the reactor this task will run within.
Create a new task.
def initialize(parent = Task.current?, finished: nil, **options, &block)
	super(parent, **options)
	
	# These instance variables are critical to the state of the task.
	# In the initialized state, the @block should be set, but the @fiber should be nil.
	# In the running state, the @fiber should be set.
	# In a finished state, the @block should be nil, and the @fiber should be nil.
	@block = block
	@fiber = nil
	
	@status = :initialized
	@result = nil
	@finished = finished
end

def reactor

def reactor
	self.root
end

def run(*arguments)

Begin the execution of the task.
def run(*arguments)
	if @status == :initialized
		@status = :running
		
		schedule do
			@block.call(self, *arguments)
		end
	else
		raise RuntimeError, "Task already running!"
	end
end

def running?

@returns [Boolean]
Whether the task is running.
def running?
	@status == :running
end

def schedule(&block)

def schedule(&block)
	@fiber = Fiber.new(annotation: self.annotation) do
		set!
		
		begin
			completed!(yield)
			# Console.logger.debug(self) {"Task was completed with #{@children.size} children!"}
		rescue Stop
			stopped!
		rescue StandardError => error
			failed!(error, false)
		rescue Exception => exception
			failed!(exception, true)
		ensure
			# Console.logger.info(self) {"Task ensure $! = #{$!} with #{@children&.size.inspect} children!"}
			finish!
		end
	end
	
	self.root.resume(@fiber)
end

def set!

Set the current fiber's `:async_task` to this task.
def set!
	# This is actually fiber-local:
	Thread.current[:async_task] = self
end

def sleep(duration = nil)

Deprecated:
  • Prefer {Kernel#sleep} except when compatibility with `stable-v1` is required.
def sleep(duration = nil)
	super
end

def stop(later = false)

@parameter later [Boolean] Whether to stop the task later, or immediately.

If `later` is false, it means that `stop` has been invoked directly. When `later` is true, it means that `stop` is invoked by `stop_children` or some other indirect mechanism. In that case, if we encounter the "current" fiber, we can't stop it right away, as it's currently performing `#stop`. Stopping it immediately would interrupt the current stop traversal, so we need to schedule the stop to occur later.

Stop the task and all of its children.
def stop(later = false)
	if self.stopped?
		# If we already stopped this task... don't try to stop it again:
		return
	end
	
	# If the fiber is alive, we need to stop it:
	if @fiber&.alive?
		if self.current?
			# If the fiber is current, and later is `true`, we need to schedule the fiber to be stopped later, as it's currently invoking `stop`:
			if later
				# If the fiber is the current fiber and we want to stop it later, schedule it:
				Fiber.scheduler.push(Stop::Later.new(self))
			else
				# Otherwise, raise the exception directly:
				raise Stop, "Stopping current task!"
			end
		else
			# If the fiber is not curent, we can raise the exception directly:
			begin
				# There is a chance that this will stop the fiber that originally called stop. If that happens, the exception handling in `#stopped` will rescue the exception and re-raise it later.
				Fiber.scheduler.raise(@fiber, Stop)
			rescue FiberError
				# In some cases, this can cause a FiberError (it might be resumed already), so we schedule it to be stopped later:
				Fiber.scheduler.push(Stop::Later.new(self))
			end
		end
	else
		# We are not running, but children might be, so transition directly into stopped state:
		stop!
	end
end

def stop!

def stop!
	stopped!
	
	finish!
end

def stopped!

def stopped!
	# Console.logger.info(self, status:) {"Task #{self} was stopped with #{@children&.size.inspect} children!"}
	@status = :stopped
	
	stopped = false
	
	begin
		# We are bnot running, but children might be so we should stop them:
		stop_children(true)
	rescue Stop
		stopped = true
		# If we are stopping children, and one of them tries to stop the current task, we should ignore it. We will be stopped later.
		retry
	end
	
	if stopped
		raise Stop, "Stopping current task!"
	end
end

def stopped?

The task has been stopped
def stopped?
	@status == :stopped
end

def to_s

def to_s
	"\#<#{self.description} (#{@status})>"
end

def wait

@returns [Object] The final expression/result of the task's block.
@raises [RuntimeError] If the task's fiber is the current fiber.

Conceptually speaking, waiting on a task should return a result, and if it throws an exception, this is certainly an exceptional case that should represent a failure in your program, not an expected outcome. In other words, you should not design your programs to expect exceptions from `#wait` as a normal flow control, and prefer to catch known exceptions within the task itself and return a result that captures the intention of the failure, e.g. a `TimeoutError` might simply return `nil` or `false` to indicate that the operation did not generate a valid result (as a timeout was an expected outcome of the internal operation in this case).

Retrieve the current result of the task. Will cause the caller to wait until result is available. If the task resulted in an unhandled error (derived from `StandardError`), this will be raised. If the task was stopped, this will return `nil`.
def wait
	raise "Cannot wait on own fiber!" if Fiber.current.equal?(@fiber)
	
	# `finish!` will set both of these to nil before signaling the condition:
	if @block || @fiber
		@finished ||= Condition.new
		@finished.wait
	end
	
	if @status == :failed
		raise @result
	else
		return @result
	end
end

def with_timeout(duration, exception = TimeoutError, message = "execution expired", &block)

Execute the given block of code, raising the specified exception if it exceeds the given duration during a non-blocking operation.
def with_timeout(duration, exception = TimeoutError, message = "execution expired", &block)
	Fiber.scheduler.with_timeout(duration, exception, message, &block)
end

def yield

Yield back to the reactor and allow other fibers to execute.
def yield
	Fiber.scheduler.yield
end