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.
@@ -0,0 +1,63 @@
1
+ # frozen_string_literal: true
2
+
3
+ # Every value mirrors the core type of the same name, field for field, and is
4
+ # validated through the core when it is built, by hand or by the gem: wrong
5
+ # type is a TypeError, a value the core's constructor rejects a RangeError.
6
+ # Every instant and span is Integer nanoseconds.
7
+ module SupervisorMachines
8
+ # The core's `Intensity`: `restarts` tolerated inside `window` nanoseconds.
9
+ # Like `Intensity::new`, the window must be longer than zero (RangeError);
10
+ # `restarts` is a nonnegative Integer that fits a u32.
11
+ Intensity = Data.define(:restarts, :window) do
12
+ # The core's `Intensity::default`: OTP's one restart in five seconds.
13
+ def self.default = new(DEFAULT_RESTARTS, DEFAULT_WINDOW)
14
+
15
+ def initialize(restarts:, window:)
16
+ restarts, window = SupervisorMachines.__send__(:__intensity, restarts, window)
17
+ super
18
+ end
19
+ end
20
+
21
+ # The core's `Span`: the inclusive range of child indices `first..last`.
22
+ # Like `Span::new`, `first` past `last` is a RangeError; it always covers at
23
+ # least one child.
24
+ Span = Data.define(:first, :last) do
25
+ # The core's `Span::single`: the one child at `index`.
26
+ def self.single(index) = new(index, index)
27
+
28
+ def initialize(first:, last:)
29
+ first, last = SupervisorMachines.__send__(:__span, first, last)
30
+ super
31
+ end
32
+
33
+ # Children in the span, the core's `len`. Always at least one.
34
+ def size = last - first + 1
35
+
36
+ # Never true: a span always covers the child that died.
37
+ def empty? = false
38
+
39
+ # Whether the child at `index` is in the span.
40
+ def contains?(index) = index.is_a?(Integer) && first <= index && index <= last
41
+ end
42
+
43
+ # The core's `Decision::Restart(Span)`: restart `span`, in index order. The
44
+ # other decisions carry nothing and are symbols (:ignore, :escalate,
45
+ # :already_escalated).
46
+ Restart = Data.define(:span) do
47
+ # The span is checked natively for its exact class and revalidated through
48
+ # the core (`Marshal.load` skips `initialize`), its fields read from the
49
+ # struct, never through readers.
50
+ def initialize(span:)
51
+ super(span: SupervisorMachines.__send__(:__restart, span))
52
+ end
53
+ end
54
+
55
+ # The values are final. `initialize` is where each validates, and a subclass
56
+ # could override it, or `allocate` build an instance that never ran it:
57
+ # subclassing raises TypeError (as subclassing Class does) and `allocate`
58
+ # is gone. `new`, keywords, `with` and `dup` all still run the check.
59
+ [Intensity, Span, Restart].each do |value|
60
+ value.singleton_class.undef_method(:allocate)
61
+ value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
62
+ end
63
+ end
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module SupervisorMachines
4
- VERSION = '0.1.4'
4
+ VERSION = '0.4.0'
5
5
  end
@@ -4,11 +4,20 @@ require 'chrono_machines'
4
4
  require 'deadline_machines'
5
5
 
6
6
  require_relative 'supervisor_machines/version'
7
+ require_relative 'supervisor_machines/values'
7
8
 
8
- # Decider is defined by the native extension, which binds the
9
- # `supervisor-machines` crate; there is no pure-Ruby implementation to fall
10
- # back to.
9
+ # Decider and the validating hooks the values above call are defined by the
10
+ # native extension, which binds the `supervisor-machines` crate; there is no
11
+ # pure-Ruby implementation to fall back to.
11
12
  require 'supervisor_machines_native/supervisor_machines_native'
12
13
 
14
+ module SupervisorMachines
15
+ private_class_method :__intensity, :__span, :__restart, :__policy, :__strategy, :__supervised_intensity
16
+
17
+ # Decider wraps native state and has no allocator: a subclass's `new`
18
+ # would build the base class anyway, so subclassing raises too.
19
+ Decider.define_singleton_method(:inherited) { |_| raise TypeError, "#{Decider} cannot be subclassed" }
20
+ end
21
+
13
22
  require_relative 'supervisor_machines/errors'
14
23
  require_relative 'supervisor_machines/supervisor'
@@ -3,19 +3,16 @@
3
3
  # `Decider` is defined by the native extension, which binds the
4
4
  # `supervisor-machines` crate: it decides which children a failure takes down
5
5
  # and when restarting has stopped being worth it. `Supervisor` owns everything
6
- # the core refuses to touch, which is every thread.
6
+ # the core refuses to touch, which is every thread. Every instant and span is
7
+ # Integer nanoseconds.
7
8
  module SupervisorMachines
8
9
  VERSION: String
9
10
 
10
- # Nanoseconds in a second. Seconds are what the Ruby surface takes; the core
11
- # is fed nanosecond integers.
12
- NS_PER_SECOND: Integer
13
-
14
11
  # Restarts OTP tolerates by default before escalating.
15
12
  DEFAULT_RESTARTS: Integer
16
13
 
17
- # The window OTP measures those restarts over, five seconds.
18
- DEFAULT_WINDOW_NS: Integer
14
+ # The window OTP measures those restarts over: five seconds, in nanoseconds.
15
+ DEFAULT_WINDOW: Integer
19
16
 
20
17
  # Which siblings a failure takes down with it.
21
18
  type strategy = :one_for_one | :one_for_all | :rest_for_one
@@ -26,18 +23,89 @@ module SupervisorMachines
26
23
  # How a child's run ended.
27
24
  type exit_kind = :normal | :abnormal
28
25
 
29
- # What the core decided: leave it stopped, restart this inclusive range of
30
- # child indices, or give up.
31
- type decision = :ignore | :escalate | Range[Integer]
26
+ # The core's `Decision`, every variant honoured.
27
+ type decision = :ignore | Restart | :escalate | :already_escalated
28
+
29
+ # The core's `Refusal`.
30
+ type refusal = :unknown_child
32
31
 
33
- # Every strategy, in the order the core declares them. Anything else raises
34
- # `ArgumentError`.
32
+ # The core's `Recording`.
33
+ type recording = :recorded | :outdated
34
+
35
+ # Every strategy, in the order the core declares them. Another Symbol raises
36
+ # `RangeError`, a non-Symbol `TypeError`.
35
37
  STRATEGIES: Array[strategy]
36
38
 
37
- # Every policy, in the order the core declares them. Anything else raises
38
- # `ArgumentError`.
39
+ # Every policy, in the order the core declares them. Another Symbol raises
40
+ # `RangeError`, a non-Symbol `TypeError`.
39
41
  POLICIES: Array[policy]
40
42
 
43
+ # Every exit, in the order the core declares them.
44
+ EXITS: Array[exit_kind]
45
+
46
+ # Private native checks behind the values and Supervisor, TypeError for a
47
+ # wrong type, RangeError for what the core rejects. `__intensity` and
48
+ # `__span` answer the fields as the core holds them; `__restart`,
49
+ # `__policy` and `__strategy` answer their argument; `__supervised_intensity`
50
+ # reads exactly an Intensity and rebuilds it, RangeError past
51
+ # Decider::MAX_RESTARTS.
52
+ private def self.__intensity: (Integer restarts, Integer window) -> [Integer, Integer]
53
+ private def self.__span: (Integer first, Integer last) -> [Integer, Integer]
54
+ private def self.__restart: (Span span) -> Span
55
+ private def self.__policy: (policy policy) -> policy
56
+ private def self.__strategy: (strategy strategy) -> strategy
57
+ private def self.__supervised_intensity: (Intensity intensity) -> Intensity
58
+
59
+ # The core's `Intensity`: `restarts` within `window` nanoseconds. A zero
60
+ # window, a negative value or one past its width raises `RangeError`; a
61
+ # non-Integer `TypeError`.
62
+ class Intensity < ::Data
63
+ attr_reader restarts: Integer
64
+ attr_reader window: Integer
65
+
66
+ def self.new: (Integer restarts, Integer window) -> instance
67
+ | (restarts: Integer, window: Integer) -> instance
68
+
69
+ # The core's `Intensity::default`: one restart in five seconds.
70
+ def self.default: () -> Intensity
71
+
72
+ def initialize: (restarts: Integer, window: Integer) -> void
73
+ end
74
+
75
+ # The core's `Span`: the inclusive child indices `first..last`. `first` past
76
+ # `last` or a negative end raises `RangeError`; a non-Integer `TypeError`.
77
+ class Span < ::Data
78
+ attr_reader first: Integer
79
+ attr_reader last: Integer
80
+
81
+ def self.new: (Integer first, Integer last) -> instance
82
+ | (first: Integer, last: Integer) -> instance
83
+
84
+ # The one child at `index`.
85
+ def self.single: (Integer index) -> Span
86
+
87
+ def initialize: (first: Integer, last: Integer) -> void
88
+
89
+ # Children in the span, at least one.
90
+ def size: () -> Integer
91
+
92
+ # Never true.
93
+ def empty?: () -> false
94
+
95
+ def contains?: (untyped index) -> bool
96
+ end
97
+
98
+ # The core's `Decision::Restart`: restart `span` in index order. A non-Span
99
+ # raises `TypeError`.
100
+ class Restart < ::Data
101
+ attr_reader span: Span
102
+
103
+ def self.new: (Span span) -> instance
104
+ | (span: Span) -> instance
105
+
106
+ def initialize: (span: Span) -> void
107
+ end
108
+
41
109
  class Error < StandardError
42
110
  end
43
111
 
@@ -45,41 +113,72 @@ module SupervisorMachines
45
113
  class Escalated < Error
46
114
  end
47
115
 
48
- # The core's decision machine. A child count and a restart history are part
49
- # of its Rust type, so the count given here is dispatched to one of
50
- # `SUPPORTED_CHILDREN` monomorphised shapes.
116
+ # The core's `Supervisor`. A child count and a restart history are part of
117
+ # its Rust type, so the count given here is dispatched to one of
118
+ # `SUPPORTED_CHILDREN` monomorphised shapes, each keeping `HISTORY`
119
+ # restart instants. Malformed arguments raise `TypeError` or `RangeError`
120
+ # before the core is asked; mutating a frozen decider raises `FrozenError`.
51
121
  class Decider
52
- # Restart timestamps every shape keeps.
122
+ # Restart instants every shape keeps.
53
123
  HISTORY: Integer
54
124
 
125
+ # The most restarts an intensity may tolerate: `HISTORY - 1`.
126
+ MAX_RESTARTS: Integer
127
+
55
128
  # The child counts a decider can be built for. Anything else raises
56
- # `ArgumentError`.
129
+ # `RangeError`.
57
130
  SUPPORTED_CHILDREN: Array[Integer]
58
131
 
59
- def self.new: (
60
- children: Integer,
61
- strategy: strategy,
62
- restarts: Integer,
63
- window_ns: Integer
132
+ # `RangeError` for an unsupported child count or more restarts than
133
+ # `MAX_RESTARTS`.
134
+ def self.new: (Integer children, strategy strategy, Intensity intensity) -> instance
135
+
136
+ # A decider holding the restarts of `history` inside the window as of
137
+ # `now`, the newest `HISTORY` of them, every instant counted (two restarts
138
+ # at one instant restore as two). Not terminated.
139
+ def self.restore: (
140
+ Integer children,
141
+ strategy strategy,
142
+ Intensity intensity,
143
+ Array[Integer] history,
144
+ Integer now
64
145
  ) -> instance
65
146
 
66
- # Feeds one stopped child to the core and returns what it decided.
67
- def stopped: (
68
- index: Integer,
69
- policy: policy,
70
- exit: exit_kind,
71
- now_ns: Integer
72
- ) -> decision
147
+ # What to do about the child at `index`. `Restart` and `:escalate` record
148
+ # `now`; `:ignore`, `:already_escalated` and the refusal `:unknown_child`
149
+ # record nothing. Decided on a copy kept once the answer is built:
150
+ # `RuntimeError` when the decider changed meanwhile (outer call not
151
+ # applied).
152
+ def stopped: (Integer index, policy policy, exit_kind exit, Integer now) -> (decision | refusal)
153
+
154
+ # Counts a restart another process performed at `now`: `:recorded`, or
155
+ # `:outdated` (nothing changed) when a full history holds only newer ones.
156
+ def record_external_restart: (Integer now) -> recording
157
+
158
+ # Merges another process's history (any order), keeping the larger count
159
+ # of each instant; answers how many restarts were added. A repeat adds 0.
160
+ def absorb: (Array[Integer] history, Integer now) -> Integer
161
+
162
+ # Every restart instant held, oldest first. Frozen.
163
+ def history: () -> Array[Integer]
164
+
165
+ # The children a failure at `index` takes with it, or nil past the count.
166
+ def span: (Integer index) -> Span?
73
167
 
74
168
  def children: () -> Integer
75
169
 
76
170
  def strategy: () -> strategy
77
171
 
172
+ def intensity: () -> Intensity
173
+
78
174
  # True once the core has escalated, and true from then on.
79
175
  def terminated?: () -> bool
80
176
 
81
- # Restarts still inside the intensity window as of `now_ns`.
82
- def recent_restarts: (Integer) -> Integer
177
+ # Restarts still inside the intensity window as of `now`.
178
+ def recent_restarts: (Integer now) -> Integer
179
+
180
+ # How long to hold off a granted restart, in nanoseconds.
181
+ def restart_delay: (Integer base, Integer ceiling, Integer now) -> Integer
83
182
 
84
183
  def inspect: () -> String
85
184
  end
@@ -90,41 +189,56 @@ module SupervisorMachines
90
189
  # ended — `stopped` by its caller, `failed` by giving up.
91
190
  type state = :registering | :running | :stopped | :failed
92
191
 
93
- # Seconds a supervisor taking itself down waits for a killed child.
94
- ESCALATION_GRACE: Float
192
+ # Nanoseconds a supervisor taking itself down waits for a killed child.
193
+ ESCALATION_GRACE: Integer
95
194
 
96
195
  # Anything that can price the wait between a restart decision and the
97
- # respawn, which is `ChronoMachines::Executor` unless told otherwise.
196
+ # respawn, in Integer nanoseconds from an attempt (1..255) and a draw
197
+ # (0...2**64): a `chrono_machines` shape, BACKOFF unless told otherwise.
98
198
  interface _Backoff
99
- def next_delay: (attempt: Integer) -> Numeric?
199
+ def delay: (Integer attempt, Integer draw) -> Integer
100
200
  end
101
201
 
102
- # A registered child and whichever thread currently runs it.
103
- class Child < ::Struct[untyped]
104
- attr_accessor name: untyped
105
- attr_accessor policy: policy
106
- attr_accessor starter: ^() -> Thread
107
- attr_accessor thread: Thread?
108
- attr_accessor epoch: Integer
109
- attr_accessor done: bool
202
+ # A ChronoMachines::Exponential: 100 ms doubling to 10 s, full jitter.
203
+ BACKOFF: _Backoff
204
+
205
+ # A registered child and whichever thread currently runs it. Private;
206
+ # replaced under the tree's lock, never mutated.
207
+ class Child < ::Data
208
+ attr_reader name: untyped
209
+ attr_reader policy: policy
210
+ attr_reader starter: ^() -> Thread
211
+ attr_reader thread: Thread?
212
+ attr_reader epoch: Integer
213
+ attr_reader done: bool
214
+
215
+ def self.new: (untyped name, policy policy, (^() -> Thread)? starter, Thread? thread, Integer epoch,
216
+ bool done) -> instance
217
+
218
+ def initialize: (name: untyped, policy: policy, starter: (^() -> Thread)?, thread: Thread?, epoch: Integer,
219
+ done: bool) -> void
220
+
221
+ def with: (?thread: Thread?, ?epoch: Integer, ?done: bool) -> Child
110
222
  end
111
223
 
112
224
  attr_reader strategy: strategy
113
225
 
114
- # `restarts` within `window` seconds is the restart intensity.
115
- def initialize: (
116
- ?strategy: strategy,
117
- ?restarts: Integer,
118
- ?window: Float,
119
- ?backoff: _Backoff?
120
- ) -> void
226
+ attr_reader intensity: Intensity
227
+
228
+ # `TypeError` for a non-Symbol strategy or a non-Intensity, `RangeError`
229
+ # for an unknown strategy or more restarts than `Decider::MAX_RESTARTS`.
230
+ # `backoff:` and `supervise`'s `policy: :permanent` are the runtime's own
231
+ # keyword defaults: this class runs threads on top of the core rather
232
+ # than mirroring it (`Decider` is the mirror).
233
+ def initialize: (strategy strategy, Intensity intensity, ?backoff: _Backoff?) -> void
121
234
 
122
235
  # Registers a child under `name`. The block returns the `Thread` that runs
123
236
  # it, and is called again for every restart.
237
+ # `TypeError`/`RangeError` for a policy outside POLICIES.
124
238
  def supervise: (untyped name, ?policy: policy) { () -> Thread } -> self
125
239
 
126
240
  # Fixes the shape of the tree and starts every child in registration
127
- # order. Raises `ArgumentError` for a child count the core has no shape
241
+ # order. Raises `RangeError` for a child count the core has no shape
128
242
  # for, `Error` for a tree that is past registering, and whatever a starter
129
243
  # raised after taking the children already up back down.
130
244
  def start: () -> self
@@ -138,10 +252,11 @@ module SupervisorMachines
138
252
  def terminated?: () -> bool
139
253
 
140
254
  # Takes every running child down in reverse start order within `grace`
141
- # seconds, or all the time it needs when `grace` is nil. A tree still
142
- # registering has nothing to take down. Raises `Escalated` for a tree that
143
- # gave up, every time it is called.
144
- def stop: (?grace: Float?) -> self
255
+ # nanoseconds, or all the time it needs when `grace` is nil. A tree still
256
+ # registering has nothing to take down. `TypeError` for a non-Integer
257
+ # grace, `RangeError` for a negative one. Raises `Escalated` for a tree
258
+ # that gave up, every time it is called.
259
+ def stop: (?Integer? grace) -> self
145
260
 
146
261
  private
147
262
 
@@ -152,22 +267,23 @@ module SupervisorMachines
152
267
  def running?: () -> bool
153
268
  def monitor: () -> void
154
269
  def handle: (Integer index, Integer epoch, exit_kind ending) -> void
155
- def restart: (Range[Integer] span) -> void
156
- def respawn: (Range[Integer] span) -> String?
270
+ def restart: (Span span) -> void
271
+ def respawn: (Span span) -> String?
157
272
  def escalate: (?String reason) -> void
158
- def shutdown: (?Float grace) -> Array[Exception]
159
- def reap: (Thread thread, Float? remaining) -> Exception?
273
+ def shutdown: (?Integer? grace) -> Array[Exception]
274
+ def reap: (Thread thread, Integer? remaining) -> Exception?
160
275
  def spawn: (Integer index) -> void
161
276
 
162
277
  # Installs a started thread under the generation that asked for it, killing
163
278
  # it when the tree has moved past that generation.
164
279
  def install: (Integer index, Integer generation, Thread thread) -> void
165
- def retire: (Child child) -> Thread?
280
+ def retire: (Integer index) -> Thread?
166
281
  def watch: (Integer index, Integer epoch, Thread thread) -> void
167
282
  def escalation: () -> String
168
283
  def abandoned: () -> String
169
284
  def unstarted: (Exception error) -> String
170
285
  def monotonic_ns: () -> Integer
171
- def to_ns: (Float seconds) -> Integer
286
+ def grace_ns: (Integer nanos) -> Integer
287
+ def join_seconds: (Integer? nanos) -> Float?
172
288
  end
173
289
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: supervisor_machines
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.4
4
+ version: 0.4.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Abdelkader Boudih
@@ -15,28 +15,28 @@ dependencies:
15
15
  requirements:
16
16
  - - ">="
17
17
  - !ruby/object:Gem::Version
18
- version: 0.12.1
18
+ version: 0.13.0
19
19
  type: :runtime
20
20
  prerelease: false
21
21
  version_requirements: !ruby/object:Gem::Requirement
22
22
  requirements:
23
23
  - - ">="
24
24
  - !ruby/object:Gem::Version
25
- version: 0.12.1
25
+ version: 0.13.0
26
26
  - !ruby/object:Gem::Dependency
27
27
  name: deadline_machines
28
28
  requirement: !ruby/object:Gem::Requirement
29
29
  requirements:
30
30
  - - ">="
31
31
  - !ruby/object:Gem::Version
32
- version: '0.1'
32
+ version: 0.2.0
33
33
  type: :runtime
34
34
  prerelease: false
35
35
  version_requirements: !ruby/object:Gem::Requirement
36
36
  requirements:
37
37
  - - ">="
38
38
  - !ruby/object:Gem::Version
39
- version: '0.1'
39
+ version: 0.2.0
40
40
  - !ruby/object:Gem::Dependency
41
41
  name: rb_sys
42
42
  requirement: !ruby/object:Gem::Requirement
@@ -75,10 +75,12 @@ files:
75
75
  - ext/supervisor_machines_native/ffi/Cargo.toml
76
76
  - ext/supervisor_machines_native/ffi/extconf.rb
77
77
  - ext/supervisor_machines_native/ffi/src/decider.rs
78
+ - ext/supervisor_machines_native/ffi/src/init.rs
78
79
  - ext/supervisor_machines_native/ffi/src/lib.rs
79
80
  - lib/supervisor_machines.rb
80
81
  - lib/supervisor_machines/errors.rb
81
82
  - lib/supervisor_machines/supervisor.rb
83
+ - lib/supervisor_machines/values.rb
82
84
  - lib/supervisor_machines/version.rb
83
85
  - sig/supervisor_machines.rbs
84
86
  homepage: https://github.com/seuros/supervisor_machines