1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
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
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
# Scheduler
This guide gives an overview of how the scheduler is implemented.
## Overview
The {ruby Async::Scheduler} uses an event loop to execute tasks. When tasks are waiting on blocking operations like IO, the scheduler will use the operating system's native event system to wait for the operation to complete. This allows the scheduler to efficiently handle many tasks.
### Tasks
Tasks are the building blocks of concurrent programs. They are lightweight and can be scheduled by the event loop. Tasks can be nested, and the parent task is used to determine the current reactor. Tasks behave like promises, in the sense you can wait on them to complete, and they might fail with an exception.
~~~ ruby
require 'async'
def sleepy(duration, task: Async::Task.current)
task.async do |subtask|
subtask.annotate "I'm going to sleep #{duration}s..."
sleep duration
puts "I'm done sleeping!"
end
end
def nested_sleepy(task: Async::Task.current)
task.async do |subtask|
subtask.annotate "Invoking sleepy 5 times..."
5.times do |index|
sleepy(index, task: subtask)
end
end
end
Async do |task|
task.annotate "Invoking nested_sleepy..."
subtask = nested_sleepy
# Print out all running tasks in a tree:
task.print_hierarchy($stderr)
# Kill the subtask
subtask.stop
end
~~~
### Thread Safety
Most methods of the reactor and related tasks are not thread-safe, so you'd typically have [one reactor per thread or process](https://github.com/socketry/async-container).
### Embedding Schedulers
{ruby Async::Scheduler#run} will run until the reactor runs out of work to do. To run a single iteration of the reactor, use {ruby Async::Scheduler#run_once}.
~~~ ruby
require 'async'
Console.logger.debug!
reactor = Async::Scheduler.new
# Run the reactor for 1 second:
reactor.async do |task|
sleep 1
puts "Finished!"
end
while reactor.run_once
# Round and round we go!
end
~~~
You can use this approach to embed the reactor in another event loop. For some integrations, you may want to specify the maximum time to wait to {ruby Async::Scheduler#run_once}.
### Stopping a Scheduler
{ruby Async::Scheduler#stop} will stop the current scheduler and all children tasks.
### Fiber Scheduler Integration
In order to integrate with native Ruby blocking operations, the {ruby Async::Scheduler} uses a {ruby Fiber::Scheduler} interface.
```ruby
require "async"
scheduler = Async::Scheduler.new
Fiber.set_scheduler(scheduler)
Fiber.schedule do
puts "Hello World!"
end
```
## Design
### Optimistic vs Pessimistic Scheduling
There are two main strategies for scheduling tasks: optimistic and pessimistic. An optimistic scheduler is usually greedy and will try to execute tasks as soon as they are scheduled using a direct transfer of control flow. A pessimistic scheduler will schedule tasks into the event loop ready list and will only execute them on the next iteration of the event loop.
```ruby
Async do
puts "Hello "
Async do
puts "World"
end
puts "!"
end
```
An optimstic scheduler will print "Hello World!", while a pessimistic scheduler will print "Hello !World". In practice you should not design your code to rely on the order of execution, but it's important to understand the difference. It is an unspecifed implementation detail of the scheduler.
|
