Class: Async::Scheduler
Overview
Handles scheduling of fibers. Implements the fiber scheduler interface.
Direct Known Subclasses
Instance Attribute Summary
Attributes inherited from Node
#annotation, #children, #head, #parent, #tail
Class Method Summary collapse
-
.supported? ⇒ Boolean
Whether the fiber scheduler is supported.
Instance Method Summary collapse
- #address_resolve(hostname) ⇒ Object
-
#async(*arguments, **options, &block) ⇒ Object
deprecated
Deprecated.
With no replacement.
-
#block(blocker, timeout) ⇒ Object
Invoked when a fiber tries to perform a blocking operation which cannot continue.
- #close ⇒ Object
- #closed? ⇒ Boolean
- #fiber ⇒ Object
-
#initialize(parent = nil, selector: nil) ⇒ Scheduler
constructor
A new instance of Scheduler.
-
#interrupt ⇒ Object
Interrupt the event loop and cause it to exit.
- #io_read(io, buffer, length, offset = 0) ⇒ Object
- #io_wait(io, events, timeout = nil) ⇒ Object
- #io_write(io, buffer, length, offset = 0) ⇒ Object
- #kernel_sleep(duration = nil) ⇒ Object
-
#process_wait(pid, flags) ⇒ Object
Wait for the specified process ID to exit.
-
#push(fiber) ⇒ Object
Schedule a fiber (or equivalent object) to be resumed on the next loop through the reactor.
- #raise(*arguments) ⇒ Object
- #resume(fiber, *arguments) ⇒ Object
-
#run ⇒ Object
Run the reactor until all tasks are finished.
-
#run_once(timeout = nil) ⇒ Object
Run one iteration of the event loop.
- #scheduler_close ⇒ Object
- #timeout_after(duration, exception, message, &block) ⇒ Object
- #to_s ⇒ Object
-
#transfer ⇒ Object
Transfer from the calling fiber to the event loop.
- #unblock(blocker, fiber) ⇒ Object
-
#with_timeout(duration, exception = TimeoutError, message = "execution expired", &block) ⇒ Object
Invoke the block, but after the specified timeout, raise TimeoutError in any currenly blocking operation.
-
#yield ⇒ Object
Yield the current fiber and resume it on the next iteration of the event loop.
Methods inherited from Node
#The parent node.=, #annotate, #backtrace, #children?, #consume, #description, #finished?, #print_hierarchy, #root, #stop, #stopped?, #terminate, #transient?, #traverse
Constructor Details
#initialize(parent = nil, selector: nil) ⇒ Scheduler
Returns a new instance of Scheduler.
26 27 28 29 30 31 32 33 34 35 |
# File 'lib/async/scheduler.rb', line 26 def initialize(parent = nil, selector: nil) super(parent) @selector = selector || ::IO::Event::Selector.new(Fiber.current) @interrupted = false @blocked = 0 @timers = ::Timers::Group.new end |
Class Method Details
.supported? ⇒ Boolean
Whether the fiber scheduler is supported.
22 23 24 |
# File 'lib/async/scheduler.rb', line 22 def self.supported? true end |
Instance Method Details
#address_resolve(hostname) ⇒ Object
144 145 146 |
# File 'lib/async/scheduler.rb', line 144 def address_resolve(hostname) ::Resolv.getaddresses(hostname) end |
#async(*arguments, **options, &block) ⇒ Object
With no replacement.
Start an asynchronous task within the specified reactor. The task will be executed until the first blocking call, at which point it will yield and and this method will return.
This is the main entry point for scheduling asynchronus tasks.
252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 |
# File 'lib/async/scheduler.rb', line 252 def async(*arguments, **, &block) task = Task.new(Task.current? || self, **, &block) # I want to take a moment to explain the logic of this. # 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. task.run(*arguments) # Console.logger.debug "Initial execution of task #{fiber} complete (#{result} -> #{fiber.alive?})..." return task end |
#block(blocker, timeout) ⇒ Object
Invoked when a fiber tries to perform a blocking operation which cannot continue. A corresponding call #unblock must be performed to allow this fiber to continue.
103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 |
# File 'lib/async/scheduler.rb', line 103 def block(blocker, timeout) # $stderr.puts "block(#{blocker}, #{Fiber.current}, #{timeout})" fiber = Fiber.current if timeout timer = @timers.after(timeout) do if fiber.alive? fiber.transfer(false) end end end begin @blocked += 1 @selector.transfer ensure @blocked -= 1 end ensure timer&.cancel end |
#close ⇒ Object
44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 |
# File 'lib/async/scheduler.rb', line 44 def close # This is a critical step. Because tasks could be stored as instance variables, and since the reactor is (probably) going out of scope, we need to ensure they are stopped. Otherwise, the tasks will belong to a reactor that will never run again and are not stopped. self.terminate Kernel::raise "Closing scheduler with blocked operations!" if @blocked > 0 # We depend on GVL for consistency: # @guard.synchronize do @selector&.close @selector = nil # end consume end |
#closed? ⇒ Boolean
63 64 65 |
# File 'lib/async/scheduler.rb', line 63 def closed? @selector.nil? end |
#fiber ⇒ Object
268 269 270 |
# File 'lib/async/scheduler.rb', line 268 def fiber(...) return async(...).fiber end |
#interrupt ⇒ Object
Interrupt the event loop and cause it to exit.
72 73 74 75 |
# File 'lib/async/scheduler.rb', line 72 def interrupt @interrupted = true @selector.wakeup end |
#io_read(io, buffer, length, offset = 0) ⇒ Object
170 171 172 |
# File 'lib/async/scheduler.rb', line 170 def io_read(io, buffer, length, offset = 0) @selector.io_read(Fiber.current, io, buffer, length, offset) end |
#io_wait(io, events, timeout = nil) ⇒ Object
149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 |
# File 'lib/async/scheduler.rb', line 149 def io_wait(io, events, timeout = nil) fiber = Fiber.current if timeout timer = @timers.after(timeout) do fiber.raise(TimeoutError) end end # Console.logger.info(self, "-> io_wait", fiber, io, events) events = @selector.io_wait(fiber, io, events) # Console.logger.info(self, "<- io_wait", fiber, io, events) return events rescue TimeoutError return false ensure timer&.cancel end |
#io_write(io, buffer, length, offset = 0) ⇒ Object
174 175 176 |
# File 'lib/async/scheduler.rb', line 174 def io_write(io, buffer, length, offset = 0) @selector.io_write(Fiber.current, io, buffer, length, offset) end |
#kernel_sleep(duration = nil) ⇒ Object
135 136 137 138 139 140 141 |
# File 'lib/async/scheduler.rb', line 135 def kernel_sleep(duration = nil) if duration self.block(nil, duration) else self.transfer end end |
#process_wait(pid, flags) ⇒ Object
Wait for the specified process ID to exit.
184 185 186 |
# File 'lib/async/scheduler.rb', line 184 def process_wait(pid, flags) return @selector.process_wait(Fiber.current, pid, flags) end |
#push(fiber) ⇒ Object
Schedule a fiber (or equivalent object) to be resumed on the next loop through the reactor.
89 90 91 |
# File 'lib/async/scheduler.rb', line 89 def push(fiber) @selector.push(fiber) end |
#raise(*arguments) ⇒ Object
93 94 95 |
# File 'lib/async/scheduler.rb', line 93 def raise(*arguments) @selector.raise(*arguments) end |
#resume(fiber, *arguments) ⇒ Object
97 98 99 |
# File 'lib/async/scheduler.rb', line 97 def resume(fiber, *arguments) @selector.resume(fiber, *arguments) end |
#run ⇒ Object
Run the reactor until all tasks are finished. Proxies arguments to #async immediately before entering the loop, if a block is provided.
225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 |
# File 'lib/async/scheduler.rb', line 225 def run(...) Kernel::raise RuntimeError, 'Reactor has been closed' if @selector.nil? initial_task = self.async(...) if block_given? @interrupted = false while self.run_once if @interrupted break end end return initial_task ensure Console.logger.debug(self) {"Exiting run-loop because #{$! ? $! : 'finished'}."} end |
#run_once(timeout = nil) ⇒ Object
Run one iteration of the event loop.
191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 |
# File 'lib/async/scheduler.rb', line 191 def run_once(timeout = nil) Kernel::raise "Running scheduler on non-blocking fiber!" unless Fiber.blocking? # If we are finished, we stop the task tree and exit: if self.finished? return false end interval = @timers.wait_interval # If there is no interval to wait (thus no timers), and no tasks, we could be done: if interval.nil? # Allow the user to specify a maximum interval if we would otherwise be sleeping indefinitely: interval = timeout elsif interval < 0 # We have timers ready to fire, don't sleep in the selctor: interval = 0 elsif timeout and interval > timeout interval = timeout end begin @selector.select(interval) rescue Errno::EINTR # Ignore. end @timers.fire # The reactor still has work to do: return true end |
#scheduler_close ⇒ Object
37 38 39 40 41 |
# File 'lib/async/scheduler.rb', line 37 def scheduler_close self.run ensure self.close end |
#timeout_after(duration, exception, message, &block) ⇒ Object
288 289 290 291 292 |
# File 'lib/async/scheduler.rb', line 288 def timeout_after(duration, exception, , &block) with_timeout(duration, exception, ) do |timer| yield duration end end |
#to_s ⇒ Object
67 68 69 |
# File 'lib/async/scheduler.rb', line 67 def to_s "\#<#{self.description} #{@children&.size || 0} children (#{stopped? ? 'stopped' : 'running'})>" end |
#transfer ⇒ Object
Transfer from the calling fiber to the event loop.
78 79 80 |
# File 'lib/async/scheduler.rb', line 78 def transfer @selector.transfer end |
#unblock(blocker, fiber) ⇒ Object
126 127 128 129 130 131 132 |
# File 'lib/async/scheduler.rb', line 126 def unblock(blocker, fiber) # $stderr.puts "unblock(#{blocker}, #{fiber})" # This operation is protected by the GVL: @selector.push(fiber) @selector.wakeup end |
#with_timeout(duration, exception = TimeoutError, message = "execution expired", &block) ⇒ Object
Invoke the block, but after the specified timeout, raise TimeoutError in any currenly blocking operation. If the block runs to completion before the timeout occurs or there are no non-blocking operations after the timeout expires, the code will complete without any exception.
274 275 276 277 278 279 280 281 282 283 284 285 286 |
# File 'lib/async/scheduler.rb', line 274 def with_timeout(duration, exception = TimeoutError, = "execution expired", &block) fiber = Fiber.current timer = @timers.after(duration) do if fiber.alive? fiber.raise(exception, ) end end yield timer ensure timer.cancel if timer end |
#yield ⇒ Object
Yield the current fiber and resume it on the next iteration of the event loop.
83 84 85 |
# File 'lib/async/scheduler.rb', line 83 def yield @selector.yield end |