Class: Async::Task

Inherits:
Node
  • Object
show all
Defined in:
lib/async/task.rb

Defined Under Namespace

Classes: FinishedError

Instance Attribute Summary collapse

Attributes inherited from Node

#A useful identifier for the current node., #Optional list of children., #children, #head, #parent, #tail

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Node

#The parent node.=, #children?, #consume, #description, #print_hierarchy, #root, #terminate, #transient=, #transient?, #traverse

Constructor Details

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

Create a new task.



63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
 
# File 'lib/async/task.rb', line 63

def initialize(parent = Task.current?, finished: nil, **options, &block)
  # 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, and @block should be nil.
  # In a finished state, the @block should be nil, and the @fiber should be nil.
  @block = block
  @fiber = nil
  
  @promise = Promise.new
  
  # Handle finished: parameter for backward compatibility:
  case finished
  when false
    # `finished: false` suppresses warnings for expected task failures:
    @promise.suppress_warnings!
  when nil
    # `finished: nil` is the default, no special handling:
  else
    # All other `finished:` values are deprecated:
    warn("finished: argument with non-false value is deprecated and will be removed.", uplevel: 1, category: :deprecated) if $VERBOSE
  end
  
  @defer_stop = nil
  
  # Call this after all state is initialized, as it may call `add_child` which will set the parent and make it visible to the scheduler.
  super(parent, **options)
end

Instance Attribute Details

#fiber ⇒ Object (readonly)

Returns the value of attribute fiber.



146
147
148
 
# File 'lib/async/task.rb', line 146

def fiber
  @fiber
end

#The fiber which is being used for the execution of this task.(fiberwhichisbeingused) ⇒ Object (readonly) 



146
 
# File 'lib/async/task.rb', line 146

attr :fiber

Class Method Details

.current ⇒ Object

Lookup the Async::Task for the current fiber. Raise RuntimeError if none is available. @raises If task was not set! for the current fiber.



380
381
382
 
# File 'lib/async/task.rb', line 380

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

.current? ⇒ Boolean

Check if there is a task defined for the current fiber.



386
387
388
 
# File 'lib/async/task.rb', line 386

def self.current?
  Fiber.current.async_task
end

.run(scheduler, *arguments, **options, &block) ⇒ Object

Run the given block of code in a task, asynchronously, in the given scheduler.



54
55
56
57
58
 
# File 'lib/async/task.rb', line 54

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

.yield ⇒ Object

Deprecated.

With no replacement.



47
48
49
50
51
 
# File 'lib/async/task.rb', line 47

def self.yield
  warn("`Async::Task.yield` is deprecated with no replacement.", uplevel: 1, category: :deprecated) if $VERBOSE
  
  Fiber.scheduler.transfer
end

Instance Method Details

#alive? ⇒ Boolean 



149
150
151
 
# File 'lib/async/task.rb', line 149

def alive?
  @fiber&.alive?
end

#annotate(annotation, &block) ⇒ Object

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.



106
107
108
109
110
111
112
 
# File 'lib/async/task.rb', line 106

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

#annotation ⇒ Object 



115
116
117
118
119
120
121
 
# File 'lib/async/task.rb', line 115

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

#async(*arguments, **options, &block) ⇒ Object

Run an asynchronous task as a child of the current task.

Raises:



230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'lib/async/task.rb', line 230

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

#backtrace(*arguments) ⇒ Object 



97
98
99
 
# File 'lib/async/task.rb', line 97

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

#complete? ⇒ Boolean

Alias for #completed?.



181
182
183
 
# File 'lib/async/task.rb', line 181

def complete?
  self.completed?
end

#completed? ⇒ Boolean 



176
177
178
 
# File 'lib/async/task.rb', line 176

def completed?
  @promise.completed?
end

#current? ⇒ Boolean 



391
392
393
 
# File 'lib/async/task.rb', line 391

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

#defer_stop ⇒ Object

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.



340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
 
# File 'lib/async/task.rb', line 340

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)!", cause: defer_stop
      end
    end
  else
    # If we are deferring stop already, entering it again is a no-op.
    yield
  end
end

#failed? ⇒ Boolean 



166
167
168
 
# File 'lib/async/task.rb', line 166

def failed?
  @promise.failed?
end

#finished? ⇒ Boolean

Whether we can remove this node from the reactor graph.



155
156
157
158
 
# File 'lib/async/task.rb', line 155

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

#reactor ⇒ Object 



92
93
94
 
# File 'lib/async/task.rb', line 92

def reactor
  self.root
end

#result ⇒ Object

Access the result of the task without waiting. May be nil if the task is not completed. Does not raise exceptions.



267
268
269
270
271
272
273
274
275
276
 
# File 'lib/async/task.rb', line 267

def result
  value = @promise.value
  
  # For backward compatibility, return nil for stopped tasks:
  if @promise.cancelled?
    nil
  else
    value
  end
end

#run(*arguments) ⇒ Object

Begin the execution of the task.



202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
 
# File 'lib/async/task.rb', line 202

def run(*arguments)
  # Move from initialized to running by clearing @block
  if block = @block
    @block = nil
    
    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.
      unless @promise.waiting?
        warn(self, "Task may have ended with unhandled exception.", exception: error)
      end
      
      raise
    end
  else
    raise RuntimeError, "Task already running!"
  end
end

#running? ⇒ Boolean 



161
162
163
 
# File 'lib/async/task.rb', line 161

def running?
  self.alive?
end

#sleep(duration = nil) ⇒ Object

Deprecated.

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



129
130
131
132
133
 
# File 'lib/async/task.rb', line 129

def sleep(duration = nil)
  Kernel.warn("`Async::Task#sleep` is deprecated, use `Kernel#sleep` instead.", uplevel: 1, category: :deprecated) if $VERBOSE
  
  super
end

#status ⇒ Object 



186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/async/task.rb', line 186

def status
  case @promise.resolved
  when :cancelled
    :stopped
  when :failed
    :failed
  when :completed
    :completed
  when nil
    self.running? ? :running : :initialized
  end
end

#stop(later = false, cause: $!) ⇒ Object

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.



284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
 
# File 'lib/async/task.rb', line 284

def stop(later = false, cause: $!)
  # If no cause is given, we generate one from the current call stack:
  unless cause
    cause = Stop::Cause.for("Stopping task!")
  end
  
  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 = cause
      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, cause))
      else
        # Otherwise, raise the exception directly:
        raise Stop, "Stopping current task!", cause: cause
      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, cause: cause)
      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, cause))
      end
    end
  else
    # We are not running, but children might be, so transition directly into stopped state:
    stop!
  end
end

#stop_deferred? ⇒ Boolean 



373
374
375
 
# File 'lib/async/task.rb', line 373

def stop_deferred?
  !!@defer_stop
end

#stopped? ⇒ Boolean 



171
172
173
 
# File 'lib/async/task.rb', line 171

def stopped?
  @promise.cancelled?
end

#The status of the execution of the task, one of `:initialized`, `:running`, `:complete`, `:stopped` or `:failed`.=(statusoftheexecutionofthetask, oneof`: initialized`, `: running`, `: complete`, `: stopped`) ⇒ Object 



186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/async/task.rb', line 186

def status
  case @promise.resolved
  when :cancelled
    :stopped
  when :failed
    :failed
  when :completed
    :completed
  when nil
    self.running? ? :running : :initialized
  end
end

#to_s ⇒ Object 



124
125
126
 
# File 'lib/async/task.rb', line 124

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

#wait ⇒ Object

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



254
255
256
257
258
259
260
261
262
263
264
 
# File 'lib/async/task.rb', line 254

def wait
  raise "Cannot wait on own fiber!" if Fiber.current.equal?(@fiber)
  
  # Wait for the task to complete - Promise handles all the complexity:
  begin
    @promise.wait
  rescue Promise::Cancel
    # For backward compatibility, stopped tasks return nil
    return nil
  end
end

#with_timeout(duration, exception = TimeoutError, message = "execution expired", &block) ⇒ Object

Execute the given block of code, raising the specified exception if it exceeds the given duration during a non-blocking operation.



136
137
138
 
# File 'lib/async/task.rb', line 136

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

#yield ⇒ Object

Yield back to the reactor and allow other fibers to execute.



141
142
143
 
# File 'lib/async/task.rb', line 141

def yield
  Fiber.scheduler.yield
end