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
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
# Scheduler
The scheduler interface is used to intercept blocking operations. A typical
implementation would be a wrapper for a gem like `EventMachine` or `Async`. This
design provides separation of concerns between the event loop implementation
and application code. It also allows for layered schedulers which can perform
instrumentation.
## Interface
This is the interface you need to implement.
~~~ ruby
class Scheduler
# Wait for the given file descriptor to match the specified events within
# the specified timeout.
# @parameter event [Integer] A bit mask of `IO::READABLE`,
# `IO::WRITABLE` and `IO::PRIORITY`.
# @parameter timeout [Numeric] The amount of time to wait for the event in seconds.
# @returns [Integer] The subset of events that are ready.
def io_wait(io, events, timeout)
end
# Sleep the current task for the specified duration, or forever if not
# specified.
# @param duration [Numeric] The amount of time to sleep in seconds.
def kernel_sleep(duration = nil)
end
# Block the calling fiber.
# @parameter blocker [Object] What we are waiting on, informational only.
# @parameter timeout [Numeric | Nil] The amount of time to wait for in seconds.
# @returns [Boolean] Whether the blocking operation was successful or not.
def block(blocker, timeout = nil)
end
# Unblock the specified fiber.
# @parameter blocker [Object] What we are waiting on, informational only.
# @parameter fiber [Fiber] The fiber to unblock.
# @reentrant Thread safe.
def unblock(blocker, fiber)
end
# Intercept the creation of a non-blocking fiber.
# @returns [Fiber]
def fiber(&block)
Fiber.new(blocking: false, &block)
end
# Invoked when the thread exits.
def close
self.run
end
def run
# Implement event loop here.
end
end
~~~
Additional hooks may be introduced in the future, we will use feature detection
in order to enable these hooks.
## Non-blocking Execution
The scheduler hooks will only be used in special non-blocking execution
contexts. Non-blocking execution contexts introduce non-determinism because the
execution of scheduler hooks may introduce context switching points into your
program.
### Fibers
Fibers can be used to create non-blocking execution contexts.
~~~ ruby
Fiber.new(blocking: false) do
puts Fiber.current.blocking? # false
# May invoke `Fiber.scheduler&.io_wait`.
io.read(...)
# May invoke `Fiber.scheduler&.io_wait`.
io.write(...)
# Will invoke `Fiber.scheduler&.kernel_sleep`.
sleep(n)
end.resume
~~~
We also introduce a new method which simplifies the creation of these
non-blocking fibers:
~~~ ruby
Fiber.schedule do
puts Fiber.current.blocking? # false
end
~~~
The purpose of this method is to allow the scheduler to internally decide the
policy for when to start the fiber, and whether to use symmetric or asymmetric
fibers.
### IO
By default, I/O is non-blocking. Not all operating systems support non-blocking
I/O. Windows is a notable example where socket I/O can be non-blocking but pipe
I/O is blocking. Provided that there *is* a scheduler and the current thread *is
non-blocking*, the operation will invoke the scheduler.
### Mutex
The `Mutex` class can be used in a non-blocking context and is fiber specific.
### ConditionVariable
The `ConditionVariable` class can be used in a non-blocking context and is
fiber-specific.
### Queue / SizedQueue
The `Queue` and `SizedQueue` classses can be used in a non-blocking context and
are fiber-specific.
### Thread
The `Thread#join` operation can be used in a non-blocking context and is
fiber-specific.
|