supervisor_machines 0.1.4 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +52 -0
- data/Cargo.lock +22 -2
- data/Cargo.toml +3 -0
- data/README.md +101 -6
- data/ext/supervisor_machines_native/core/Cargo.toml +4 -6
- data/ext/supervisor_machines_native/core/src/lib.rs +102 -22
- data/ext/supervisor_machines_native/core/src/supervisor.rs +270 -154
- data/ext/supervisor_machines_native/ffi/Cargo.toml +5 -9
- data/ext/supervisor_machines_native/ffi/src/decider.rs +333 -117
- data/ext/supervisor_machines_native/ffi/src/init.rs +30 -0
- data/ext/supervisor_machines_native/ffi/src/lib.rs +199 -108
- data/lib/supervisor_machines/supervisor.rb +113 -60
- data/lib/supervisor_machines/values.rb +63 -0
- data/lib/supervisor_machines/version.rb +1 -1
- data/lib/supervisor_machines.rb +12 -3
- data/sig/supervisor_machines.rbs +179 -63
- metadata +7 -5
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: e943fd70055323fe77d4dabbf7d729981ee1157cd45702642ca3dd7a619fd594
|
|
4
|
+
data.tar.gz: 067c5bd1768025f70adbf3bb9be0eb0eee220c6ad501f448bb3e564f2f1eac30
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: d7cbfa5665fad1c662cdcdf18205d8c6c783dcd9dcee2aa773731fda01e0afea7904988b9fe04924f72d1879bf78aa1f600a2913ab69999f89e008b4c00a81d2
|
|
7
|
+
data.tar.gz: 18fea2bb0b868a6470435015284fc5949cd8a373a8bbbbbbcf72b3d6d25e94ffedb87b5974722b5103db6c65c776a8b740de9226642ba0bf3c02008d75114518
|
data/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,57 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [0.4.0](https://github.com/seuros/supervisor_machines/compare/supervisor_machines/v0.3.2...supervisor_machines/v0.4.0) (2026-11-16)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### ⚠ BREAKING CHANGES
|
|
7
|
+
|
|
8
|
+
* take chrono_machines shapes for the respawn delay and seal Decider
|
|
9
|
+
|
|
10
|
+
### Features
|
|
11
|
+
|
|
12
|
+
* take chrono_machines shapes for the respawn delay and seal Decider ([b837f98](https://github.com/seuros/supervisor_machines/commit/b837f981e1e8eba163a54bafed04b94a18b7cd0f))
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
### Bug Fixes
|
|
16
|
+
|
|
17
|
+
* fix wrapped classes at load so building a value runs no Ruby ([3b425ae](https://github.com/seuros/supervisor_machines/commit/3b425ae69f73c6cf8df692c7c094918cd661de4f))
|
|
18
|
+
|
|
19
|
+
## [0.3.2](https://github.com/seuros/supervisor_machines/compare/supervisor_machines/v0.3.1...supervisor_machines/v0.3.2) (2026-11-14)
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
### Bug Fixes
|
|
23
|
+
|
|
24
|
+
* **deps:** require matryona-machines >= 0.4 ([c6bb9ed](https://github.com/seuros/supervisor_machines/commit/c6bb9edb77be3af8da24e90bf252437b44d2da84))
|
|
25
|
+
|
|
26
|
+
## [0.3.1](https://github.com/seuros/supervisor_machines/compare/supervisor_machines/v0.3.0...supervisor_machines/v0.3.1) (2026-11-14)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
### Bug Fixes
|
|
30
|
+
|
|
31
|
+
* **deps:** require matryona-machines >= 0.3 ([65279bf](https://github.com/seuros/supervisor_machines/commit/65279bff313f50fe063e34505ac7249830470b37))
|
|
32
|
+
|
|
33
|
+
## [0.3.0](https://github.com/seuros/supervisor_machines/compare/supervisor_machines/v0.2.0...supervisor_machines/v0.3.0) (2026-11-14)
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
### ⚠ BREAKING CHANGES
|
|
37
|
+
|
|
38
|
+
* adopt matryona-machines 0.2: struct-only reads, native Restart check, symbols! tables, caret rb-sys
|
|
39
|
+
|
|
40
|
+
### Features
|
|
41
|
+
|
|
42
|
+
* adopt matryona-machines 0.2: struct-only reads, native Restart check, symbols! tables, caret rb-sys ([836afc6](https://github.com/seuros/supervisor_machines/commit/836afc6d615cf53a61e57a75d88b4c14a3ea4329))
|
|
43
|
+
|
|
44
|
+
## [0.2.0](https://github.com/seuros/supervisor_machines/compare/supervisor_machines/v0.1.4...supervisor_machines/v0.2.0) (2026-11-14)
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
### ⚠ BREAKING CHANGES
|
|
48
|
+
|
|
49
|
+
* refuse unknown children, Duration time, multiset restore and absorb, exact-class boundary, Decider core
|
|
50
|
+
|
|
51
|
+
### Features
|
|
52
|
+
|
|
53
|
+
* refuse unknown children, Duration time, multiset restore and absorb, exact-class boundary, Decider core ([16f739b](https://github.com/seuros/supervisor_machines/commit/16f739b821052bb676b4086ec63927d9cc0ee8e9))
|
|
54
|
+
|
|
3
55
|
## [0.1.4](https://github.com/seuros/supervisor_machines/compare/supervisor_machines/v0.1.3...supervisor_machines/v0.1.4) (2026-11-06)
|
|
4
56
|
|
|
5
57
|
|
data/Cargo.lock
CHANGED
|
@@ -35,6 +35,12 @@ version = "2.13.2"
|
|
|
35
35
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
36
36
|
checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
|
|
37
37
|
|
|
38
|
+
[[package]]
|
|
39
|
+
name = "bytes"
|
|
40
|
+
version = "1.12.1"
|
|
41
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
42
|
+
checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
|
|
43
|
+
|
|
38
44
|
[[package]]
|
|
39
45
|
name = "cexpr"
|
|
40
46
|
version = "0.6.0"
|
|
@@ -110,6 +116,7 @@ version = "0.9.3"
|
|
|
110
116
|
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
111
117
|
checksum = "40ef424404d166cbb71c8b8d19c9c589c748c4547c1afa1928c5504299f6c713"
|
|
112
118
|
dependencies = [
|
|
119
|
+
"bytes",
|
|
113
120
|
"magnus-macros",
|
|
114
121
|
"rb-sys",
|
|
115
122
|
"rb-sys-env",
|
|
@@ -127,6 +134,15 @@ dependencies = [
|
|
|
127
134
|
"syn",
|
|
128
135
|
]
|
|
129
136
|
|
|
137
|
+
[[package]]
|
|
138
|
+
name = "matryona-machines"
|
|
139
|
+
version = "0.6.0"
|
|
140
|
+
source = "registry+https://github.com/rust-lang/crates.io-index"
|
|
141
|
+
checksum = "cf8a06ab02efd767270815a1f515a40bbf3bfc77038e9360676ebe8d47833b07"
|
|
142
|
+
dependencies = [
|
|
143
|
+
"magnus",
|
|
144
|
+
]
|
|
145
|
+
|
|
130
146
|
[[package]]
|
|
131
147
|
name = "memchr"
|
|
132
148
|
version = "2.8.3"
|
|
@@ -252,13 +268,17 @@ checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
|
|
|
252
268
|
|
|
253
269
|
[[package]]
|
|
254
270
|
name = "supervisor-machines"
|
|
255
|
-
version = "0.
|
|
271
|
+
version = "0.7.0"
|
|
272
|
+
dependencies = [
|
|
273
|
+
"matryona-machines",
|
|
274
|
+
]
|
|
256
275
|
|
|
257
276
|
[[package]]
|
|
258
277
|
name = "supervisor_machines_native"
|
|
259
|
-
version = "0.1.
|
|
278
|
+
version = "0.1.6"
|
|
260
279
|
dependencies = [
|
|
261
280
|
"magnus",
|
|
281
|
+
"matryona-machines",
|
|
262
282
|
"rb-sys",
|
|
263
283
|
"supervisor-machines",
|
|
264
284
|
]
|
data/Cargo.toml
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
[workspace]
|
|
2
2
|
members = ["ext/supervisor_machines_native/core", "ext/supervisor_machines_native/ffi"]
|
|
3
|
+
default-members = ["ext/supervisor_machines_native/core"]
|
|
3
4
|
resolver = "3"
|
|
4
5
|
|
|
5
6
|
[workspace.package]
|
|
@@ -8,10 +9,12 @@ rust-version = "1.99"
|
|
|
8
9
|
|
|
9
10
|
[workspace.dependencies]
|
|
10
11
|
supervisor-machines = { path = "ext/supervisor_machines_native/core" }
|
|
12
|
+
matryona-machines = { version = ">=0.6", default-features = false }
|
|
11
13
|
|
|
12
14
|
[workspace.lints.rust]
|
|
13
15
|
unsafe_code = "forbid"
|
|
14
16
|
unused_must_use = "warn"
|
|
17
|
+
missing_docs = "warn"
|
|
15
18
|
|
|
16
19
|
[workspace.lints.clippy]
|
|
17
20
|
all = { level = "warn", priority = -1 }
|
data/README.md
CHANGED
|
@@ -27,7 +27,9 @@ native extension, not an option.
|
|
|
27
27
|
```ruby
|
|
28
28
|
SM = SupervisorMachines
|
|
29
29
|
|
|
30
|
-
|
|
30
|
+
SECOND = 1_000_000_000
|
|
31
|
+
|
|
32
|
+
tree = SM::Supervisor.new(:one_for_all, SM::Intensity.new(3, 60 * SECOND))
|
|
31
33
|
tree.supervise(:cache) { Thread.new { cache.run } }
|
|
32
34
|
tree.supervise(:warmup, policy: :transient) { Thread.new { warm_the_cache } }
|
|
33
35
|
tree.start
|
|
@@ -36,13 +38,19 @@ tree.children # => [:cache, :warmup]
|
|
|
36
38
|
tree.restarts # => 0
|
|
37
39
|
tree.terminated? # => false
|
|
38
40
|
|
|
39
|
-
tree.stop(
|
|
41
|
+
tree.stop(5 * SECOND)
|
|
40
42
|
```
|
|
41
43
|
|
|
42
44
|
A starter block returns the `Thread` that runs the child, and is called again
|
|
43
45
|
for every restart. A child that stops is noticed, handed to the core, and
|
|
44
46
|
whatever the core decides is carried out.
|
|
45
47
|
|
|
48
|
+
Every instant and span is **Integer nanoseconds**, in and out: a non-Integer
|
|
49
|
+
raises `TypeError`, a negative one `RangeError`. `stop(grace)` takes a grace in
|
|
50
|
+
nanoseconds or `nil` for no limit; `Supervisor::ESCALATION_GRACE` is
|
|
51
|
+
nanoseconds too. The sibling gems the tree drives (chrono_machines,
|
|
52
|
+
deadline_machines) still speak Float seconds; the tree converts at their door.
|
|
53
|
+
|
|
46
54
|
---
|
|
47
55
|
|
|
48
56
|
## 🔄 Lifecycle
|
|
@@ -91,7 +99,9 @@ tree.supervise(:migration, policy: :temporary) { Thread.new { migrate } }
|
|
|
91
99
|
|
|
92
100
|
## 🔥 Restart Intensity
|
|
93
101
|
|
|
94
|
-
`restarts
|
|
102
|
+
An `SupervisorMachines::Intensity.new(restarts, window)`, `restarts` within
|
|
103
|
+
`window` nanoseconds, is all the thrashing a tree will do.
|
|
104
|
+
`Intensity.default` is OTP's one restart in five seconds. Past
|
|
95
105
|
it, the tree stops its remaining children in reverse start order and raises
|
|
96
106
|
`SupervisorMachines::Escalated`, and the supervisor's own supervisor now owns
|
|
97
107
|
the problem. That decision is sticky: `terminated?` stays true and every later
|
|
@@ -102,8 +112,9 @@ the problem. That decision is sticky: `terminated?` stays true and every later
|
|
|
102
112
|
## 🚫 Rules of Engagement
|
|
103
113
|
|
|
104
114
|
- The delay between a restart decision and the respawn comes from
|
|
105
|
-
[chrono_machines][chrono]
|
|
106
|
-
|
|
115
|
+
[chrono_machines][chrono]: `Supervisor::BACKOFF`, 100 ms doubling to 10 s
|
|
116
|
+
with full jitter. Pass another shape as `backoff:` to change the curve.
|
|
117
|
+
- The shutdown budget comes from [deadline_machines][deadline]: `stop(grace)`
|
|
107
118
|
bounds the whole ordered teardown, and a child that outstays it is left
|
|
108
119
|
behind rather than waited on forever.
|
|
109
120
|
- Restart intensity, strategy spans and policy decisions come from the core
|
|
@@ -115,10 +126,94 @@ the problem. That decision is sticky: `terminated?` stays true and every later
|
|
|
115
126
|
|
|
116
127
|
The core carries its child count in its type, so a tree is dispatched to one of
|
|
117
128
|
`SupervisorMachines::Decider::SUPPORTED_CHILDREN` monomorphised shapes: 1
|
|
118
|
-
through 16, and 32. Any other count raises `
|
|
129
|
+
through 16, and 32. Any other count raises `RangeError` from `#start`. More
|
|
130
|
+
restarts than `Decider::MAX_RESTARTS` (the 64-instant history minus one) raise
|
|
131
|
+
`RangeError` from `Supervisor.new`. An unknown strategy or policy symbol is a
|
|
132
|
+
`RangeError`, a non-Symbol a `TypeError`.
|
|
119
133
|
|
|
120
134
|
Threads are the only supervised unit.
|
|
121
135
|
|
|
136
|
+
`Supervisor` is a runtime on top of the core, not a mirror of it, so it keeps
|
|
137
|
+
two keyword defaults the core has no counterpart for: `backoff:` (a
|
|
138
|
+
chrono_machines shape, asked `delay(restarts, draw)` in nanoseconds) and
|
|
139
|
+
`supervise(name, policy: :permanent)`, OTP's default child policy. The
|
|
140
|
+
`Decider` below is the mirror, and takes no keyword at all.
|
|
141
|
+
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
## 🧭 The Decider
|
|
145
|
+
|
|
146
|
+
`SupervisorMachines::Decider` is the core's `Supervisor` itself, for callers
|
|
147
|
+
who run their own processes, fibers or reactors. It mirrors the Rust API
|
|
148
|
+
method for method, positionally and in nanoseconds; refusals are symbols and
|
|
149
|
+
never raise.
|
|
150
|
+
|
|
151
|
+
```ruby
|
|
152
|
+
decider = SM::Decider.new(3, :rest_for_one, SM::Intensity.new(2, 60 * SECOND))
|
|
153
|
+
decider.stopped(1, :permanent, :abnormal, now)
|
|
154
|
+
# => #<data SupervisorMachines::Restart span=#<data SupervisorMachines::Span first=1, last=2>>
|
|
155
|
+
decider.stopped(7, :permanent, :abnormal, now) # => :unknown_child
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Values are `Data`, validated through the core whether the gem built them or
|
|
159
|
+
you did: `Intensity(restarts, window)` (zero window: `RangeError`),
|
|
160
|
+
`Span(first, last)` (`first` past `last`: `RangeError`), `Restart(span)`.
|
|
161
|
+
They are final: subclassing one raises `TypeError` and `allocate` is gone.
|
|
162
|
+
Sealing stops accidents, not reflection (a named subclass's constant is bound
|
|
163
|
+
before `inherited` raises, and `Marshal.load` skips `initialize`), so the
|
|
164
|
+
binding is the authority: every value it reads must be an instance of exactly
|
|
165
|
+
the gem's class (`TypeError` otherwise, a subclass included) and is rebuilt
|
|
166
|
+
through the core constructor (`RangeError` for a forged one). `Decider` wraps
|
|
167
|
+
native state with no allocator, and is sealed too: subclassing it raises
|
|
168
|
+
`TypeError`.
|
|
169
|
+
|
|
170
|
+
### Contract
|
|
171
|
+
|
|
172
|
+
- **One refusal**, `:unknown_child`: an index at or past the child count. It is
|
|
173
|
+
checked first, on a terminated decider too, and changes nothing.
|
|
174
|
+
- **Honoured repeat.** Once escalated, every further `stopped` answers
|
|
175
|
+
`:already_escalated` and records nothing.
|
|
176
|
+
- **The clock.** The decider keeps no clock but its restart history. Answers
|
|
177
|
+
that depend on `now` record it (a `Restart`, `:escalate`, `:recorded`);
|
|
178
|
+
answers that hold whatever the time (`:ignore`, `:already_escalated`,
|
|
179
|
+
`:outdated`) record nothing. Restarts may arrive in any order.
|
|
180
|
+
- **No scopes.** Child indices are your own numbers; nothing is issued.
|
|
181
|
+
`Decider.restore` rebuilds from a saved `history`, every instant counted
|
|
182
|
+
(two restarts at one instant restore as two); escalation is not saved, so a
|
|
183
|
+
restored decider decides for itself. `absorb` merges an Array of Integer
|
|
184
|
+
nanoseconds (any order) keeping the larger count of each instant, so
|
|
185
|
+
another process's two restarts at one instant stay two and a repeated
|
|
186
|
+
absorb changes nothing.
|
|
187
|
+
- **Malformed input raises** before the core is touched: `TypeError` for the
|
|
188
|
+
wrong type, `RangeError` for a value outside what the core accepts,
|
|
189
|
+
`FrozenError` for a frozen decider.
|
|
190
|
+
- **Never loses work.** `stopped` decides on a copy and keeps it only once the
|
|
191
|
+
answer is built: a raise while building a `Restart` (a redefined `new`)
|
|
192
|
+
changes nothing, freezing the decider meanwhile raises `FrozenError` and a
|
|
193
|
+
call that changed it `RuntimeError`, with the outer `stopped` not applied.
|
|
194
|
+
No reader holds the decider while it builds a `Data` answer, so a `new` that
|
|
195
|
+
calls back into it makes an ordinary call.
|
|
196
|
+
|
|
197
|
+
### Every answer
|
|
198
|
+
|
|
199
|
+
| Method | Answers | Records the clock |
|
|
200
|
+
| --- | --- | --- |
|
|
201
|
+
| `Decider.new(children, strategy, intensity)` | a decider; `RangeError` for an unsupported count or too many restarts | - |
|
|
202
|
+
| `Decider.restore(children, strategy, intensity, history, now)` | a decider holding the restarts inside the window as of `now` | - |
|
|
203
|
+
| `stopped(index, policy, exit, now)` | `:ignore` | no |
|
|
204
|
+
| | `Restart(span)`: one restart recorded at `now` | yes |
|
|
205
|
+
| | `:escalate`: recorded at `now`, now terminated | yes |
|
|
206
|
+
| | `:already_escalated`: terminated before the call | no |
|
|
207
|
+
| | `:unknown_child` (refusal): nothing changed | no |
|
|
208
|
+
| `record_external_restart(now)` | `:recorded` | yes |
|
|
209
|
+
| | `:outdated`: a full history of newer restarts, nothing changed | no |
|
|
210
|
+
| `absorb(history, now)` | Integer, restarts added (larger count of each instant kept); `0` changes nothing | only the added instants |
|
|
211
|
+
| `recent_restarts(now)` | Integer | no |
|
|
212
|
+
| `restart_delay(base, ceiling, now)` | Integer nanoseconds | no |
|
|
213
|
+
| `span(index)` | `Span`, or `nil` past the child count | no |
|
|
214
|
+
| `history` | frozen Array of Integer nanoseconds, oldest first | no |
|
|
215
|
+
| `strategy`, `intensity`, `children`, `terminated?` | readers | no |
|
|
216
|
+
|
|
122
217
|
---
|
|
123
218
|
|
|
124
219
|
## 📡 Credits
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[package]
|
|
2
2
|
name = "supervisor-machines"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "0.7.0"
|
|
4
4
|
edition.workspace = true
|
|
5
5
|
rust-version.workspace = true
|
|
6
6
|
authors = ["Abdelkader Boudih <oss@seuros.com>"]
|
|
@@ -10,15 +10,13 @@ repository = "https://github.com/seuros/supervisor_machines"
|
|
|
10
10
|
keywords = ["supervisor", "supervision-tree", "otp", "restart", "no-std"]
|
|
11
11
|
categories = ["no-std", "concurrency"]
|
|
12
12
|
readme = "README.md"
|
|
13
|
-
exclude = ["src/**/tests.rs", "tests/"]
|
|
13
|
+
exclude = ["src/tests/", "src/**/tests.rs", "tests/"]
|
|
14
14
|
[lib]
|
|
15
15
|
name = "supervisor_machines"
|
|
16
16
|
crate-type = ["lib"]
|
|
17
17
|
|
|
18
|
-
[
|
|
19
|
-
|
|
20
|
-
std = ["alloc"]
|
|
21
|
-
alloc = []
|
|
18
|
+
[dev-dependencies]
|
|
19
|
+
matryona-machines = { workspace = true, features = ["testing"] }
|
|
22
20
|
|
|
23
21
|
[lints]
|
|
24
22
|
workspace = true
|
|
@@ -1,9 +1,13 @@
|
|
|
1
|
-
#![
|
|
1
|
+
#![no_std]
|
|
2
|
+
#![cfg_attr(not(test), deny(clippy::indexing_slicing))]
|
|
2
3
|
|
|
3
4
|
//! Supervision decisions, in the OTP sense.
|
|
4
5
|
//!
|
|
5
6
|
//! Which children restart after one dies, and whether that has happened too
|
|
6
7
|
//! often to keep trying. The caller owns the threads, fibers or processes.
|
|
8
|
+
//!
|
|
9
|
+
//! Time is [`core::time::Duration`] since an epoch the caller picks, for
|
|
10
|
+
//! instants and spans alike. The core reads no clock.
|
|
7
11
|
|
|
8
12
|
/// Compiles and runs the README's examples as doctests.
|
|
9
13
|
#[cfg(doctest)]
|
|
@@ -12,8 +16,29 @@ struct ReadmeDoctests;
|
|
|
12
16
|
|
|
13
17
|
pub mod supervisor;
|
|
14
18
|
|
|
19
|
+
use core::fmt;
|
|
20
|
+
use core::time::Duration;
|
|
21
|
+
|
|
15
22
|
pub use supervisor::Supervisor;
|
|
16
23
|
|
|
24
|
+
/// Why a call was not honoured. A refused call changed nothing.
|
|
25
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
26
|
+
pub enum Refusal {
|
|
27
|
+
/// The child index is not below `CHILDREN`: the supervisor owns no such
|
|
28
|
+
/// child, so there is nothing to decide.
|
|
29
|
+
UnknownChild,
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
impl fmt::Display for Refusal {
|
|
33
|
+
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
34
|
+
formatter.write_str(match self {
|
|
35
|
+
Self::UnknownChild => "the supervisor owns no child at that index",
|
|
36
|
+
})
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
impl core::error::Error for Refusal {}
|
|
41
|
+
|
|
17
42
|
/// Which siblings a failure takes down with it.
|
|
18
43
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
19
44
|
pub enum Strategy {
|
|
@@ -45,28 +70,54 @@ pub enum Exit {
|
|
|
45
70
|
Abnormal,
|
|
46
71
|
}
|
|
47
72
|
|
|
48
|
-
/// What the supervisor should do about a child that stopped.
|
|
73
|
+
/// What the supervisor should do about a child that stopped. Every variant is
|
|
74
|
+
/// an honoured answer: the question was well formed and this is the decision.
|
|
49
75
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
50
76
|
pub enum Decision {
|
|
51
|
-
/// Leave it stopped. Nothing restarts.
|
|
77
|
+
/// Leave it stopped. Nothing restarts and nothing was recorded.
|
|
52
78
|
Ignore,
|
|
53
|
-
/// Restart this inclusive range of children, in index order.
|
|
79
|
+
/// Restart this inclusive range of children, in index order. The restart
|
|
80
|
+
/// was recorded at the instant supplied.
|
|
54
81
|
Restart(Span),
|
|
55
|
-
/// Restarting is not working
|
|
56
|
-
///
|
|
82
|
+
/// Restarting is not working: this failure spent the intensity. The
|
|
83
|
+
/// restart was recorded (unless a full history of newer restarts left no
|
|
84
|
+
/// room for it, which is itself past the intensity), the supervisor is
|
|
85
|
+
/// now terminated, and it must
|
|
86
|
+
/// take its remaining children down and let its own supervisor decide.
|
|
57
87
|
Escalate,
|
|
88
|
+
/// The supervisor had already escalated. Nothing was recorded: the answer
|
|
89
|
+
/// holds whatever the time, and a supervisor that gave up stays given up.
|
|
90
|
+
AlreadyEscalated,
|
|
58
91
|
}
|
|
59
92
|
|
|
60
|
-
///
|
|
93
|
+
/// What [`Supervisor::record_external_restart`] did with the restart.
|
|
94
|
+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
95
|
+
pub enum Recording {
|
|
96
|
+
/// The restart is now in the history.
|
|
97
|
+
Recorded,
|
|
98
|
+
/// The history is full of newer restarts, which already decide every
|
|
99
|
+
/// question this one could have changed. Nothing changed.
|
|
100
|
+
Outdated,
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/// An inclusive range of child indices. It always covers at least one child.
|
|
61
104
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
62
105
|
pub struct Span {
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
/// Highest index, restarted last.
|
|
66
|
-
pub last: usize,
|
|
106
|
+
first: usize,
|
|
107
|
+
last: usize,
|
|
67
108
|
}
|
|
68
109
|
|
|
69
110
|
impl Span {
|
|
111
|
+
/// The children `first..=last`, or `None` when `first` is past `last`.
|
|
112
|
+
#[must_use]
|
|
113
|
+
pub const fn new(first: usize, last: usize) -> Option<Self> {
|
|
114
|
+
if first > last {
|
|
115
|
+
return None;
|
|
116
|
+
}
|
|
117
|
+
Some(Self { first, last })
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/// The one child at `index`.
|
|
70
121
|
#[must_use]
|
|
71
122
|
pub const fn single(index: usize) -> Self {
|
|
72
123
|
Self {
|
|
@@ -75,10 +126,23 @@ impl Span {
|
|
|
75
126
|
}
|
|
76
127
|
}
|
|
77
128
|
|
|
129
|
+
/// Lowest index, restarted first.
|
|
130
|
+
#[must_use]
|
|
131
|
+
pub const fn first(&self) -> usize {
|
|
132
|
+
self.first
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/// Highest index, restarted last.
|
|
136
|
+
#[must_use]
|
|
137
|
+
pub const fn last(&self) -> usize {
|
|
138
|
+
self.last
|
|
139
|
+
}
|
|
140
|
+
|
|
78
141
|
/// Children in the span. Always at least one.
|
|
79
142
|
#[must_use]
|
|
80
143
|
pub const fn len(&self) -> usize {
|
|
81
|
-
|
|
144
|
+
// `first <= last` by construction.
|
|
145
|
+
(self.last - self.first).saturating_add(1)
|
|
82
146
|
}
|
|
83
147
|
|
|
84
148
|
/// Never true. A span always covers the child that died.
|
|
@@ -87,6 +151,7 @@ impl Span {
|
|
|
87
151
|
false
|
|
88
152
|
}
|
|
89
153
|
|
|
154
|
+
/// Whether the child at `index` is in the span.
|
|
90
155
|
#[must_use]
|
|
91
156
|
pub const fn contains(&self, index: usize) -> bool {
|
|
92
157
|
self.first <= index && index <= self.last
|
|
@@ -96,31 +161,46 @@ impl Span {
|
|
|
96
161
|
/// How many restarts within how long before a supervisor gives up.
|
|
97
162
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
|
98
163
|
pub struct Intensity {
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
/// Length of the window, in nanoseconds.
|
|
102
|
-
pub window_ns: u64,
|
|
164
|
+
restarts: u32,
|
|
165
|
+
window: Duration,
|
|
103
166
|
}
|
|
104
167
|
|
|
105
168
|
/// Restarts OTP tolerates by default before escalating.
|
|
106
169
|
pub const DEFAULT_RESTARTS: u32 = 1;
|
|
107
170
|
|
|
108
171
|
/// The window OTP measures those restarts over, five seconds.
|
|
109
|
-
pub const
|
|
172
|
+
pub const DEFAULT_WINDOW: Duration = Duration::from_secs(5);
|
|
110
173
|
|
|
111
174
|
impl Intensity {
|
|
175
|
+
/// `restarts` tolerated inside `window`, or `None` when the window is
|
|
176
|
+
/// zero: a restart cannot be measured over no time at all.
|
|
112
177
|
#[must_use]
|
|
113
|
-
pub const fn new(restarts: u32,
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
window_ns,
|
|
178
|
+
pub const fn new(restarts: u32, window: Duration) -> Option<Self> {
|
|
179
|
+
if window.is_zero() {
|
|
180
|
+
return None;
|
|
117
181
|
}
|
|
182
|
+
Some(Self { restarts, window })
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
/// Restarts tolerated inside the window.
|
|
186
|
+
#[must_use]
|
|
187
|
+
pub const fn restarts(&self) -> u32 {
|
|
188
|
+
self.restarts
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/// Length of the window.
|
|
192
|
+
#[must_use]
|
|
193
|
+
pub const fn window(&self) -> Duration {
|
|
194
|
+
self.window
|
|
118
195
|
}
|
|
119
196
|
}
|
|
120
197
|
|
|
121
198
|
impl Default for Intensity {
|
|
122
199
|
fn default() -> Self {
|
|
123
|
-
Self
|
|
200
|
+
Self {
|
|
201
|
+
restarts: DEFAULT_RESTARTS,
|
|
202
|
+
window: DEFAULT_WINDOW,
|
|
203
|
+
}
|
|
124
204
|
}
|
|
125
205
|
}
|
|
126
206
|
|