class Async::Task
@public Since ‘stable-v1`.
def self.current
@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?
Check if there is a task defined for the current fiber.
def self.current? Thread.current[:async_task] end
def self.yield
- With no replacement.
def self.yield Fiber.scheduler.transfer end
def alive?
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)
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)
def completed!(result) @result = result @status = :completed end
def completed?
def completed? @status == :completed end
def current?
def current? Fiber.current.equal?(@fiber) end
def failed!(exception = false, propagate = true)
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!
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?
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 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)
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?
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!
def set! # This is actually fiber-local: Thread.current[:async_task] = self end
def sleep(duration = nil)
- Prefer {Kernel#sleep} except when compatibility with `stable-v1` is required.
def sleep(duration = nil) super end
def stop(later = false)
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?
def stopped? @status == :stopped end
def to_s
def to_s "\#<#{self.description} (#{@status})>" end
def wait
@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)
def with_timeout(duration, exception = TimeoutError, message = "execution expired", &block) Fiber.scheduler.with_timeout(duration, exception, message, &block) end
def yield
def yield Fiber.scheduler.yield end