Class: Async::Reactor
- Extended by:
- Forwardable
- Defined in:
- lib/async/reactor.rb
Overview
An asynchronous, cooperatively scheduled event reactor.
Instance Attribute Summary collapse
-
#scheduler ⇒ Object
readonly
Returns the value of attribute scheduler.
Attributes inherited from Node
#annotation, #children, #head, #parent, #tail
Class Method Summary collapse
-
.run(*arguments, **options, &block) ⇒ Object
The preferred method to invoke asynchronous behavior at the top level.
- .selector ⇒ Object
Instance Method Summary collapse
-
#<<(fiber) ⇒ Object
Schedule a fiber (or equivalent object) to be resumed on the next loop through the reactor.
-
#async(*arguments, **options) {|Task| ... } ⇒ Task
Start an asynchronous task within the specified reactor.
- #block(blocker, timeout) ⇒ Object
-
#close ⇒ void
Stop each of the children tasks and close the selector.
-
#closed? ⇒ Boolean
Check if the selector has been closed.
- #fiber(&block) ⇒ Object
- #finished? ⇒ Boolean
-
#initialize(parent = nil, selector: self.class.selector, logger: nil) ⇒ Reactor
constructor
A new instance of Reactor.
-
#interrupt ⇒ Object
Interrupt the reactor at the earliest convenience.
- #logger ⇒ Object
- #register(io, interest, value = Fiber.current) ⇒ Object
-
#run(*arguments, **options, &block) ⇒ Object
Run the reactor until all tasks are finished.
-
#run_once(timeout = nil) ⇒ Boolean
Run one iteration of the event loop.
-
#sleep(duration) ⇒ Object
Put the calling fiber to sleep for a given ammount of time.
- #stop(later = true) ⇒ Object
- #stopped? ⇒ Boolean
- #to_s ⇒ Object
- #unblock(blocker, fiber) ⇒ Object
-
#with_timeout(timeout, exception = TimeoutError) ⇒ Object
Invoke the block, but after the specified timeout, raise TimeoutError in any currenly blocking operation.
-
#yield(fiber = Fiber.current) ⇒ Object
Yield the current fiber and resume it on the next iteration of the event loop.
Methods inherited from Node
#annotate, #backtrace, #children?, #consume, #description, #print_hierarchy, #transient?, #traverse
Constructor Details
#initialize(parent = nil, selector: self.class.selector, logger: nil) ⇒ Reactor
Returns a new instance of Reactor.
76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 |
# File 'lib/async/reactor.rb', line 76 def initialize(parent = nil, selector: self.class.selector, logger: nil) super(parent) @selector = selector @timers = Timers::Group.new @logger = logger @ready = [] @running = [] if Scheduler.supported? @scheduler = Scheduler.new(self) else @scheduler = nil end @interrupted = false @guard = Mutex.new @blocked = 0 @unblocked = [] end |
Instance Attribute Details
#scheduler ⇒ Object (readonly)
Returns the value of attribute scheduler.
98 99 100 |
# File 'lib/async/reactor.rb', line 98 def scheduler @scheduler end |
Class Method Details
.run(*arguments, **options, &block) ⇒ Object
The preferred method to invoke asynchronous behavior at the top level.
-
When invoked within an existing reactor task, it will run the given block
asynchronously. Will return the task once it has been scheduled.
-
When invoked at the top level, will create and run a reactor, and invoke
the block as an asynchronous task. Will block until the reactor finishes running.
48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 |
# File 'lib/async/reactor.rb', line 48 def self.run(*arguments, **, &block) if current = Task.current? reactor = current.reactor return reactor.async(*arguments, **, &block) else reactor = self.new begin return reactor.run(*arguments, **, &block) ensure reactor.close end end end |
.selector ⇒ Object
64 65 66 67 68 69 70 71 72 73 74 |
# File 'lib/async/reactor.rb', line 64 def self.selector if backend = ENV['ASYNC_BACKEND']&.to_sym if NIO::Selector.backends.include?(backend) return NIO::Selector.new(backend) else warn "Could not find ASYNC_BACKEND=#{backend}!" end end return NIO::Selector.new end |
Instance Method Details
#<<(fiber) ⇒ Object
Schedule a fiber (or equivalent object) to be resumed on the next loop through the reactor.
193 194 195 |
# File 'lib/async/reactor.rb', line 193 def << fiber @ready << fiber end |
#async(*arguments, **options) {|Task| ... } ⇒ Task
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.
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 |
# File 'lib/async/reactor.rb', line 158 def async(*arguments, **, &block) task = Task.new(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) # logger.debug "Initial execution of task #{fiber} complete (#{result} -> #{fiber.alive?})..." return task end |
#block(blocker, timeout) ⇒ Object
101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 |
# File 'lib/async/reactor.rb', line 101 def block(blocker, timeout) fiber = Fiber.current if timeout timer = @timers.after(timeout) do if fiber.alive? fiber.resume(false) end end end begin @blocked += 1 Task.yield ensure @blocked -= 1 end ensure timer&.cancel end |
#close ⇒ void
This method returns an undefined value.
Stop each of the children tasks and close the selector.
311 312 313 314 315 316 317 |
# File 'lib/async/reactor.rb', line 311 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.stop(false) @selector.close @selector = nil end |
#closed? ⇒ Boolean
Check if the selector has been closed.
321 322 323 |
# File 'lib/async/reactor.rb', line 321 def closed? @selector.nil? end |
#fiber(&block) ⇒ Object
130 131 132 133 134 135 136 |
# File 'lib/async/reactor.rb', line 130 def fiber(&block) if @scheduler Fiber.new(blocking: false, &block) else Fiber.new(&block) end end |
#finished? ⇒ Boolean
204 205 206 207 |
# File 'lib/async/reactor.rb', line 204 def finished? # TODO I'm not sure if checking `@running.empty?` is really required. super && @ready.empty? && @running.empty? && @blocked.zero? end |
#interrupt ⇒ Object
Interrupt the reactor at the earliest convenience. Can be called from a different thread safely.
182 183 184 185 186 187 188 189 |
# File 'lib/async/reactor.rb', line 182 def interrupt @guard.synchronize do unless @interrupted @interrupted = true @selector.wakeup end end end |
#logger ⇒ Object
138 139 140 |
# File 'lib/async/reactor.rb', line 138 def logger @logger || Console.logger end |
#register(io, interest, value = Fiber.current) ⇒ Object
174 175 176 177 178 179 |
# File 'lib/async/reactor.rb', line 174 def register(io, interest, value = Fiber.current) monitor = @selector.register(io, interest) monitor.value = value return monitor end |
#run(*arguments, **options, &block) ⇒ Object
Run the reactor until all tasks are finished. Proxies arguments to #async immediately before entering the loop, if a block is provided.
284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 |
# File 'lib/async/reactor.rb', line 284 def run(*arguments, **, &block) raise RuntimeError, 'Reactor has been closed' if @selector.nil? @scheduler&.set! initial_task = self.async(*arguments, **, &block) if block_given? while self.run_once # Round and round we go! end return initial_task ensure @scheduler&.clear! logger.debug(self) {"Exiting run-loop because #{$! ? $! : 'finished'}."} end |
#run_once(timeout = nil) ⇒ Boolean
Run one iteration of the event loop.
212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 |
# File 'lib/async/reactor.rb', line 212 def run_once(timeout = nil) # logger.debug(self) {"@ready = #{@ready} @running = #{@running}"} if @ready.any? # running used to correctly answer on `finished?`, and to reuse Array object. @running, @ready = @ready, @running @running.each do |fiber| fiber.resume if fiber.alive? end @running.clear end if @unblocked.any? unblocked = Array.new @guard.synchronize do unblocked, @unblocked = @unblocked, unblocked end while fiber = unblocked.pop fiber.resume if fiber.alive? end end if @ready.empty? interval = @timers.wait_interval else # if there are tasks ready to execute, don't sleep: interval = 0 end # If we are finished, we stop the task tree and exit: if self.finished? return false end # 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 # logger.info(self) {"Selecting with #{@children&.size} children with interval = #{interval ? interval.round(2) : 'infinite'}..."} if monitors = @selector.select(interval) monitors.each do |monitor| monitor.value.resume end end @timers.fire # We check and clear the interrupted flag here: if @interrupted @guard.synchronize do @interrupted = false end return false end # The reactor still has work to do: return true end |
#sleep(duration) ⇒ Object
Put the calling fiber to sleep for a given ammount of time.
327 328 329 330 331 332 333 334 335 336 337 338 339 |
# File 'lib/async/reactor.rb', line 327 def sleep(duration) fiber = Fiber.current timer = @timers.after(duration) do if fiber.alive? fiber.resume end end Task.yield ensure timer.cancel if timer end |
#stop(later = true) ⇒ Object
301 302 303 304 305 306 |
# File 'lib/async/reactor.rb', line 301 def stop(later = true) @children&.each do |child| # We don't want this process to propagate `Async::Stop` exceptions, so we schedule tasks to stop later. child.stop(later) end end |
#stopped? ⇒ Boolean
146 147 148 |
# File 'lib/async/reactor.rb', line 146 def stopped? @children.nil? end |
#to_s ⇒ Object
142 143 144 |
# File 'lib/async/reactor.rb', line 142 def to_s "\#<#{self.description} #{@children&.size || 0} children (#{stopped? ? 'stopped' : 'running'})>" end |
#unblock(blocker, fiber) ⇒ Object
123 124 125 126 127 128 |
# File 'lib/async/reactor.rb', line 123 def unblock(blocker, fiber) @guard.synchronize do @unblocked << fiber @selector.wakeup end end |
#with_timeout(timeout, exception = TimeoutError) ⇒ 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.
344 345 346 347 348 349 350 351 352 353 354 355 356 357 |
# File 'lib/async/reactor.rb', line 344 def with_timeout(timeout, exception = TimeoutError) fiber = Fiber.current timer = @timers.after(timeout) do if fiber.alive? error = exception.new("execution expired") fiber.resume(error) end end yield timer ensure timer.cancel if timer end |