refresh_machines 0.7.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.
- checksums.yaml +7 -0
- data/CHANGELOG.md +109 -0
- data/Cargo.lock +325 -0
- data/Cargo.toml +29 -0
- data/LICENSE.txt +21 -0
- data/README.md +352 -0
- data/ext/refresh_machines_native/core/CHANGELOG.md +77 -0
- data/ext/refresh_machines_native/core/Cargo.toml +21 -0
- data/ext/refresh_machines_native/core/README.md +175 -0
- data/ext/refresh_machines_native/core/src/decision.rs +83 -0
- data/ext/refresh_machines_native/core/src/lead.rs +123 -0
- data/ext/refresh_machines_native/core/src/lease.rs +42 -0
- data/ext/refresh_machines_native/core/src/lib.rs +564 -0
- data/ext/refresh_machines_native/core/src/policy.rs +79 -0
- data/ext/refresh_machines_native/core/src/refusal.rs +47 -0
- data/ext/refresh_machines_native/extconf.rb +2 -0
- data/ext/refresh_machines_native/ffi/Cargo.toml +22 -0
- data/ext/refresh_machines_native/ffi/extconf.rb +14 -0
- data/ext/refresh_machines_native/ffi/src/answers.rs +117 -0
- data/ext/refresh_machines_native/ffi/src/init.rs +66 -0
- data/ext/refresh_machines_native/ffi/src/lib.rs +389 -0
- data/ext/refresh_machines_native/ffi/src/values.rs +124 -0
- data/lib/refresh_machines/version.rb +5 -0
- data/lib/refresh_machines.rb +113 -0
- data/sig/refresh_machines.rbs +179 -0
- metadata +90 -0
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
//! Private hooks that hold every `RefreshMachines` Data value to what the
|
|
2
|
+
//! core accepts, whether the gem built it or the caller did.
|
|
3
|
+
|
|
4
|
+
use magnus::{Error, Ruby, Value, value::ReprValue};
|
|
5
|
+
use matryona_machines::ruby::{
|
|
6
|
+
Choice, Refused, Symbols, duration, instant, integer, symbol_or_fields_why,
|
|
7
|
+
};
|
|
8
|
+
use refresh_machines::{Decision, FlightId, Lease, Notification, WaiterId};
|
|
9
|
+
|
|
10
|
+
use crate::Refusals;
|
|
11
|
+
use crate::answers::{Outcomes, Revalidations, classes};
|
|
12
|
+
|
|
13
|
+
/// `__policy`: the three windows `Policy::new` takes, each Integer
|
|
14
|
+
/// nanoseconds in `0..2**64-1`, named for its field.
|
|
15
|
+
pub fn policy(fresh_for: Value, revalidate: Value, if_error: Value) -> Result<(), Error> {
|
|
16
|
+
duration(fresh_for, "fresh_for")?;
|
|
17
|
+
duration(revalidate, "stale_while_revalidate")?;
|
|
18
|
+
duration(if_error, "stale_if_error").map(drop)
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/// `__age`: a `Fresh` or `Stale` age, Integer nanoseconds a core `Duration`
|
|
22
|
+
/// holds, up to `Duration::MAX`: an age the core answers may pass the
|
|
23
|
+
/// argument range because sums saturate instead of wrapping.
|
|
24
|
+
pub fn age(value: Value) -> Result<(), Error> {
|
|
25
|
+
instant(value, "age").map(drop)
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/// `__until`: a `Backoff`'s instant, over the whole `Duration` range like
|
|
29
|
+
/// an age.
|
|
30
|
+
pub fn until(value: Value) -> Result<(), Error> {
|
|
31
|
+
instant(value, "until").map(drop)
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/// `__lease`: what `Lease::from_raw` accepts.
|
|
35
|
+
pub fn lease(ruby: &Ruby, value: Value) -> Result<Value, Error> {
|
|
36
|
+
lease_id(ruby, integer(value, "lease")?).map(|_| value)
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/// `__wait`: what `Decision::wait` accepts.
|
|
40
|
+
pub fn wait(ruby: &Ruby, waiter: Value, flight: Value) -> Result<(), Error> {
|
|
41
|
+
let (waiter, flight) = (integer(waiter, "waiter")?, integer(flight, "flight")?);
|
|
42
|
+
let (waiter, flight) = (waiter_id(ruby, waiter)?, flight_id(ruby, flight)?);
|
|
43
|
+
Decision::wait(waiter, flight)
|
|
44
|
+
.map(|_| ())
|
|
45
|
+
.ok_or_else(|| not_together(ruby))
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/// `__notification`: what `Notification::new` accepts.
|
|
49
|
+
pub fn notification(
|
|
50
|
+
ruby: &Ruby,
|
|
51
|
+
waiter: Value,
|
|
52
|
+
flight: Value,
|
|
53
|
+
key: Value,
|
|
54
|
+
outcome: Value,
|
|
55
|
+
) -> Result<(), Error> {
|
|
56
|
+
let (waiter, flight) = (integer(waiter, "waiter")?, integer(flight, "flight")?);
|
|
57
|
+
let key = integer(key, "key")?;
|
|
58
|
+
let outcome = Outcomes::parse(ruby, outcome)?;
|
|
59
|
+
let (waiter, flight) = (waiter_id(ruby, waiter)?, flight_id(ruby, flight)?);
|
|
60
|
+
Notification::new(waiter, flight, key, outcome)
|
|
61
|
+
.map(|_| ())
|
|
62
|
+
.ok_or_else(|| not_together(ruby))
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
fn not_together(ruby: &Ruby) -> Error {
|
|
66
|
+
Error::new(
|
|
67
|
+
ruby.exception_range_error(),
|
|
68
|
+
"the waiter must be of the flight's scope and issued after it",
|
|
69
|
+
)
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/// `__refusal`: the symbol of a refusal variant.
|
|
73
|
+
pub fn refusal(ruby: &Ruby, value: Value) -> Result<Value, Error> {
|
|
74
|
+
Refusals::parse(ruby, value).map(|_| value)
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
const NOT_ONE: &str = "revalidation must be a Lead, :in_flight, a Backoff or an Unavailable";
|
|
78
|
+
|
|
79
|
+
/// `__revalidation`: what a `Stale#revalidation` may hold, read natively
|
|
80
|
+
/// because `case`/`===` takes a subclass: `:in_flight`, or exactly a `Lead`,
|
|
81
|
+
/// `Backoff` or `Unavailable` whose fields are checked again (`Marshal.load`
|
|
82
|
+
/// skips `initialize`). `RangeError` naming any other Symbol (`unknown
|
|
83
|
+
/// revalidation :nope`), `TypeError` for anything else.
|
|
84
|
+
pub fn revalidation(ruby: &Ruby, value: Value) -> Result<Value, Error> {
|
|
85
|
+
let classes = classes(ruby)?;
|
|
86
|
+
let one_of = [
|
|
87
|
+
classes.lead.get(ruby),
|
|
88
|
+
classes.backoff.get(ruby),
|
|
89
|
+
classes.unavailable.get(ruby),
|
|
90
|
+
];
|
|
91
|
+
// Each class has one member, read from the struct.
|
|
92
|
+
let read = symbol_or_fields_why(ruby, value, Revalidations, &one_of, |why| match why {
|
|
93
|
+
Refused::UnknownSymbol(symbol) => format!("unknown revalidation {}", symbol.inspect()),
|
|
94
|
+
_ => NOT_ONE.into(),
|
|
95
|
+
})?;
|
|
96
|
+
match read {
|
|
97
|
+
Choice::Symbol(_) => Ok(()),
|
|
98
|
+
Choice::Struct(0, [field]) => self::lease(ruby, field).map(drop),
|
|
99
|
+
Choice::Struct(1, [field]) => self::until(field),
|
|
100
|
+
Choice::Struct(_, [field]) => refusal(ruby, field).map(drop),
|
|
101
|
+
}?;
|
|
102
|
+
Ok(value)
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/// The lease an Integer names, `RangeError` for a sequence of zero.
|
|
106
|
+
pub fn lease_id(ruby: &Ruby, raw: u64) -> Result<Lease, Error> {
|
|
107
|
+
Lease::from_raw(raw).ok_or_else(|| zero_sequence(ruby, "lease"))
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/// The waiter id an Integer names, `RangeError` for a sequence of zero.
|
|
111
|
+
pub fn waiter_id(ruby: &Ruby, raw: u64) -> Result<WaiterId, Error> {
|
|
112
|
+
WaiterId::from_raw(raw).ok_or_else(|| zero_sequence(ruby, "waiter"))
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
fn flight_id(ruby: &Ruby, raw: u64) -> Result<FlightId, Error> {
|
|
116
|
+
FlightId::from_raw(raw).ok_or_else(|| zero_sequence(ruby, "flight"))
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
fn zero_sequence(ruby: &Ruby, kind: &str) -> Error {
|
|
120
|
+
Error::new(
|
|
121
|
+
ruby.exception_range_error(),
|
|
122
|
+
format!("a {kind} id's sequence (the low 48 bits) must not be zero"),
|
|
123
|
+
)
|
|
124
|
+
}
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require_relative 'refresh_machines/version'
|
|
4
|
+
|
|
5
|
+
# Every Data value below is held to what the core accepts, whether the gem
|
|
6
|
+
# returned it or it was built by hand: TypeError for the wrong type,
|
|
7
|
+
# RangeError for a value outside the core's domain.
|
|
8
|
+
module RefreshMachines
|
|
9
|
+
# Freshness rules for one value, as three spans in Integer nanoseconds.
|
|
10
|
+
# Both stale windows open when `fresh_for` ends. `state`,
|
|
11
|
+
# `while_revalidate?` and `if_error?` are native and take an age.
|
|
12
|
+
#
|
|
13
|
+
# Every instant and span in this gem is Integer nanoseconds: `now` as read
|
|
14
|
+
# from `Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)`, and
|
|
15
|
+
# every age, window, `lead_for`, `retry_after` and `Backoff#until`.
|
|
16
|
+
# Span arguments, and the Policy windows, are in 0..2**64-1; `now` is in
|
|
17
|
+
# 0..`Duration::MAX`, so every instant the refresher answers reads back as
|
|
18
|
+
# `now`. An age or instant the core answers (Fresh, Stale, Backoff) may be
|
|
19
|
+
# past 2**64-1, up to `Duration::MAX`, because sums saturate instead of
|
|
20
|
+
# wrapping.
|
|
21
|
+
Policy = Data.define(:fresh_for, :stale_while_revalidate, :stale_if_error) do
|
|
22
|
+
def initialize(fresh_for:, stale_while_revalidate:, stale_if_error:)
|
|
23
|
+
RefreshMachines.__send__(:__policy, fresh_for, stale_while_revalidate, stale_if_error)
|
|
24
|
+
super
|
|
25
|
+
end
|
|
26
|
+
end
|
|
27
|
+
# Serve the cached value.
|
|
28
|
+
Fresh = Data.define(:age) do
|
|
29
|
+
def initialize(age:)
|
|
30
|
+
RefreshMachines.__send__(:__age, age)
|
|
31
|
+
super
|
|
32
|
+
end
|
|
33
|
+
end
|
|
34
|
+
# Serve the cached value, stale. `revalidation` says who refreshes it: a
|
|
35
|
+
# Lead (you do), :in_flight (someone else is), a Backoff (nobody until then)
|
|
36
|
+
# or an Unavailable (a refresh is due but could not be registered).
|
|
37
|
+
Stale = Data.define(:age, :revalidation) do
|
|
38
|
+
def initialize(age:, revalidation:)
|
|
39
|
+
RefreshMachines.__send__(:__age, age)
|
|
40
|
+
RefreshMachines.__send__(:__revalidation, revalidation)
|
|
41
|
+
super
|
|
42
|
+
end
|
|
43
|
+
end
|
|
44
|
+
# Nothing servable: fetch, then report with `lease`, a lease id (its
|
|
45
|
+
# sequence, the low 48 bits, is never zero).
|
|
46
|
+
Fetch = Data.define(:lease) do
|
|
47
|
+
def initialize(lease:)
|
|
48
|
+
RefreshMachines.__send__(:__lease, lease)
|
|
49
|
+
super
|
|
50
|
+
end
|
|
51
|
+
end
|
|
52
|
+
# Nothing servable and someone is already fetching: park under the `waiter`
|
|
53
|
+
# id (issued after `flight`, in its scope). `flight` names the refresh being shared: what `Refresher#flight`
|
|
54
|
+
# answers for the key's live lease, and the `flight` of the notification to come.
|
|
55
|
+
Wait = Data.define(:waiter, :flight) do
|
|
56
|
+
def initialize(waiter:, flight:)
|
|
57
|
+
RefreshMachines.__send__(:__wait, waiter, flight)
|
|
58
|
+
super
|
|
59
|
+
end
|
|
60
|
+
end
|
|
61
|
+
# Stale#revalidation: refresh in the background and report with `lease`.
|
|
62
|
+
Lead = Data.define(:lease) do
|
|
63
|
+
def initialize(lease:)
|
|
64
|
+
RefreshMachines.__send__(:__lease, lease)
|
|
65
|
+
super
|
|
66
|
+
end
|
|
67
|
+
end
|
|
68
|
+
# Stale#revalidation: the last refresh failed and asked for quiet `until` then.
|
|
69
|
+
Backoff = Data.define(:until) do
|
|
70
|
+
def initialize(until:)
|
|
71
|
+
RefreshMachines.__send__(:__until, binding.local_variable_get(:until))
|
|
72
|
+
super
|
|
73
|
+
end
|
|
74
|
+
end
|
|
75
|
+
# Stale#revalidation: a refresh is due but was not registered; `refusal` is
|
|
76
|
+
# the reason, a refusal symbol. The decision is still honoured: serve the
|
|
77
|
+
# stale value.
|
|
78
|
+
Unavailable = Data.define(:refusal) do
|
|
79
|
+
def initialize(refusal:)
|
|
80
|
+
RefreshMachines.__send__(:__refusal, refusal)
|
|
81
|
+
super
|
|
82
|
+
end
|
|
83
|
+
end
|
|
84
|
+
# One waiter to wake. `flight` names the refresh that settled, see
|
|
85
|
+
# `Refresher#flight`; `waiter` is of its scope and issued after it.
|
|
86
|
+
# `outcome` is :completed or :abandoned.
|
|
87
|
+
Notification = Data.define(:waiter, :flight, :key, :outcome) do
|
|
88
|
+
def initialize(waiter:, flight:, key:, outcome:)
|
|
89
|
+
RefreshMachines.__send__(:__notification, waiter, flight, key, outcome)
|
|
90
|
+
super
|
|
91
|
+
end
|
|
92
|
+
end
|
|
93
|
+
end
|
|
94
|
+
|
|
95
|
+
# Native is required: no algorithm fallback. It validates and builds the Data
|
|
96
|
+
# values above and adds the Policy predicates, so they must exist first.
|
|
97
|
+
require 'refresh_machines_native/refresh_machines_native'
|
|
98
|
+
|
|
99
|
+
module RefreshMachines
|
|
100
|
+
private_class_method :__policy, :__age, :__until, :__lease, :__wait, :__notification, :__refusal, :__revalidation
|
|
101
|
+
|
|
102
|
+
# The values are sealed. `initialize` is where each validates, and a
|
|
103
|
+
# subclass could override it, or `allocate` build an instance that never ran
|
|
104
|
+
# it: subclassing raises TypeError and `allocate` is gone. Sealing stops
|
|
105
|
+
# accidents, not reflection (a named subclass's constant is bound before
|
|
106
|
+
# `inherited` raises; `Marshal.load` skips `initialize`), so the native side
|
|
107
|
+
# is the authority: a value it reads (a Policy, a Stale's revalidation) must
|
|
108
|
+
# be exactly its class, and its fields are checked again.
|
|
109
|
+
[Policy, Fresh, Stale, Fetch, Wait, Lead, Backoff, Unavailable, Notification].each do |value|
|
|
110
|
+
value.singleton_class.undef_method(:allocate)
|
|
111
|
+
value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
|
|
112
|
+
end
|
|
113
|
+
end
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
module RefreshMachines
|
|
2
|
+
VERSION: String
|
|
3
|
+
|
|
4
|
+
# Every instant (`now`, `Backoff#until`) and span (ages, policy windows,
|
|
5
|
+
# `lead_for`, `retry_after`) is Integer nanoseconds. A span argument must be
|
|
6
|
+
# in 0..2**64-1; a `now` argument may be anything in 0..Duration::MAX, so
|
|
7
|
+
# every instant the refresher answers (a `Backoff#until` past 2**64-1
|
|
8
|
+
# included) reads back as `now`. A returned sum may be larger than 2**64-1,
|
|
9
|
+
# up to the core's Duration::MAX; it never wraps.
|
|
10
|
+
#
|
|
11
|
+
# Every Data value validates when built, by the gem or by hand: TypeError
|
|
12
|
+
# for the wrong type, RangeError for a value the core rejects.
|
|
13
|
+
type state = :fresh | :stale | :expired
|
|
14
|
+
# Refusals: the call was not honoured and changed nothing. Every reason has
|
|
15
|
+
# its own symbol; there is no catch-all.
|
|
16
|
+
type refusal = :time_regressed | :zero_lead | :entries_full | :flights_full
|
|
17
|
+
| :waiters_full | :exhausted | :stale
|
|
18
|
+
|
|
19
|
+
# The scope (0..65_535) a lease, waiter or flight id was issued under: the
|
|
20
|
+
# top 16 bits. Use it to route an id to the refresher that issued it.
|
|
21
|
+
def self.scope_of: (Integer id) -> Integer
|
|
22
|
+
|
|
23
|
+
# Private native checks behind the Data values: TypeError for the wrong
|
|
24
|
+
# type, RangeError for a value the core rejects. The value-returning ones
|
|
25
|
+
# answer their argument unchanged.
|
|
26
|
+
private def self.__policy: (Integer fresh_for, Integer stale_while_revalidate, Integer stale_if_error) -> nil
|
|
27
|
+
private def self.__age: (Integer age) -> nil
|
|
28
|
+
private def self.__until: (Integer until_) -> nil
|
|
29
|
+
private def self.__lease: (Integer lease) -> Integer
|
|
30
|
+
private def self.__wait: (Integer waiter, Integer flight) -> nil
|
|
31
|
+
private def self.__notification: (Integer waiter, Integer flight, Integer key, Notification::outcome outcome) -> nil
|
|
32
|
+
private def self.__refusal: (refusal refusal) -> refusal
|
|
33
|
+
private def self.__revalidation: (revalidation revalidation) -> revalidation
|
|
34
|
+
|
|
35
|
+
class Policy < Data
|
|
36
|
+
attr_reader fresh_for: Integer
|
|
37
|
+
attr_reader stale_while_revalidate: Integer
|
|
38
|
+
attr_reader stale_if_error: Integer
|
|
39
|
+
def self.new: (Integer fresh_for, Integer stale_while_revalidate, Integer stale_if_error) -> Policy
|
|
40
|
+
| (fresh_for: Integer, stale_while_revalidate: Integer, stale_if_error: Integer) -> Policy
|
|
41
|
+
def state: (Integer age) -> state
|
|
42
|
+
def while_revalidate?: (Integer age) -> bool
|
|
43
|
+
def if_error?: (Integer age) -> bool
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
# Ages and instants answered by the core: Integer nanoseconds in
|
|
47
|
+
# 0..Duration::MAX (about 1.8e28).
|
|
48
|
+
class Fresh < Data
|
|
49
|
+
attr_reader age: Integer
|
|
50
|
+
def self.new: (Integer age) -> Fresh
|
|
51
|
+
| (age: Integer) -> Fresh
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
# Who refreshes a stale value that is being served.
|
|
55
|
+
type revalidation = Lead | :in_flight | Backoff | Unavailable
|
|
56
|
+
|
|
57
|
+
class Stale < Data
|
|
58
|
+
attr_reader age: Integer
|
|
59
|
+
attr_reader revalidation: revalidation
|
|
60
|
+
def self.new: (Integer age, revalidation revalidation) -> Stale
|
|
61
|
+
| (age: Integer, revalidation: revalidation) -> Stale
|
|
62
|
+
end
|
|
63
|
+
|
|
64
|
+
# Ids are Integers: lease ids, waiter ids and flight ids, all from the one
|
|
65
|
+
# sequence of their refresher, so no two ids of a refresher are equal. An id
|
|
66
|
+
# whose sequence (the low 48 bits) is zero raises RangeError, in a Data
|
|
67
|
+
# value and as an argument alike.
|
|
68
|
+
class Fetch < Data
|
|
69
|
+
attr_reader lease: Integer
|
|
70
|
+
def self.new: (Integer lease) -> Fetch
|
|
71
|
+
| (lease: Integer) -> Fetch
|
|
72
|
+
end
|
|
73
|
+
|
|
74
|
+
# The waiter is of the flight's scope and issued after it, else RangeError.
|
|
75
|
+
class Wait < Data
|
|
76
|
+
attr_reader waiter: Integer
|
|
77
|
+
attr_reader flight: Integer
|
|
78
|
+
def self.new: (Integer waiter, Integer flight) -> Wait
|
|
79
|
+
| (waiter: Integer, flight: Integer) -> Wait
|
|
80
|
+
end
|
|
81
|
+
|
|
82
|
+
class Lead < Data
|
|
83
|
+
attr_reader lease: Integer
|
|
84
|
+
def self.new: (Integer lease) -> Lead
|
|
85
|
+
| (lease: Integer) -> Lead
|
|
86
|
+
end
|
|
87
|
+
|
|
88
|
+
class Backoff < Data
|
|
89
|
+
attr_reader until: Integer
|
|
90
|
+
def self.new: (Integer until_) -> Backoff
|
|
91
|
+
| (until: Integer) -> Backoff
|
|
92
|
+
end
|
|
93
|
+
|
|
94
|
+
# Why the refresh was not registered: any refusal symbol (RangeError for
|
|
95
|
+
# another symbol). `decide` answers it with :flights_full or :exhausted.
|
|
96
|
+
class Unavailable < Data
|
|
97
|
+
attr_reader refusal: refusal
|
|
98
|
+
def self.new: (refusal refusal) -> Unavailable
|
|
99
|
+
| (refusal: refusal) -> Unavailable
|
|
100
|
+
end
|
|
101
|
+
|
|
102
|
+
# The waiter is of the flight's scope and issued after it, else RangeError.
|
|
103
|
+
class Notification < Data
|
|
104
|
+
type outcome = :completed | :abandoned
|
|
105
|
+
|
|
106
|
+
attr_reader waiter: Integer
|
|
107
|
+
attr_reader flight: Integer
|
|
108
|
+
attr_reader key: Integer
|
|
109
|
+
attr_reader outcome: outcome
|
|
110
|
+
def self.new: (Integer waiter, Integer flight, Integer key, outcome outcome) -> Notification
|
|
111
|
+
| (waiter: Integer, flight: Integer, key: Integer, outcome: outcome) -> Notification
|
|
112
|
+
end
|
|
113
|
+
|
|
114
|
+
class Refresher
|
|
115
|
+
CAPACITY: Integer
|
|
116
|
+
FLIGHT_CAPACITY: Integer
|
|
117
|
+
WAITER_CAPACITY: Integer
|
|
118
|
+
|
|
119
|
+
# Scope zero.
|
|
120
|
+
def self.new: () -> Refresher
|
|
121
|
+
# `scope` is an Integer in 0..65_535, carried in the top 16 bits of every id.
|
|
122
|
+
def self.with_scope: (Integer scope) -> Refresher
|
|
123
|
+
# Empty, at time zero, the id sequence continuing after `issued` (a saved
|
|
124
|
+
# `#issued`): the constructor for a restart. nil when `issued` is beyond
|
|
125
|
+
# the sequence (more than 2**48 - 1).
|
|
126
|
+
def self.resumed: (Integer scope, Integer issued) -> Refresher
|
|
127
|
+
def scope: () -> Integer
|
|
128
|
+
# Ids issued so far, of every kind (leases, waiter ids, flight ids, all
|
|
129
|
+
# from one sequence): the count to save for `resumed`.
|
|
130
|
+
def issued: () -> Integer
|
|
131
|
+
# Methods taking a lease or waiter id raise RangeError for a zero sequence,
|
|
132
|
+
# before the core is asked. Every honoured decide, store, fail, reap, put
|
|
133
|
+
# and sweep records `now` (each answer depends on it); a refusal records
|
|
134
|
+
# nothing.
|
|
135
|
+
# Honoured: Fresh, Stale, Fetch, Wait. Refused: :time_regressed, :zero_lead,
|
|
136
|
+
# and, only when nothing is servable, :flights_full, :waiters_full, :exhausted.
|
|
137
|
+
def decide: (Integer key, Integer now, Integer lead_for) -> (Fresh | Stale | Fetch | Wait | :time_regressed | :zero_lead | :flights_full | :waiters_full | :exhausted)
|
|
138
|
+
# Honoured: :stored. Refused: :time_regressed, :stale, :entries_full.
|
|
139
|
+
def store: (Integer lease, Integer now, Integer age, Policy policy) -> (:stored | :time_regressed | :stale | :entries_full)
|
|
140
|
+
# Honoured: the age of the value that covers for the failure, or nil when
|
|
141
|
+
# nothing does. Refused: :time_regressed, :stale.
|
|
142
|
+
def fail: (Integer lease, Integer now, Integer retry_after) -> (Integer | nil | :time_regressed | :stale)
|
|
143
|
+
# Honoured: :abandoned. Refused: :stale.
|
|
144
|
+
def abandon: (Integer lease) -> (:abandoned | :stale)
|
|
145
|
+
# Honoured: leases revoked. Refused: :time_regressed.
|
|
146
|
+
def reap: (Integer now) -> (Integer | :time_regressed)
|
|
147
|
+
# Honoured: :stored. Refused: :time_regressed, :entries_full.
|
|
148
|
+
def put: (Integer key, Integer now, Integer age, Policy policy) -> (:stored | :time_regressed | :entries_full)
|
|
149
|
+
# Honoured: :forgotten when there was metadata to drop, and the repeat
|
|
150
|
+
# :not_held when the key had none (nothing changes). Never refuses.
|
|
151
|
+
def forget: (Integer key) -> (:forgotten | :not_held)
|
|
152
|
+
# Honoured: at most `max` swept keys (a `max` past CAPACITY sweeps
|
|
153
|
+
# whatever is expired, which is never more). Refused: :time_regressed.
|
|
154
|
+
def sweep: (Integer now, Integer max) -> (Array[Integer] | :time_regressed)
|
|
155
|
+
# Honoured: :cancelled. Refused: :stale.
|
|
156
|
+
def cancel: (Integer waiter) -> (:cancelled | :stale)
|
|
157
|
+
# The oldest queued notification, or nil when nothing is queued. Never refuses.
|
|
158
|
+
def poll: () -> Notification?
|
|
159
|
+
# At most `max` queued notifications, oldest first (a `max` past
|
|
160
|
+
# WAITER_CAPACITY takes them all, which is never more). Never refuses.
|
|
161
|
+
def drain: (Integer max) -> Array[Notification]
|
|
162
|
+
def age: (Integer key, Integer now) -> Integer?
|
|
163
|
+
def state: (Integer key, Integer now) -> state?
|
|
164
|
+
def stale_if_error: (Integer key, Integer now) -> Integer?
|
|
165
|
+
def leading: (Integer key) -> Integer?
|
|
166
|
+
def flight: (Integer lease) -> Integer?
|
|
167
|
+
def now: () -> Integer
|
|
168
|
+
# Keys with metadata (the core's `len`).
|
|
169
|
+
def size: () -> Integer
|
|
170
|
+
# Whether no key has metadata (the core's `is_empty`).
|
|
171
|
+
def empty?: () -> bool
|
|
172
|
+
def in_flight: () -> Integer
|
|
173
|
+
def waiting: () -> Integer
|
|
174
|
+
def pending: () -> Integer
|
|
175
|
+
def capacity: () -> Integer
|
|
176
|
+
def flight_capacity: () -> Integer
|
|
177
|
+
def waiter_capacity: () -> Integer
|
|
178
|
+
end
|
|
179
|
+
end
|
metadata
ADDED
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
|
2
|
+
name: refresh_machines
|
|
3
|
+
version: !ruby/object:Gem::Version
|
|
4
|
+
version: 0.7.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: Classifies cached values as fresh, stale or expired and grants one refresh
|
|
33
|
+
lease per key. Stores no values, fetches nothing and evicts nothing.
|
|
34
|
+
email:
|
|
35
|
+
- oss@seuros.com
|
|
36
|
+
executables: []
|
|
37
|
+
extensions:
|
|
38
|
+
- ext/refresh_machines_native/extconf.rb
|
|
39
|
+
extra_rdoc_files: []
|
|
40
|
+
files:
|
|
41
|
+
- CHANGELOG.md
|
|
42
|
+
- Cargo.lock
|
|
43
|
+
- Cargo.toml
|
|
44
|
+
- LICENSE.txt
|
|
45
|
+
- README.md
|
|
46
|
+
- ext/refresh_machines_native/core/CHANGELOG.md
|
|
47
|
+
- ext/refresh_machines_native/core/Cargo.toml
|
|
48
|
+
- ext/refresh_machines_native/core/README.md
|
|
49
|
+
- ext/refresh_machines_native/core/src/decision.rs
|
|
50
|
+
- ext/refresh_machines_native/core/src/lead.rs
|
|
51
|
+
- ext/refresh_machines_native/core/src/lease.rs
|
|
52
|
+
- ext/refresh_machines_native/core/src/lib.rs
|
|
53
|
+
- ext/refresh_machines_native/core/src/policy.rs
|
|
54
|
+
- ext/refresh_machines_native/core/src/refusal.rs
|
|
55
|
+
- ext/refresh_machines_native/extconf.rb
|
|
56
|
+
- ext/refresh_machines_native/ffi/Cargo.toml
|
|
57
|
+
- ext/refresh_machines_native/ffi/extconf.rb
|
|
58
|
+
- ext/refresh_machines_native/ffi/src/answers.rs
|
|
59
|
+
- ext/refresh_machines_native/ffi/src/init.rs
|
|
60
|
+
- ext/refresh_machines_native/ffi/src/lib.rs
|
|
61
|
+
- ext/refresh_machines_native/ffi/src/values.rs
|
|
62
|
+
- lib/refresh_machines.rb
|
|
63
|
+
- lib/refresh_machines/version.rb
|
|
64
|
+
- sig/refresh_machines.rbs
|
|
65
|
+
homepage: https://github.com/seuros/refresh_machines
|
|
66
|
+
licenses:
|
|
67
|
+
- MIT
|
|
68
|
+
metadata:
|
|
69
|
+
source_code_uri: https://github.com/seuros/refresh_machines
|
|
70
|
+
rubygems_mfa_required: 'true'
|
|
71
|
+
cargo_crate_name: refresh_machines_native
|
|
72
|
+
cargo_manifest_path: ext/refresh_machines_native/ffi/Cargo.toml
|
|
73
|
+
rdoc_options: []
|
|
74
|
+
require_paths:
|
|
75
|
+
- lib
|
|
76
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
|
77
|
+
requirements:
|
|
78
|
+
- - ">="
|
|
79
|
+
- !ruby/object:Gem::Version
|
|
80
|
+
version: 4.0.0
|
|
81
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
82
|
+
requirements:
|
|
83
|
+
- - ">="
|
|
84
|
+
- !ruby/object:Gem::Version
|
|
85
|
+
version: '0'
|
|
86
|
+
requirements: []
|
|
87
|
+
rubygems_version: 4.0.20
|
|
88
|
+
specification_version: 4
|
|
89
|
+
summary: Stale-while-revalidate and stale-if-error decisions for Ruby
|
|
90
|
+
test_files: []
|