handoff_machines 0.8.3

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,291 @@
1
+ module HandoffMachines
2
+ VERSION: String
3
+ CAPACITY: Integer
4
+ WINDOW: Integer
5
+ PHASES: Array[Symbol]
6
+ REFUSALS: Array[Symbol]
7
+
8
+ # Integer nanoseconds on one monotonic clock, for instants (now, deadline)
9
+ # and spans (phase_budget) alike:
10
+ # Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond). A non-Integer
11
+ # raises TypeError. A span outside 0..2**64-1 raises RangeError; an instant
12
+ # is read over the whole `Duration` range, 0..Duration::MAX nanoseconds, so
13
+ # every deadline the coordinator answers reads back as `now`, and raises
14
+ # RangeError outside it.
15
+ type nanoseconds = Integer
16
+ type phase = :quiesce | :drain | :checkpoint | :activate | :rollback | :complete | :aborted
17
+ # Every symbol that means "this call was not honoured and changed nothing":
18
+ # one per core `Refusal` variant, no catch-all. Each method below lists
19
+ # exactly the ones it can answer.
20
+ type refusal = :full | :busy | :replica_busy | :same_replica | :exhausted | :clock_regressed
21
+ | :stale | :unknown | :out_of_phase | :wrong_replica | :behind_base | :beyond_drain
22
+ | :out_of_window | :unacked | :mismatch | :stale_token | :fence_required
23
+ # Refusals every acknowledgement can answer for its ticket and clock.
24
+ # :unknown is a ticket this coordinator never issued, which includes every
25
+ # ticket of another scope; :stale is one it issued that is no longer live.
26
+ # `fenced`, `activated` and `abort` also answer :unknown to a fencing token
27
+ # of another scope than the transfer's source token, after the clock and
28
+ # the ticket and before anything else is checked.
29
+ type ticket_refusal = :clock_regressed | :stale | :unknown
30
+ # Honoured acknowledgement, the core's `Acked`. Recorded: the transfer now
31
+ # stands at `phase`. Duplicate: an idempotent repeat of an acknowledgement
32
+ # the transfer already recorded with the same payload (or, for discarded,
33
+ # never owed); nothing changed, not even the clock, and the transfer still
34
+ # stands at `phase`. A replay with a different payload is :mismatch;
35
+ # :out_of_phase means not awaited and never recorded.
36
+ type acked = Recorded | Duplicate
37
+ # The core's `Recipient`: Replica(id), or :authority.
38
+ type recipient = Replica | :authority
39
+ # The core's `Action`: a Data per variant with a field, a symbol otherwise.
40
+ type action = :quiesce | Drain | Capture | Install | Fence | Activate | Resume | :discard
41
+
42
+ # Anything read as a fencing token: this gem's FencingToken, or the
43
+ # `lease_machines` gem's. A bare Integer is not one (TypeError).
44
+ interface _FencingToken
45
+ def raw: () -> Integer
46
+ end
47
+
48
+ # The lease core's `FencingToken`, which the handoff core re-exports.
49
+ class FencingToken < Data
50
+ # Scope in the top 16 bits above a sequence number counted from 1.
51
+ attr_reader raw: Integer
52
+ # TypeError for a non-Integer; RangeError outside 1..2**64-1 or when the
53
+ # sequence number is zero.
54
+ def self.new: (Integer raw) -> FencingToken
55
+ | (raw: Integer) -> FencingToken
56
+ def self.from_raw: (Integer raw) -> FencingToken
57
+ # The scope of the authority that issued this token.
58
+ def scope: () -> Integer
59
+ # nil across scopes: such tokens are not comparable.
60
+ def order: (_FencingToken other) -> (-1 | 0 | 1)?
61
+ # False across scopes.
62
+ def newer_than?: (_FencingToken other) -> bool
63
+ end
64
+
65
+ # Every Data value below is valid or does not exist: `new` checks it through
66
+ # the core constructor of the type it mirrors. TypeError for a value of the
67
+ # wrong type, RangeError for one the core would not build.
68
+
69
+ # The core's `Limits::new`: RangeError when `per_replica` is zero.
70
+ class Limits < Data
71
+ attr_reader phase_budget: nanoseconds
72
+ attr_reader per_replica: Integer
73
+ def self.new: (nanoseconds phase_budget, Integer per_replica) -> Limits
74
+ | (phase_budget: nanoseconds, per_replica: Integer) -> Limits
75
+ end
76
+
77
+ # The core's `Ticket::new`: RangeError for a generation with a zero sequence.
78
+ class Ticket < Data
79
+ attr_reader partition: Integer
80
+ # Never zero, never reused: the issuing coordinator's scope in the top
81
+ # 16 bits above a sequence counted from 1.
82
+ attr_reader generation: Integer
83
+ def self.new: (Integer partition, Integer generation) -> Ticket
84
+ | (partition: Integer, generation: Integer) -> Ticket
85
+ # The scope of the coordinator that issued this ticket.
86
+ def scope: () -> Integer
87
+ end
88
+
89
+ # The core's `Acked::recorded`: RangeError for :quiesce or a Symbol that is
90
+ # not a phase.
91
+ class Recorded < Data
92
+ attr_reader phase: phase
93
+ def self.new: (phase phase) -> Recorded
94
+ | (phase: phase) -> Recorded
95
+ def duplicate?: () -> false
96
+ end
97
+
98
+ # The core's `Acked::duplicate`: RangeError for :quiesce, :complete,
99
+ # :aborted or a Symbol that is not a phase.
100
+ class Duplicate < Data
101
+ attr_reader phase: phase
102
+ def self.new: (phase phase) -> Duplicate
103
+ | (phase: phase) -> Duplicate
104
+ def duplicate?: () -> true
105
+ end
106
+
107
+ # Integer ids in 0..2**64-1.
108
+ class Replica < Data
109
+ attr_reader id: Integer
110
+ def self.new: (Integer id) -> Replica
111
+ | (id: Integer) -> Replica
112
+ end
113
+
114
+ # Source: finish in-flight offsets below `until` and acknowledge each.
115
+ # Offsets and checkpoint ids are Integers in 0..2**64-1.
116
+ class Drain < Data
117
+ attr_reader until: Integer
118
+ def self.new: (Integer until_offset) -> Drain
119
+ | (until: Integer) -> Drain
120
+ end
121
+
122
+ # Source: capture a checkpoint at exactly `at`.
123
+ class Capture < Data
124
+ attr_reader at: Integer
125
+ def self.new: (Integer at) -> Capture
126
+ | (at: Integer) -> Capture
127
+ end
128
+
129
+ # Target: install the named checkpoint.
130
+ class Install < Data
131
+ attr_reader checkpoint: Integer
132
+ def self.new: (Integer checkpoint) -> Install
133
+ | (checkpoint: Integer) -> Install
134
+ end
135
+
136
+ # Authority: issue the target a token of `above`'s scope, strictly newer.
137
+ # Like Activate, Resume and Status, it keeps this gem's FencingToken: a
138
+ # sibling gem's token is converted on the way in, so `==` holds.
139
+ class Fence < Data
140
+ attr_reader above: FencingToken
141
+ def self.new: (_FencingToken above) -> Fence
142
+ | (above: _FencingToken) -> Fence
143
+ end
144
+
145
+ # Target: start serving under `token`.
146
+ class Activate < Data
147
+ attr_reader token: FencingToken
148
+ def self.new: (_FencingToken token) -> Activate
149
+ | (token: _FencingToken) -> Activate
150
+ end
151
+
152
+ # Source: resume serving; under `token` when the rollback was fenced.
153
+ class Resume < Data
154
+ attr_reader token: FencingToken?
155
+ def self.new: (_FencingToken? token) -> Resume
156
+ | (token: _FencingToken?) -> Resume
157
+ end
158
+
159
+ # The core's `Order::new`: RangeError unless only the authority is asked
160
+ # to fence and it is asked nothing else, or for a recipient Symbol other
161
+ # than :authority or an action Symbol other than :quiesce and :discard (a
162
+ # bare :resume included: it is `Resume.new(nil)`). TypeError for a ticket,
163
+ # replica or action Data that is not exactly this gem's class.
164
+ class Order < Data
165
+ attr_reader ticket: Ticket
166
+ attr_reader to: recipient
167
+ attr_reader action: action
168
+ def self.new: (Ticket ticket, recipient to, action action) -> Order
169
+ | (ticket: Ticket, to: recipient, action: action) -> Order
170
+ end
171
+
172
+ # The core's `Status::checked`: an issued ticket, two different replicas,
173
+ # a phase that is not final and only what that phase has recorded; during
174
+ # the drain, a quiesce point above `base`. The
175
+ # deadline is now + phase_budget, saturating at Duration::MAX.
176
+ class Status < Data
177
+ attr_reader ticket: Ticket
178
+ attr_reader source: Integer
179
+ attr_reader target: Integer
180
+ attr_reader phase: phase
181
+ attr_reader base: Integer
182
+ attr_reader until: Integer?
183
+ attr_reader checkpoint: Integer?
184
+ attr_reader token: FencingToken?
185
+ attr_reader deadline: nanoseconds
186
+ def self.new: (Ticket ticket, Integer source, Integer target, phase phase, Integer base, Integer? until_offset,
187
+ Integer? checkpoint, _FencingToken? token, nanoseconds deadline) -> Status
188
+ | (ticket: Ticket, source: Integer, target: Integer, phase: phase, base: Integer, until: Integer?,
189
+ checkpoint: Integer?, token: _FencingToken?, deadline: nanoseconds) -> Status
190
+ end
191
+
192
+ # The core's `Handoff<16, 4>`. Honoured answers come first in every return
193
+ # type, then the refusals that method can answer.
194
+ class Handoff
195
+ # A fresh generation namespace in scope zero.
196
+ def self.new: (Limits limits) -> Handoff
197
+ # A fresh generation namespace whose generations carry `scope`, an Integer
198
+ # in 0..65_535 (TypeError for a non-Integer, RangeError outside the range).
199
+ def self.with_scope: (Limits limits, Integer scope) -> Handoff
200
+ # Generations of `scope` above `last_generation`, what #generation answered
201
+ # before the restart (nil: nothing issued, an equal fresh coordinator).
202
+ # RangeError when `last_generation` is not a generation of `scope`: a value
203
+ # from another scope, one that lost its top bits, or a bare 0.
204
+ def self.restored: (Limits limits, Integer scope, Integer? last_generation) -> Handoff
205
+ def scope: () -> Integer
206
+ def limits: () -> Limits
207
+ # `source_token`'s scope is the transfer's token scope.
208
+ def start: (Integer partition, Integer source, Integer target, Integer base, _FencingToken source_token,
209
+ nanoseconds now)
210
+ -> (Ticket | :clock_regressed | :same_replica | :busy | :full | :replica_busy | :exhausted)
211
+ # Recorded(:drain | :checkpoint), or Duplicate.
212
+ def quiesced: (Ticket ticket, Integer replica, Integer until_offset, nanoseconds now)
213
+ -> (acked | ticket_refusal | :out_of_phase | :wrong_replica | :behind_base | :mismatch)
214
+ # Recorded(:drain | :checkpoint), or Duplicate.
215
+ def drained: (Ticket ticket, Integer replica, Integer offset, nanoseconds now)
216
+ -> (acked | ticket_refusal | :out_of_phase | :wrong_replica | :beyond_drain | :out_of_window)
217
+ # Recorded(:drain), or Duplicate.
218
+ def committed: (Ticket ticket, Integer replica, Integer offset, nanoseconds now)
219
+ -> (acked | ticket_refusal | :out_of_phase | :wrong_replica | :unacked)
220
+ # Recorded(:checkpoint), or Duplicate.
221
+ def captured: (Ticket ticket, Integer replica, Integer checkpoint, nanoseconds now)
222
+ -> (acked | ticket_refusal | :out_of_phase | :wrong_replica | :mismatch)
223
+ # Recorded(:activate), or Duplicate.
224
+ def installed: (Ticket ticket, Integer replica, Integer checkpoint, nanoseconds now)
225
+ -> (acked | ticket_refusal | :out_of_phase | :wrong_replica | :mismatch)
226
+ # Recorded(:activate), or Duplicate. In order, after the ticket refusals:
227
+ # :unknown for a token of another scope than the source token's; then
228
+ # :mismatch when a different token is recorded; :out_of_phase;
229
+ # :stale_token for one not newer than the source token.
230
+ def fenced: (Ticket ticket, _FencingToken token, nanoseconds now)
231
+ -> (acked | ticket_refusal | :mismatch | :out_of_phase | :stale_token)
232
+ # Recorded(:complete); never Duplicate, a repeat is :stale. In order,
233
+ # after the ticket refusals: :unknown for a token of another scope;
234
+ # :out_of_phase; :wrong_replica; :mismatch.
235
+ def activated: (Ticket ticket, Integer replica, _FencingToken token, nanoseconds now)
236
+ -> (Recorded | ticket_refusal | :out_of_phase | :wrong_replica | :mismatch)
237
+ # Recorded(:rollback), or Duplicate. `token` is nil for an unfenced abort.
238
+ # In order, after the ticket refusals: :unknown for a token of another
239
+ # scope; :mismatch during a rollback under another token; :stale_token
240
+ # for one not newer than every token the transfer knows; :fence_required.
241
+ def abort: (Ticket ticket, _FencingToken? token, nanoseconds now)
242
+ -> (acked | ticket_refusal | :mismatch | :stale_token | :fence_required)
243
+ # Recorded(:rollback | :aborted), or Duplicate.
244
+ def resumed: (Ticket ticket, Integer replica, nanoseconds now)
245
+ -> (acked | ticket_refusal | :out_of_phase | :wrong_replica)
246
+ # Recorded(:rollback | :aborted), or Duplicate.
247
+ def discarded: (Ticket ticket, Integer replica, nanoseconds now)
248
+ -> (acked | ticket_refusal | :out_of_phase | :wrong_replica)
249
+ def status: (Integer partition) -> Status?
250
+ def orders: (Integer from, Integer limit) -> [Array[Order], Integer]
251
+ def outstanding: (Ticket ticket, Integer from, Integer limit)
252
+ -> (Array[Integer] | :stale | :unknown | :out_of_phase)
253
+ def overdue: (nanoseconds now, Integer from, Integer limit) -> [Array[Ticket], Integer]
254
+ def active: () -> Integer
255
+ # The highest generation issued, scope included; nil before the first.
256
+ def generation: () -> Integer?
257
+
258
+ private
259
+
260
+ private def self.native_with_scope: (Limits, Integer) -> Handoff
261
+ private def self.native_restored: (Limits, Integer, Integer?) -> Handoff
262
+ private def self.native_scope_of: (Ticket) -> Integer
263
+ def native_limits: () -> [Integer, Integer]
264
+ def order: (Integer, Integer, Integer | :authority, Symbol, Integer?) -> Order
265
+ def action: (Symbol, Integer?) -> action
266
+ def native_status: (Integer) -> [Array[untyped], Array[untyped]]?
267
+ def native_orders: (Integer, Integer) -> [Array[Array[untyped]], Integer]
268
+ def native_overdue: (Integer, Integer, Integer) -> [Array[[Integer, Integer]], Integer]
269
+ end
270
+
271
+ private
272
+
273
+ ACTIONS: Hash[Symbol, singleton(Data)]
274
+ TOKENED: Array[Symbol]
275
+ private def self.native_raw: (Integer) -> nil
276
+ private def self.native_token_scope: (_FencingToken) -> Integer
277
+ private def self.native_token_order: (_FencingToken, _FencingToken) -> (-1 | 0 | 1)?
278
+ private def self.native_token_newer: (_FencingToken, _FencingToken) -> bool
279
+ private def self.__limits: (Integer, Integer) -> nil
280
+ private def self.__ticket: (Integer, Integer) -> nil
281
+ private def self.__recorded: (phase) -> nil
282
+ private def self.__duplicate: (phase) -> nil
283
+ private def self.__replica: (Integer) -> nil
284
+ private def self.__drain: (Integer) -> nil
285
+ private def self.__capture: (Integer) -> nil
286
+ private def self.__install: (Integer) -> nil
287
+ private def self.__token: (_FencingToken) -> FencingToken
288
+ private def self.__order: (Ticket, recipient, action) -> nil
289
+ private def self.__status: (Ticket, Integer, Integer, phase, Integer, Integer?, Integer?, _FencingToken?, Integer)
290
+ -> FencingToken?
291
+ end
metadata ADDED
@@ -0,0 +1,93 @@
1
+ --- !ruby/object:Gem::Specification
2
+ name: handoff_machines
3
+ version: !ruby/object:Gem::Version
4
+ version: 0.8.3
5
+ platform: ruby
6
+ authors:
7
+ - Abdelkader Boudih
8
+ bindir: bin
9
+ cert_chain: []
10
+ date: 1980-01-02 00:00:00.000000000 Z
11
+ dependencies:
12
+ - !ruby/object:Gem::Dependency
13
+ name: rb_sys
14
+ requirement: !ruby/object:Gem::Requirement
15
+ requirements:
16
+ - - "~>"
17
+ - !ruby/object:Gem::Version
18
+ version: '0.9'
19
+ - - ">="
20
+ - !ruby/object:Gem::Version
21
+ version: 0.9.130
22
+ type: :runtime
23
+ prerelease: false
24
+ version_requirements: !ruby/object:Gem::Requirement
25
+ requirements:
26
+ - - "~>"
27
+ - !ruby/object:Gem::Version
28
+ version: '0.9'
29
+ - - ">="
30
+ - !ruby/object:Gem::Version
31
+ version: 0.9.130
32
+ description: 'Moves a partition between replicas one acknowledged phase at a time:
33
+ quiesce, drain, checkpoint, then activate the target under a newer fencing token.
34
+ Bound to Ruby from the no_std handoff-machines crate: the coordinator policy only,
35
+ not a rebalancer or a lease authority.'
36
+ email:
37
+ - oss@seuros.com
38
+ executables: []
39
+ extensions:
40
+ - ext/handoff_machines_native/extconf.rb
41
+ extra_rdoc_files: []
42
+ files:
43
+ - CHANGELOG.md
44
+ - Cargo.lock
45
+ - Cargo.toml
46
+ - LICENSE.txt
47
+ - README.md
48
+ - ext/handoff_machines_native/core/CHANGELOG.md
49
+ - ext/handoff_machines_native/core/Cargo.toml
50
+ - ext/handoff_machines_native/core/README.md
51
+ - ext/handoff_machines_native/core/src/iter.rs
52
+ - ext/handoff_machines_native/core/src/lib.rs
53
+ - ext/handoff_machines_native/core/src/refusal.rs
54
+ - ext/handoff_machines_native/core/src/transfer.rs
55
+ - ext/handoff_machines_native/core/src/types.rs
56
+ - ext/handoff_machines_native/extconf.rb
57
+ - ext/handoff_machines_native/ffi/Cargo.toml
58
+ - ext/handoff_machines_native/ffi/extconf.rb
59
+ - ext/handoff_machines_native/ffi/src/classes.rs
60
+ - ext/handoff_machines_native/ffi/src/handoff.rs
61
+ - ext/handoff_machines_native/ffi/src/init.rs
62
+ - ext/handoff_machines_native/ffi/src/lib.rs
63
+ - ext/handoff_machines_native/ffi/src/names.rs
64
+ - ext/handoff_machines_native/ffi/src/values.rs
65
+ - lib/handoff_machines.rb
66
+ - lib/handoff_machines/version.rb
67
+ - sig/handoff_machines.rbs
68
+ homepage: https://github.com/seuros/handoff_machines
69
+ licenses:
70
+ - MIT
71
+ metadata:
72
+ source_code_uri: https://github.com/seuros/handoff_machines
73
+ rubygems_mfa_required: 'true'
74
+ cargo_crate_name: handoff_machines_native
75
+ cargo_manifest_path: ext/handoff_machines_native/ffi/Cargo.toml
76
+ rdoc_options: []
77
+ require_paths:
78
+ - lib
79
+ required_ruby_version: !ruby/object:Gem::Requirement
80
+ requirements:
81
+ - - ">="
82
+ - !ruby/object:Gem::Version
83
+ version: 4.0.0
84
+ required_rubygems_version: !ruby/object:Gem::Requirement
85
+ requirements:
86
+ - - ">="
87
+ - !ruby/object:Gem::Version
88
+ version: '0'
89
+ requirements: []
90
+ rubygems_version: 4.0.20
91
+ specification_version: 4
92
+ summary: Partition handoff phases with generation-tagged acknowledgements for Ruby
93
+ test_files: []