class Task
A sequence of instructions, defined by a block, which is executed sequentially and managed by the scheduler. A task can be in one of the following states: initialized
, running
, completed
, failed
, cancelled
or stopped
.
Example
require 'async'
# Create an asynchronous task that sleeps for 1 second:
Async do |task|
sleep(1)
end
Signature
- public
Since Async v1.
Nested
Definitions
def self.yield
- deprecated
Signature
- deprecated
With no replacement.
Implementation
def self.yield
Fiber.scheduler.transfer
end
def yield
Yield back to the reactor and allow other fibers to execute.
Implementation
def yield
Fiber.scheduler.yield
end
def self.run(scheduler, *arguments, **options, &block)
Run the given block of code in a task, asynchronously, in the given scheduler.
Implementation
def self.run(scheduler, *arguments, **options, &block)
self.new(scheduler, **options, &block).tap do |task|
task.run(*arguments)
end
end
def run(*arguments)
Begin the execution of the task.
Signature
-
raises
RuntimeError
If the task is already running.
Implementation
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 initialize(parent = Task.current?, finished: nil, **options, &block)
Create a new task.
Signature
-
parameter
reactor
Reactor
the reactor this task will run within.
-
parameter
parent
Task
the parent task.
Implementation
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
Signature
-
returns
Scheduler
The scheduler for this task.
Implementation
def reactor
self.root
end
def backtrace(*arguments)
Signature
-
returns
Array(Thread::Backtrace::Location) | Nil
The backtrace of the task, if available.
Implementation
def backtrace(*arguments)
@fiber&.backtrace(*arguments)
end
def annotate(annotation, &block)
Annotate the task with a description.
This will internally try to annotate the fiber if it is running, otherwise it will annotate the task itself.
Signature
-
parameter
annotation
String
The description to annotate the task with.
Implementation
def annotate(annotation, &block)
if @fiber
@fiber.annotate(annotation, &block)
else
super
end
end
def annotation
Signature
-
returns
Object
The annotation of the task.
Implementation
def annotation
if @fiber
@fiber.annotation
else
super
end
end
def to_s
Signature
-
returns
String
A description of the task and it's current status.
Implementation
def to_s
"\#<#{self.description} (#{@status})>"
end
def sleep(duration = nil)
- deprecated
Signature
- deprecated
Prefer
Kernel#sleep
except when compatibility withstable-v1
is required.
Implementation
def sleep(duration = nil)
super
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.
Implementation
def with_timeout(duration, exception = TimeoutError, message = "execution expired", &block)
Fiber.scheduler.with_timeout(duration, exception, message, &block)
end
attr :fiber
Signature
-
attribute
Fiber
The fiber which is being used for the execution of this task.
def alive?
Signature
-
returns
Boolean
Whether the internal fiber is alive, i.e. it is actively executing.
Implementation
def alive?
@fiber&.alive?
end
def finished?
Whether we can remove this node from the reactor graph.
Signature
-
returns
Boolean
Implementation
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 running?
Signature
-
returns
Boolean
Whether the task is running.
Implementation
def running?
@status == :running
end
def failed?
Signature
-
returns
Boolean
Whether the task failed with an exception.
Implementation
def failed?
@status == :failed
end
def stopped?
Signature
-
returns
Boolean
Whether the task has been stopped.
Implementation
def stopped?
@status == :stopped
end
def completed?
Signature
-
returns
Boolean
Whether the task has completed execution and generated a result.
Implementation
def completed?
@status == :completed
end
attr :status
Signature
-
attribute
Symbol
The status of the execution of the task, one of
:initialized
,:running
,:complete
,:stopped
or:failed
.
def async(*arguments, **options, &block)
- public
- asynchronous
Run an asynchronous task as a child of the current task.
Signature
- public
Since Async v1.
- asynchronous
May context switch immediately to the new task.
-
yields
{|task| ...}
in the context of the new task.
-
raises
FinishedError
If the task has already finished.
-
returns
Task
The child task.
Implementation
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 wait
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
.
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).
Signature
-
raises
RuntimeError
If the task's fiber is the current fiber.
-
returns
Object
The final expression/result of the task's block.
Implementation
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
attr :result
Access the result of the task without waiting. May be nil if the task is not completed. Does not raise exceptions.
def stop(later = false)
Stop the task and all of its children.
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.
Signature
-
parameter
later
Boolean
Whether to stop the task later, or immediately.
Implementation
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 defer_stop
- public
Defer the handling of stop. During the execution of the given block, if a stop is requested, it will be deferred until the block exits. This is useful for ensuring graceful shutdown of servers and other long-running tasks. You should wrap the response handling code in a defer_stop block to ensure that the task is stopped when the response is complete but not before.
You can nest calls to defer_stop, but the stop will only be deferred until the outermost block exits.
If stop is invoked a second time, it will be immediately executed.
Signature
-
yields
{}
The block of code to execute.
- public
Since Async v1.
Implementation
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 stop_deferred?
Signature
-
returns
Boolean
Whether stop has been deferred.
Implementation
def stop_deferred?
@defer_stop
end
def self.current
Lookup the class Async::Task
for the current fiber. Raise RuntimeError
if none is available.
Signature
-
returns
Task
Implementation
def self.current
Fiber.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.
Signature
-
returns
Interface(:async) | Nil
Implementation
def self.current?
Fiber.current.async_task
end
def current?
Signature
-
returns
Boolean
Whether this task is the currently executing task.
Implementation
def current?
Fiber.current.equal?(@fiber)
end
def finish!
Finish the current task, moving any children to the parent.
Implementation
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)
State transition into the completed state.
Implementation
def completed!(result)
@result = result
@status = :completed
end
def failed!(exception = false)
State transition into the failed state.
Implementation
def failed!(exception = false)
@result = exception
@status = :failed
end