class Async::Task

def self.current
	Fiber.current.async_task or raise RuntimeError, "No async task available!"
end

def self.current?
	Fiber.current.async_task
end

def self.run(scheduler, *arguments, **options, &block)
	self.new(scheduler, **options, &block).tap do |task|
		task.run(*arguments)
	end
end

def self.yield
	Fiber.scheduler.transfer
end

def alive?
	@fiber&.alive?
end

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

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

def async(*arguments, **options, &block)
	raise FinishedError if self.finished?
	
	task = Task.new(self, **options, &block)
	
	# 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.
	#
	# There are different strategies (greedy vs non-greedy). We are currently using a greedy strategy.
	task.run(*arguments)
	
	return task
end

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

def completed!(result)
	@result = result
	@status = :completed
end

def completed?
	@status == :completed
end

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

def defer_stop
	# Tri-state variable for controlling stop:
	# - nil: defer_stop has not been called.
	# - false: defer_stop has been called and we are not stopping.
	# - true: defer_stop has been called and we will stop when exiting the block.
	if @defer_stop.nil?
		begin
			# If we are not deferring stop already, we can defer it now:
			@defer_stop = false
			
			yield
		rescue Stop
			# If we are exiting due to a stop, we shouldn't try to invoke stop again:
			@defer_stop = nil
			raise
		ensure
			defer_stop = @defer_stop
			
			# We need to ensure the state is reset before we exit the block:
			@defer_stop = nil
			
			# If we were asked to stop, we should do so now:
			if defer_stop
				raise Stop, "Stopping current task (was deferred)!"
			end
		end
	else
		# If we are deferring stop already, entering it again is a no-op.
		yield
	end
end

def failed!(exception = false)
	@result = exception
	@status = :failed
end

def failed?
	@status == :failed
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 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)
	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
	
	@defer_stop = nil
end

def reactor
	self.root
end

def run(*arguments)
	if @status == :initialized
		@status = :running
		
		schedule do
			@block.call(self, *arguments)
		rescue => error
			# I'm not completely happy with this overhead, but the alternative is to not log anything which makes debugging extremely difficult. Maybe we can introduce a debug wrapper which adds extra logging.
			if @finished.nil?
				warn(self, "Task may have ended with unhandled exception.", exception: error)
			end
			
			raise
		end
	else
		raise RuntimeError, "Task already running!"
	end
end

def running?
	@status == :running
end

def schedule(&block)
	@fiber = Fiber.new(annotation: self.annotation) do
		begin
			completed!(yield)
		rescue Stop
			stopped!
		rescue StandardError => error
			failed!(error)
		rescue Exception => exception
			failed!(exception)
			
			# This is a critical failure, we should stop the reactor:
			raise
		ensure
			# Console.info(self) {"Task ensure $! = #{$!} with #{@children&.size.inspect} children!"}
			finish!
		end
	end
	
	@fiber.async_task = self
	
	self.root.resume(@fiber)
end

def sleep(duration = nil)
	super
end

def stop(later = false)
	if self.stopped?
		# If the task is already stopped, a `stop` state transition re-enters the same state which is a no-op. However, we will also attempt to stop any running children too. This can happen if the children did not stop correctly the first time around. Doing this should probably be considered a bug, but it's better to be safe than sorry.
		return stopped!
	end
	
	# If the fiber is alive, we need to stop it:
	if @fiber&.alive?
		# As the task is now exiting, we want to ensure the event loop continues to execute until the task finishes.
		self.transient = false
		
		# If we are deferring stop...
		if @defer_stop == false
			# Don't stop now... but update the state so we know we need to stop later.
			@defer_stop = true
			return false
		end
		
		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 => error
				# 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!
	stopped!
	
	finish!
end

def stop_deferred?
	@defer_stop
end

def stopped!
	# Console.info(self, status:) {"Task #{self} was stopped with #{@children&.size.inspect} children!"}
	@status = :stopped
	
	stopped = false
	
	begin
		# We are not 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?
	@status == :stopped
end

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

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 warn(...)
	Console.warn(...)
end

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

def yield
	Fiber.scheduler.yield
end