class Task

deprecated

With no replacement.

def self.yield
	Fiber.scheduler.transfer
end

def yield
	Fiber.scheduler.yield
end

parameter　reactor　Reactor

the reactor this task will run within.

parameter　parent　Task

the parent 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

deprecated

Prefer Kernel#sleep except when compatibility with stable-v1 is required.

def sleep(duration = nil)
	super
end

def with_timeout(duration, exception = TimeoutError, message = "execution expired", &block)
	Fiber.scheduler.with_timeout(duration, exception, message, &block)
end

def alive?
	@fiber&.alive?
end

returns　Boolean

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

returns　Boolean

def running?
	@status == :running
end

def stopped?
	@status == :stopped
end

def completed?
	@status == :completed
end

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

def async(*arguments, **options, &block)
	raise "Cannot create child task within a task that has finished execution!" if self.finished?
	
	task = Task.new(self, **options, &block)
	
	task.run(*arguments)
	
	return task
end

raises　RuntimeError

If the task's fiber is the current fiber.

returns　Object

The final expression/result of the task's block.

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 @result.is_a?(Exception)
		raise @result
	else
		return @result
	end
end

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

returns　Task

def self.current
	Thread.current[:async_task] or raise RuntimeError, "No async task available!"
end

returns　Task | Nil

def self.current?
	Thread.current[:async_task]
end

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 completed!(result)
	@result = result
	@status = :completed
end

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 set!
	# This is actually fiber-local:
	Thread.current[:async_task] = self
end