journal_machines 0.7.1-x86_64-linux
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 +95 -0
- data/LICENSE.txt +21 -0
- data/README.md +401 -0
- data/ext/journal_machines_native/core/CHANGELOG.md +77 -0
- data/ext/journal_machines_native/core/README.md +261 -0
- data/ext/journal_machines_native/extconf.rb +2 -0
- data/lib/journal_machines/version.rb +4 -0
- data/lib/journal_machines.rb +138 -0
- data/lib/journal_machines_native/journal_machines_native.so +0 -0
- data/sig/journal_machines.rbs +209 -0
- metadata +64 -0
checksums.yaml
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: c8433791bb193b665335c75f7a23a3f8ffecc5a1053b73f60bea45c5b7d0b233
|
|
4
|
+
data.tar.gz: 5327adb7ed271e4d1a751ba7c76b9168aad879750d164061fa08cb59d1118f7e
|
|
5
|
+
SHA512:
|
|
6
|
+
metadata.gz: 5ff80bbceff206a26ce6c3f77d1dce2b56770194c74a5c97e1e9521c5d9d1f611f909b564b2895d583985cdae948bbe98be0f2c5b82db4268a861f4f6824f465
|
|
7
|
+
data.tar.gz: 6486f1565b20f1bab9301bdccae2383626c5cc05e64f5d6861ce5566dee2b47bfafb1ab9ab7cd2bf008a72a6909a4e9c102da5dede046e76f84a0fb864f27a5f
|
data/CHANGELOG.md
ADDED
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [0.7.1](https://github.com/seuros/journal_machines/compare/journal_machines/v0.7.0...journal_machines/v0.7.1) (2026-11-16)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Bug Fixes
|
|
7
|
+
|
|
8
|
+
* fix wrapped classes at load so building a handle runs no Ruby ([f87e049](https://github.com/seuros/journal_machines/commit/f87e049d521da4c49f9b160a5247c2a94307aaf5))
|
|
9
|
+
|
|
10
|
+
## [0.7.0](https://github.com/seuros/journal_machines/compare/journal_machines/v0.6.1...journal_machines/v0.7.0) (2026-11-16)
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
### ⚠ BREAKING CHANGES
|
|
14
|
+
|
|
15
|
+
* replace Segment pinned bool with a Retention enum
|
|
16
|
+
|
|
17
|
+
### Features
|
|
18
|
+
|
|
19
|
+
* replace Segment pinned bool with a Retention enum ([98d6904](https://github.com/seuros/journal_machines/commit/98d690430cea94988b5ceb7389d7238999896dcd))
|
|
20
|
+
|
|
21
|
+
## [0.6.1](https://github.com/seuros/journal_machines/compare/journal_machines/v0.6.0...journal_machines/v0.6.1) (2026-11-14)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
### Bug Fixes
|
|
25
|
+
|
|
26
|
+
* **deps:** require matryona-machines >= 0.4 and read the Segment replacement with optional_typed ([f318c31](https://github.com/seuros/journal_machines/commit/f318c317503a121503ce9865fd51f0289e6398c0))
|
|
27
|
+
|
|
28
|
+
## [0.6.0](https://github.com/seuros/journal_machines/compare/journal_machines/v0.5.0...journal_machines/v0.6.0) (2026-11-14)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
### ⚠ BREAKING CHANGES
|
|
32
|
+
|
|
33
|
+
* adopt matryona 0.3: optional_positive, integer_in and boolean readers, names_only refusal table
|
|
34
|
+
|
|
35
|
+
### Features
|
|
36
|
+
|
|
37
|
+
* adopt matryona 0.3: optional_positive, integer_in and boolean readers, names_only refusal table ([ab0f05d](https://github.com/seuros/journal_machines/commit/ab0f05dc11b473e24308f7696af71be55674ee11))
|
|
38
|
+
|
|
39
|
+
## [0.5.0](https://github.com/seuros/journal_machines/compare/journal_machines/v0.4.0...journal_machines/v0.5.0) (2026-11-14)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
### ⚠ BREAKING CHANGES
|
|
43
|
+
|
|
44
|
+
* adopt matryona-machines 0.2: exact-class Pin/Replacement handles, positive thresholds, compiler-checked symbol tables
|
|
45
|
+
|
|
46
|
+
### Features
|
|
47
|
+
|
|
48
|
+
* adopt matryona-machines 0.2: exact-class Pin/Replacement handles, positive thresholds, compiler-checked symbol tables ([53ef3b1](https://github.com/seuros/journal_machines/commit/53ef3b10ded3b1b994e2da14f04ecd5dcf5c7a7c))
|
|
49
|
+
|
|
50
|
+
## [0.4.0](https://github.com/seuros/journal_machines/compare/journal_machines/v0.3.0...journal_machines/v0.4.0) (2026-11-14)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
### ⚠ BREAKING CHANGES
|
|
54
|
+
|
|
55
|
+
* validate values through the core, value handles, native answers, read Policy by exact class, clone-then-keep roll/reclaim
|
|
56
|
+
|
|
57
|
+
### Features
|
|
58
|
+
|
|
59
|
+
* validate values through the core, value handles, native answers, read Policy by exact class, clone-then-keep roll/reclaim ([5b00d40](https://github.com/seuros/journal_machines/commit/5b00d406d92bdfb6f1ec331b60c61243ec013994))
|
|
60
|
+
|
|
61
|
+
## [0.3.0](https://github.com/seuros/journal_machines/compare/journal_machines/v0.2.0...journal_machines/v0.3.0) (2026-11-13)
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
### ⚠ BREAKING CHANGES
|
|
65
|
+
|
|
66
|
+
* handles are issued through periscope-machines. Every instance can be built with a scope; a handle from another scope is refused before any lookup; all handle kinds of an instance share one sequence; resumed restores the sequence after a restart. Handles of a journal no longer share raw values; release of a pin that is not held is Stale; the Ruby owner tag is gone.
|
|
67
|
+
|
|
68
|
+
### Features
|
|
69
|
+
|
|
70
|
+
* draw segment ids, pin generations and attempts from one scoped periscope sequence; add Journal::resumed ([6a9b959](https://github.com/seuros/journal_machines/commit/6a9b9597aceffa452dee5d74903f99b184a15d2e))
|
|
71
|
+
|
|
72
|
+
## [0.2.0](https://github.com/seuros/journal_machines/compare/journal_machines/v0.1.2...journal_machines/v0.2.0) (2026-11-13)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
### ⚠ BREAKING CHANGES
|
|
76
|
+
|
|
77
|
+
* see CONVENTIONS: one exhaustive Refusal per crate, Result from every mutator, honoured idempotent repeats only when provable, Duration time, Ruby mirrors the core. No compatibility aliases. Requires offset-machines >= 0.3. A repeated confirm with another payload is Mismatch; releasing a pin that is not held is Stale.
|
|
78
|
+
|
|
79
|
+
### Features
|
|
80
|
+
|
|
81
|
+
* one Refusal enum with Result everywhere, provable repeats only, Duration time, Ruby Policy and _from pin calls ([f820899](https://github.com/seuros/journal_machines/commit/f8208990722b8407f206f8714c5708720f72dc74))
|
|
82
|
+
|
|
83
|
+
## [0.1.2](https://github.com/seuros/journal_machines/compare/journal_machines/v0.1.1...journal_machines/v0.1.2) (2026-11-13)
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
### Features
|
|
87
|
+
|
|
88
|
+
* add pin_checkpoint_from and checkpoint_from to the Ruby journal ([a42f1da](https://github.com/seuros/journal_machines/commit/a42f1dace271d39d47264133d63bcd3d1101e441))
|
|
89
|
+
|
|
90
|
+
## [0.1.1](https://github.com/seuros/journal_machines/compare/journal_machines-v0.1.0...journal_machines/v0.1.1) (2026-11-12)
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
### Features
|
|
94
|
+
|
|
95
|
+
* initial extraction ([1e4f7a9](https://github.com/seuros/journal_machines/commit/1e4f7a9c3344bd27293fc3f51ee66e22d266e183))
|
data/LICENSE.txt
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Abdelkader Boudih
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
data/README.md
ADDED
|
@@ -0,0 +1,401 @@
|
|
|
1
|
+
# JournalMachines
|
|
2
|
+
|
|
3
|
+
> Deleting a log segment is easy. Deleting it at the right time is the job.
|
|
4
|
+
|
|
5
|
+
Segment bookkeeping for a segmented log, in Ruby. You tell the journal what your log files look like: how big the active one is, which records in the old ones are dead, who is still reading, how far recovery has got. It tells you when to roll, which segments are worth compacting, and when an old file may finally be deleted. It never touches a file itself.
|
|
6
|
+
|
|
7
|
+
## Quick Start
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
gem 'journal_machines'
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
```ruby
|
|
14
|
+
HOUR = 3600 * 1_000_000_000 # time is Integer nanoseconds
|
|
15
|
+
clock = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond) }
|
|
16
|
+
|
|
17
|
+
# max_bytes, max_records, max_age, min_dead_per_mille. nil turns a threshold off.
|
|
18
|
+
policy = JournalMachines::Policy.new(64 * 1024 * 1024, nil, HOUR, 500)
|
|
19
|
+
journal = JournalMachines::Journal.new(policy, 0, clock.call) # first offset 0, opened now
|
|
20
|
+
checkpoint = journal.pin_checkpoint(1, 0) # recovery replays from offset 0
|
|
21
|
+
|
|
22
|
+
# Writer loop: ask before every append batch.
|
|
23
|
+
if journal.roll_decision(file.size, file.records, clock.call) != :keep
|
|
24
|
+
file.fsync_and_close
|
|
25
|
+
rolled = journal.roll(file.size, file.records, clock.call)
|
|
26
|
+
file = open_segment(rolled.opened, rolled.next_offset)
|
|
27
|
+
end
|
|
28
|
+
|
|
29
|
+
# Compactor loop.
|
|
30
|
+
journal.compaction_candidates(nil, 64).each do |segment|
|
|
31
|
+
replacement = journal.propose(segment.id)
|
|
32
|
+
bytes, live = rewrite_and_fsync(segment) # your code, your fsync
|
|
33
|
+
journal.confirm_rewritten(replacement, bytes, live)
|
|
34
|
+
end
|
|
35
|
+
|
|
36
|
+
# Reaper loop: only what the journal lets go.
|
|
37
|
+
journal.reclaimable(nil, 64).each do |segment|
|
|
38
|
+
reclaimed = journal.reclaim(segment.replacement)
|
|
39
|
+
delete_file(reclaimed.segment, reclaimed.revision) if reclaimed.is_a?(JournalMachines::Reclaimed)
|
|
40
|
+
end
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
One journal, three loops. Offsets, sizes and times are Integers. Time is Integer nanoseconds on one monotonic clock, `Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)`, for instants (`now`, a segment's `opened_at`) and spans (`max_age`) alike. No floats, no seconds, no `Time.now`.
|
|
44
|
+
|
|
45
|
+
## A Message to the Resistance
|
|
46
|
+
|
|
47
|
+
So you wrote an append-only log. Appending was the easy part. Then the disk filled, and you wrote a cleaner. The cleaner copied the live records of an old segment into a new file and deleted the old one.
|
|
48
|
+
|
|
49
|
+
Then a consumer that had been paused for an hour woke up holding a byte position into the file you deleted. So you added a check: don't delete while someone is reading. Then the machine lost power between the delete and the fsync of the new file, and the new file came back zero bytes long. So you added another check: fsync first. Then recovery replayed from the last checkpoint, which pointed into a segment the cleaner had judged finished. So you added a third check, in a third place, guarded by a third boolean.
|
|
50
|
+
|
|
51
|
+
Every one of those was the same rule, discovered one outage at a time. An original may go only when its replacement is durable *and* nobody who needs it is still behind it. The rule is small. The trouble is that it lived in three places and was enforced by remembering. This gem is the one place.
|
|
52
|
+
|
|
53
|
+
## Chapter 1: Stardate 2026.316, the AMS Rosenblum
|
|
54
|
+
|
|
55
|
+
> **AMS Rosenblum**, NCC-4228, *Rosenblum*-class archive cutter.
|
|
56
|
+
> Nothing leaves the hold until its copy is stowed and nobody is still reading it.
|
|
57
|
+
|
|
58
|
+
The archive cutter doesn't write the logbooks and doesn't shred them. It keeps the register of volumes: which one is open, which are closed, which have been recopied onto fresh stock, and who has one checked out. The shredder crew works from the register and from nothing else.
|
|
59
|
+
|
|
60
|
+
On a bridge somewhere, a cadet volunteers:
|
|
61
|
+
|
|
62
|
+
```ruby
|
|
63
|
+
def clean(segment)
|
|
64
|
+
compacted = rewrite(segment)
|
|
65
|
+
File.delete(segment.path)
|
|
66
|
+
compacted
|
|
67
|
+
end
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
"That," says the cutter's archivist, "deletes the only copy between two lines, while the reader on deck four is halfway through it."
|
|
71
|
+
|
|
72
|
+
## The Flight Plan
|
|
73
|
+
|
|
74
|
+
Every segment the journal knows about is in one of these states:
|
|
75
|
+
|
|
76
|
+
```mermaid
|
|
77
|
+
stateDiagram-v2
|
|
78
|
+
[*] --> active
|
|
79
|
+
active --> sealed: roll
|
|
80
|
+
sealed --> proposed: propose
|
|
81
|
+
proposed --> durable: confirm_rewritten / confirm_superseded
|
|
82
|
+
proposed --> sealed: abort
|
|
83
|
+
durable --> sealed: abort
|
|
84
|
+
durable --> reclaimable: last pin moves past the segment
|
|
85
|
+
reclaimable --> durable: a new pin lands on it
|
|
86
|
+
reclaimable --> sealed: reclaim, rewritten (new revision)
|
|
87
|
+
reclaimable --> [*]: reclaim, superseded
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
And the afternoon the cleaner wanted segment 1 while a reader was still in it:
|
|
91
|
+
|
|
92
|
+
```mermaid
|
|
93
|
+
sequenceDiagram
|
|
94
|
+
participant C as Compactor
|
|
95
|
+
participant J as Journal
|
|
96
|
+
participant R as Reader
|
|
97
|
+
|
|
98
|
+
R->>J: pin_reader(3)
|
|
99
|
+
J-->>R: Pin
|
|
100
|
+
C->>J: propose(1)
|
|
101
|
+
J-->>C: Replacement
|
|
102
|
+
C->>C: rewrite live records, fsync
|
|
103
|
+
C->>J: reclaim(replacement)
|
|
104
|
+
J-->>C: :not_durable
|
|
105
|
+
C->>J: confirm_rewritten(replacement, 30, 4)
|
|
106
|
+
J-->>C: :recorded
|
|
107
|
+
C->>J: reclaim(replacement)
|
|
108
|
+
J-->>C: :pinned
|
|
109
|
+
Note over C: keeps both files
|
|
110
|
+
R->>J: advance(pin, 10)
|
|
111
|
+
J-->>R: :moved
|
|
112
|
+
C->>J: reclaim(replacement)
|
|
113
|
+
J-->>C: Reclaimed
|
|
114
|
+
Note over C: deletes revision 0. The reader never noticed.
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
## How the Journal Works
|
|
118
|
+
|
|
119
|
+
### Roll
|
|
120
|
+
|
|
121
|
+
```ruby
|
|
122
|
+
policy = JournalMachines::Policy.new(100, 10, 50, 500)
|
|
123
|
+
policy.max_age # => 50
|
|
124
|
+
journal = JournalMachines::Journal.new(policy, 0, 1000)
|
|
125
|
+
journal.policy == policy # => true
|
|
126
|
+
|
|
127
|
+
journal.roll_decision(99, 9, 1049) # => :keep
|
|
128
|
+
journal.roll_decision(100, 9, 1000) # => #<data JournalMachines::Due reason=:size>
|
|
129
|
+
journal.roll_decision(1, 10, 1000) # => #<data JournalMachines::Due reason=:records>
|
|
130
|
+
journal.roll_decision(1, 1, 1050) # => #<data JournalMachines::Due reason=:age>
|
|
131
|
+
journal.roll_decision(0, 0, 9999) # => :keep, an empty segment is never due
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
`roll_decision` answers the core's `Roll`: the symbol `:keep`, or a `Due(reason)` naming the first threshold reached. It only reads. You pass what you observed about the active segment, bytes, records and the time, and it compares them with the thresholds, in that order. Leave a threshold out and it never triggers.
|
|
135
|
+
|
|
136
|
+
`now` and `max_age` are nanoseconds, so the segment above was opened at 1000 ns and is due by age 50 ns later. Real code passes the monotonic clock reading and a `max_age` like `30 * 60 * 1_000_000_000`. `segment.opened_at` reads back the same nanoseconds.
|
|
137
|
+
|
|
138
|
+
When you have actually sealed the file, say so:
|
|
139
|
+
|
|
140
|
+
```ruby
|
|
141
|
+
rolled = journal.roll(100, 9, 1000)
|
|
142
|
+
rolled.sealed # => 1
|
|
143
|
+
rolled.opened # => 2
|
|
144
|
+
rolled.next_offset # => 9
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
`Policy.new(max_bytes, max_records, max_age, min_dead_per_mille)` holds the three roll thresholds and the dead-record ratio for compaction. `Journal.new(policy, base_offset, now)` opens one active segment at `base_offset`, at instant `now`. Neither has defaults: every argument is yours to choose. A threshold of `nil` never triggers. A threshold of zero, or a ratio above 1000, raises `RangeError` from `Policy.new`, so a bad policy never exists.
|
|
148
|
+
|
|
149
|
+
A roll doesn't have to be due. Sealing early is your call. Sealing an empty segment is `:empty`.
|
|
150
|
+
|
|
151
|
+
### Compaction candidates
|
|
152
|
+
|
|
153
|
+
The journal doesn't know which records are dead. You do, so you tell it:
|
|
154
|
+
|
|
155
|
+
```ruby
|
|
156
|
+
policy = JournalMachines::Policy.new(nil, nil, nil, 500) # no roll thresholds, compact at half dead
|
|
157
|
+
journal = JournalMachines::Journal.new(policy, 0, 0)
|
|
158
|
+
3.times { journal.roll(100, 10, 0) } # segments 1, 2, 3 sealed; 4 active
|
|
159
|
+
|
|
160
|
+
journal.observe_live(1, 5) # => :recorded, half dead
|
|
161
|
+
journal.observe_live(2, 6) # => :recorded, not dead enough
|
|
162
|
+
journal.observe_live(3, 0) # => :recorded, all dead
|
|
163
|
+
|
|
164
|
+
journal.compaction_candidates(nil, 64).map(&:id) # => [1, 3]
|
|
165
|
+
journal.compaction_candidates(nil, 1).map(&:id) # => [1]
|
|
166
|
+
journal.compaction_candidates(1, 1).map(&:id) # => [3]
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
A sealed segment is a candidate when at least `min_dead_per_mille` of its stored records are dead (500 here, so half) and it has no replacement in flight. Candidates come oldest first, at most `limit` at a time. Pass the last id you handled to get the next batch.
|
|
170
|
+
|
|
171
|
+
### Replacement
|
|
172
|
+
|
|
173
|
+
```ruby
|
|
174
|
+
replacement = journal.propose(1)
|
|
175
|
+
replacement.class # => JournalMachines::Replacement
|
|
176
|
+
journal.segment(1).state # => :proposed
|
|
177
|
+
journal.propose(1) # => :busy
|
|
178
|
+
|
|
179
|
+
journal.confirm_rewritten(replacement, 40, 5) # => :recorded
|
|
180
|
+
journal.confirm_rewritten(replacement, 40, 5) # => :already_durable, a repeat
|
|
181
|
+
journal.confirm_rewritten(replacement, 41, 5) # => :mismatch, that is not what was recorded
|
|
182
|
+
journal.confirm_superseded(replacement) # => :mismatch
|
|
183
|
+
journal.segment(1).state # => :reclaimable
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Confirming twice with the same numbers is not an error. The attempt is durable with exactly that, which is what you asked for, so the answer is `:already_durable`. Confirming it again with anything else, other bytes, another record count, or the other method, is `:mismatch`: the journal never recorded that, so it won't tell you it did. The first confirmation stands. If it was wrong, `abort` and propose again.
|
|
187
|
+
|
|
188
|
+
`propose` marks a segment as being replaced. `confirm_rewritten(replacement, bytes, live_records)` says a compacted copy of the same offsets is on disk and synced. `confirm_superseded(replacement)` says something else now covers the range, a snapshot or an archive, or nothing at all because every record was dead. The journal takes your word for it. It cannot see your disk.
|
|
189
|
+
|
|
190
|
+
The core has one call here, `confirm_durable(replacement, durable)`, where `durable` is `Rewritten { bytes, live_records }` or `Superseded`. Ruby has one method per variant, named after it and taking that variant's fields in order. Both answer `:recorded` the first time.
|
|
191
|
+
|
|
192
|
+
Changed your mind, or the rewrite failed?
|
|
193
|
+
|
|
194
|
+
```ruby
|
|
195
|
+
journal.abort(replacement) # => :aborted
|
|
196
|
+
journal.segment(1).state # => :sealed
|
|
197
|
+
journal.abort(replacement) # => :stale
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
### Pins
|
|
201
|
+
|
|
202
|
+
A pin says "everything at or after this offset is still needed."
|
|
203
|
+
|
|
204
|
+
```ruby
|
|
205
|
+
journal = JournalMachines::Journal.new(policy, 0, 0)
|
|
206
|
+
2.times { journal.roll(100, 10, 0) } # segment 1 holds 0...10, segment 2 holds 10...20
|
|
207
|
+
|
|
208
|
+
reader = journal.pin_reader(3)
|
|
209
|
+
reader.class # => JournalMachines::Pin
|
|
210
|
+
journal.low_pin # => 3
|
|
211
|
+
journal.segment(1).retention # => :pinned
|
|
212
|
+
|
|
213
|
+
journal.advance(reader, 10) # => :moved
|
|
214
|
+
journal.advance(reader, 10) # => :unchanged, already there
|
|
215
|
+
journal.advance(reader, 4) # => :regressed
|
|
216
|
+
journal.segment(1).retention # => :unpinned
|
|
217
|
+
|
|
218
|
+
journal.release(reader) # => :released
|
|
219
|
+
journal.release(reader) # => :stale
|
|
220
|
+
journal.advance(reader, 11) # => :stale
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Release is checked against the acquisition, not the slot. Once released, a pin handle never names a pin again, even after the journal hands the same slot to someone else: `advance`, `checkpoint` and `pin_offset` answer `:stale` (or `nil`) and leave the new holder alone. A second `release` is `:stale` too, and changes nothing. The journal keeps no list of released pins, and it can't work the answer out: pins, segments and attempts are numbered from one sequence, so "one of my numbers that no pin holds" is just as true of a segment id. It only honours a repeat it can prove. A pin it never issued, from a journal of another scope or with a number it hasn't reached, is `:stale` as well.
|
|
224
|
+
|
|
225
|
+
Moving a pin to where it already sits is `:unchanged`, an answer and not a refusal. Moving it back is `:regressed`, a refusal: the journal may already have let go of what lies behind the pin, so it cannot promise it again.
|
|
226
|
+
|
|
227
|
+
A checkpoint pin also carries the generation of the consumer assignment that reported it:
|
|
228
|
+
|
|
229
|
+
```ruby
|
|
230
|
+
checkpoint = journal.pin_checkpoint(3, 20) # assignment generation 3, offset 20
|
|
231
|
+
|
|
232
|
+
journal.checkpoint(checkpoint, 3, 25) # => :advanced
|
|
233
|
+
journal.checkpoint(checkpoint, 2, 99) # => :stale_assignment
|
|
234
|
+
journal.checkpoint(checkpoint, 4, 8) # => :reassigned
|
|
235
|
+
journal.pin_offset(checkpoint) # => 8
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
A consumer that was fenced off can't drag retention forward with an offset it committed before it lost the partition. A newer assignment takes over at whatever offset it reports, even a lower one.
|
|
239
|
+
|
|
240
|
+
If the generation and the offset come from an offset tracker, hand over the tracker instead of two loose integers:
|
|
241
|
+
|
|
242
|
+
```ruby
|
|
243
|
+
tracker = OffsetMachines::Tracker.new # gem 'offset_machines'
|
|
244
|
+
journal.pin_checkpoint_from(tracker) # => :unassigned, nothing pinned
|
|
245
|
+
|
|
246
|
+
tracker.assign(3, 20)
|
|
247
|
+
checkpoint = journal.pin_checkpoint_from(tracker)
|
|
248
|
+
journal.pin_offset(checkpoint) # => 20
|
|
249
|
+
|
|
250
|
+
tracker.ack(3, 20) # acknowledged, not committed
|
|
251
|
+
journal.checkpoint_from(checkpoint, tracker) # => :unchanged
|
|
252
|
+
tracker.mark_committed(3, 21)
|
|
253
|
+
journal.checkpoint_from(checkpoint, tracker) # => :advanced, now at 21
|
|
254
|
+
|
|
255
|
+
zombie = OffsetMachines::Tracker.new
|
|
256
|
+
zombie.assign(2, 99)
|
|
257
|
+
journal.checkpoint_from(checkpoint, zombie) # => :stale_assignment
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
`pin_checkpoint_from(tracker)` is `pin_checkpoint(tracker.generation, tracker.base)` and `checkpoint_from(pin, tracker)` is `checkpoint(pin, tracker.generation, tracker.base)`, with the same answers. Both numbers are read from the one object you pass, so they can't come from two different trackers. This gem doesn't depend on `offset_machines`: any object with public `generation` and `base` readers fits, `OffsetMachines::Tracker` being the one they were written for. The binding asks for both before calling either, so an object missing one raises `TypeError` naming it (`expected an offset tracker responding to #generation and #base, Object lacks #base`) and runs neither.
|
|
261
|
+
|
|
262
|
+
### Reclaim
|
|
263
|
+
|
|
264
|
+
```ruby
|
|
265
|
+
journal = JournalMachines::Journal.new(policy, 0, 0)
|
|
266
|
+
journal.roll(100, 10, 0)
|
|
267
|
+
reader = journal.pin_reader(3)
|
|
268
|
+
replacement = journal.propose(1)
|
|
269
|
+
|
|
270
|
+
journal.reclaim(replacement) # => :not_durable
|
|
271
|
+
journal.confirm_rewritten(replacement, 30, 4) # => :recorded
|
|
272
|
+
journal.reclaim(replacement) # => :pinned
|
|
273
|
+
journal.reclaimable(nil, 64) # => []
|
|
274
|
+
|
|
275
|
+
journal.advance(reader, 10) # => :moved
|
|
276
|
+
reclaimed = journal.reclaim(replacement)
|
|
277
|
+
reclaimed.revision # => 0, the file to delete
|
|
278
|
+
reclaimed.bytes # => 100
|
|
279
|
+
reclaimed.replaced_by # => 4, the revision now serving 0...10: the attempt number
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
Two conditions, both required: the replacement is confirmed durable, and no pin of either kind sits below the segment's end. Miss one and you get a symbol and nothing changes. A rewritten segment keeps its id and its offsets under a new revision. A superseded one leaves the journal and `replaced_by` is `nil`.
|
|
283
|
+
|
|
284
|
+
### Capacity
|
|
285
|
+
|
|
286
|
+
The journal tracks 64 segments and 32 pins. Past that it refuses:
|
|
287
|
+
|
|
288
|
+
```ruby
|
|
289
|
+
journal = JournalMachines::Journal.new(policy, 0, 0)
|
|
290
|
+
journal.segment_capacity # => 64
|
|
291
|
+
63.times { journal.roll(1, 1, 0) }
|
|
292
|
+
journal.roll(1, 1, 0) # => :segments_full
|
|
293
|
+
|
|
294
|
+
32.times { journal.pin_reader(0) }
|
|
295
|
+
journal.pin_reader(0) # => :pins_full
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
A `:segments_full` roll means your writer keeps appending to the segment it has until you reclaim something. Nothing is dropped to make room.
|
|
299
|
+
|
|
300
|
+
### Time only moves forward
|
|
301
|
+
|
|
302
|
+
```ruby
|
|
303
|
+
journal = JournalMachines::Journal.new(JournalMachines::Policy.new(nil, nil, 10, 500), 0, 100)
|
|
304
|
+
journal.roll_decision(1, 1, 99) # => :time_regression
|
|
305
|
+
journal.roll(1, 1, 99) # => :time_regression
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
A clock reading earlier than the moment the active segment was opened is refused, not guessed at.
|
|
309
|
+
|
|
310
|
+
### Every answer
|
|
311
|
+
|
|
312
|
+
A call that is honoured answers with a value. A call that is not honoured answers with one of the refusal symbols below, and only those, and changes nothing. A repeat of something that already holds is honoured: it gets its own answer in the Honoured column, marked *repeat*, and it changes nothing either.
|
|
313
|
+
|
|
314
|
+
| Call | Honoured | Refusals | Records the clock |
|
|
315
|
+
| --- | --- | --- | --- |
|
|
316
|
+
| `Journal.new`, `with_scope`, `resumed` | a `Journal` | none; bad input raises | yes: the first segment opens at `now` |
|
|
317
|
+
| `roll_decision(bytes, records, now)` | `:keep`, `Due(:size)`, `Due(:records)`, `Due(:age)` | `:time_regression`, `:overflow`, `:no_active` | no, a read: the journal keeps no watermark, and `now` is judged against the active segment's opening |
|
|
318
|
+
| `roll(bytes, records, now)` | `Rolled` | `:empty`, `:time_regression`, `:overflow`, `:segments_full`, `:exhausted`, `:no_active` | yes: the new active segment opens at `now` |
|
|
319
|
+
| `observe_live(id, live_records)` | `:recorded` | `:unknown`, `:active`, `:exceeds` | no clock |
|
|
320
|
+
| `pin_reader(offset)` | `Pin` | `:pins_full`, `:exhausted` | no clock |
|
|
321
|
+
| `pin_checkpoint(assignment, offset)`, `pin_checkpoint_from(tracker)` | `Pin` | `:unassigned`, `:pins_full`, `:exhausted` | no clock |
|
|
322
|
+
| `advance(pin, offset)` | `:moved`, `:unchanged` (*repeat*) | `:stale`, `:wrong_kind`, `:regressed` | no clock |
|
|
323
|
+
| `checkpoint(pin, assignment, offset)`, `checkpoint_from(pin, tracker)` | `:advanced`, `:reassigned`, `:unchanged` (*repeat*) | `:stale`, `:wrong_kind`, `:unassigned`, `:stale_assignment`, `:regressed` | no clock |
|
|
324
|
+
| `release(pin)` | `:released` | `:stale` | no clock |
|
|
325
|
+
| `propose(id)` | `Replacement` | `:unknown`, `:active`, `:busy`, `:exhausted` | no clock |
|
|
326
|
+
| `confirm_rewritten(replacement, bytes, live_records)` | `:recorded`, `:already_durable` (*repeat*) | `:stale`, `:mismatch`, `:exceeds` | no clock |
|
|
327
|
+
| `confirm_superseded(replacement)` | `:recorded`, `:already_durable` (*repeat*) | `:stale`, `:mismatch` | no clock |
|
|
328
|
+
| `reclaim(replacement)` | `Reclaimed` | `:stale`, `:not_durable`, `:pinned` | no clock |
|
|
329
|
+
| `abort(replacement)` | `:aborted` | `:stale` | no clock |
|
|
330
|
+
| `Policy.new`, `Due.new`, `Rolled.new`, `Reclaimed.new`, `Segment.new` | the value | none; a value no journal could hold or answer raises `RangeError`, a wrong type `TypeError` | no clock |
|
|
331
|
+
|
|
332
|
+
Each refusal is the snake_case of one core `Refusal` variant. There is no catch-all symbol. The only instants the journal keeps are its segments' opening times, and only the constructors and an honoured `roll` set one; no repeat takes a clock at all.
|
|
333
|
+
|
|
334
|
+
The repeats. Only one the journal can prove from its own state is honoured:
|
|
335
|
+
|
|
336
|
+
| Repeat | Meaning |
|
|
337
|
+
| --- | --- |
|
|
338
|
+
| `:unchanged` | The pin already sits at that offset (for a checkpoint: under that same assignment generation). |
|
|
339
|
+
| `:already_durable` | This attempt was confirmed before by the same method with the same bytes and record count. |
|
|
340
|
+
|
|
341
|
+
Each refusal means one thing wherever it shows up:
|
|
342
|
+
|
|
343
|
+
| Refusal | Meaning |
|
|
344
|
+
| --- | --- |
|
|
345
|
+
| `:no_active` | There is no active segment. Not reachable with the compiled capacity of 64. |
|
|
346
|
+
| `:empty` | The active segment holds no records, so there is nothing to seal. |
|
|
347
|
+
| `:time_regression` | `now` is earlier than the moment the active segment was opened. |
|
|
348
|
+
| `:overflow` | The offset range would pass `2**64 - 1`. |
|
|
349
|
+
| `:segments_full` | All 64 segment slots are taken. Reclaim one. |
|
|
350
|
+
| `:pins_full` | All 32 pin slots are held. Release one. |
|
|
351
|
+
| `:exhausted` | The journal ran out of numbers for segment ids, pin generations and attempts. That takes `2**48 - 1` of them, all kinds together, per scope. |
|
|
352
|
+
| `:unknown` | No segment has that id. |
|
|
353
|
+
| `:active` | That is the active segment, still being written. |
|
|
354
|
+
| `:busy` | The segment already has a replacement in flight. |
|
|
355
|
+
| `:exceeds` | More live records than the segment stores. |
|
|
356
|
+
| `:mismatch` | The attempt is already durable, but not with this: `confirm_superseded` after `confirm_rewritten` or the reverse, or `confirm_rewritten` with other bytes or another record count. The first confirmation stands. |
|
|
357
|
+
| `:stale` | The `Pin` or `Replacement` is not current: released, aborted, reclaimed, superseded by a newer attempt, or one this journal never issued (another scope, or a number it hasn't reached). Releasing a pin twice is `:stale`. |
|
|
358
|
+
| `:wrong_kind` | `advance` on a checkpoint pin, or `checkpoint` on a reader pin. |
|
|
359
|
+
| `:unassigned` | Assignment generation zero is not an assignment. |
|
|
360
|
+
| `:stale_assignment` | The assignment generation is older than the one the checkpoint holds. |
|
|
361
|
+
| `:regressed` | The offset is behind the pin. |
|
|
362
|
+
| `:not_durable` | The replacement hasn't been confirmed durable. |
|
|
363
|
+
| `:pinned` | A pin still sits below the segment's end. |
|
|
364
|
+
|
|
365
|
+
The queries `active`, `segment`, `covering`, `segments`, `compaction_candidates`, `reclaimable`, `pin_offset`, `low_pin`, `pins`, `policy`, `size`, `empty?`, `segment_capacity` and `pin_capacity` never refuse. They answer a value, `nil` or an empty array. `segments(after, limit)`, `compaction_candidates(after, limit)` and `reclaimable(after, limit)` take both arguments every time: `after` is the last segment id you were given, or `nil` to begin, and `limit` bounds the Array (the core hands out an iterator instead). `after` has to be a number this journal issued: one whose segment has since been reclaimed still works as a position, but a number it never issued (another scope, sequence zero such as a bare `0`, or one it hasn't reached) is no position here, and the scan answers `[]`. Begin with `nil`, not `0`.
|
|
366
|
+
|
|
367
|
+
## The Rules of the Archivist
|
|
368
|
+
|
|
369
|
+
- **Everything is an Integer** in `0..2**64-1`: offsets, sizes, counts, times, ids, generations. Floats, nil, and strings raise `TypeError`. Out of range raises `RangeError`. A threshold may be `nil`, never zero. A missing argument raises `ArgumentError`: nothing has a default.
|
|
370
|
+
- **Time is Integer nanoseconds.** `now` (in `Journal.new`, `roll_decision` and `roll`), `max_age` and `Segment#opened_at` are nanoseconds on one monotonic clock: `Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond)`. A Float or any other non-Integer raises `TypeError`; a negative value or one past `2**64-1` raises `RangeError`.
|
|
371
|
+
- **Scopes.** A `Pin`, a `Replacement` and a segment id are only meaningful to the `Journal` that issued them. They are numbered from 1, so two journals hand out the same ones, and a handle given to the wrong journal would name a live pin or attempt there. One journal never repeats itself, though: segment ids, pin generations and attempt numbers come from a single sequence (the first segment is 1, and every roll, pin and proposal takes the next number), so a generation or an attempt passed where a segment id goes names no segment. Segment ids still ascend; they aren't consecutive. Give each journal its own scope: `Journal.with_scope(policy, base_offset, now, scope)`, any Integer in `0..65_535` (a non-Integer raises `TypeError`, anything outside the range raises `RangeError`). `Journal.new(policy, base_offset, now)` is scope zero. The scope rides in the top 16 bits of every segment id, pin generation and attempt number (and so of a rewritten segment's `revision`); `journal.scope`, `pin.scope` and `replacement.scope` read it back. A journal that never issued it, of another scope or not that far along, answers `:stale` to a pin or replacement (`nil` from `pin_offset`) and `:unknown` to a segment id (`nil` from `segment`, `[]` from the scans), and changes nothing. The journal can't pick a scope for you, and two journals left in the same scope still mix up each other's handles. `Pin` and `Replacement` objects can't be built by hand. They are values: two handles to the same pin acquisition or replacement attempt are `==` and `eql?` and hash alike, so the `replacement` of two reads of one proposed segment compares equal, and so do the two `Segment`s.
|
|
372
|
+
- **Values are valid or do not exist.** `Policy`, `Due`, `Rolled`, `Reclaimed` and `Segment` check themselves through the core when they are built, by hand or by the journal: `Due.new(:nope)`, `Rolled.new(2, 2, 10)`, `Reclaimed.new(1, 0, 9, 1)` or a `Segment` that is `:active` with records all raise `RangeError`; a String for a Symbol, `true` for `retention`, or an Integer for a `Replacement` raises `TypeError`. What the journal answers always passes, so `==` against a value you built means what it says. The values, and the `Pin` and `Replacement` handles, are final: subclassing one raises `TypeError` and `allocate` is gone. That stops accidents, not reflection (a named subclass still leaves its constant behind; `Marshal.load` and a hand-bound `Data#initialize` skip the check), so the extension is the authority: the `Policy` a journal opens with must be exactly a `Policy` (`TypeError` otherwise, a subclass included), and its fields are read natively and checked again by the core (`RangeError`).
|
|
373
|
+
- **The journal never loses work.** Every argument is converted before the journal is asked, and the value classes are resolved once, when the extension loads. So are the classes of `Journal`, `Pin` and `Replacement`: a handle is built with no Ruby code run, an instance of the class the gem defined even if the constant is later redefined, and a redefined `Object.const_get` is never consulted. Building an answer runs Ruby code (`new`, which a reopened class can redefine), so `roll` and `reclaim` decide on a copy, build the `Rolled` or `Reclaimed`, and keep the copy only if the journal is still unfrozen and unchanged: a `new` that raises applies nothing, one that freezes the journal raises `FrozenError`, one that calls back in and changes it raises `RuntimeError`, and the outer call is not applied.
|
|
374
|
+
- **The binding never loses work.** Everything that can raise (a bad argument, a frozen journal, a tracker whose readers raise) happens before the journal is asked; after it has changed, the binding only builds values from its answer. The scans read their segments into a buffer before building a single Ruby value.
|
|
375
|
+
- **Refusals don't raise.** `:segments_full`, `:pinned`, `:not_durable`, `:stale` and the rest are answers. A refused call changes nothing. Only malformed input raises.
|
|
376
|
+
- **Restarts.** A journal built again with `new` or `with_scope` numbers from 1 again, so a pin or replacement that outlived the restart could name a new entry. Either resume the numbering, `Journal.resumed(policy, base_offset, now, scope, issued)` with the `journal.issued` you saved from the journal before it, or give each incarnation its own scope. `resumed` restores the numbering and nothing else: segments and pins are yours to replay, and the one active segment takes the next number. It raises `RangeError` for an `issued` outside `0..2**48-2`. Save `issued` before you hand a number out: resuming from too low a count reissues.
|
|
377
|
+
- **Repeats aren't refusals, when they can be proved.** `:unchanged` and `:already_durable` mean the journal can see that exactly what you asked for was already done. Treat them as success. They change nothing. A repeat it can't prove is refused: a second `release`, `reclaim` or `abort` is `:stale` (it keeps neither the pins it released nor how an attempt ended), a second confirmation with different contents is `:mismatch`.
|
|
378
|
+
- **No pins means no objection.** The journal protects what is pinned. If nobody pinned a checkpoint, nothing stops a durable replacement from being reclaimed.
|
|
379
|
+
- **Frozen means frozen.** `freeze` the journal and every mutating call raises `FrozenError`.
|
|
380
|
+
|
|
381
|
+
## What You Think You're Doing vs Reality
|
|
382
|
+
|
|
383
|
+
### You Think: "The compacted file is written, so the old one can go."
|
|
384
|
+
### Reality: Written is not durable, and durable is not unread.
|
|
385
|
+
|
|
386
|
+
A file you wrote and didn't sync is a promise from the page cache. A file you synced can still be the wrong one to keep alone, if a reader holds a position in the original or recovery intends to replay through it. `reclaim` won't say yes until you've confirmed the first and every pin has cleared the second.
|
|
387
|
+
|
|
388
|
+
### You Think: "The consumer acknowledged it, so the checkpoint can move."
|
|
389
|
+
### Reality: Acknowledged is not committed.
|
|
390
|
+
|
|
391
|
+
Move the checkpoint pin to the offset your commit actually persisted, not to the one a worker says it finished. `pin_checkpoint_from` and `checkpoint_from` pair with `offset_machines` for exactly this: they pin at the tracker's confirmed base, never at what was merely acknowledged.
|
|
392
|
+
|
|
393
|
+
## What's Yours
|
|
394
|
+
|
|
395
|
+
Everything that touches a disk. You write the records, seal the files, rewrite the compacted copies, fsync, and delete. The journal keeps metadata in your process and loses it when the process dies. After a restart, rebuild a journal from what's on disk and from your own durable manifest (see Restarts above for its numbering), then re-pin readers and checkpoints before letting the reaper run. A half-finished replacement found on disk after a crash is yours to finish or discard. This is not a log writer, not a byte compactor and not a Raft log. It's an initial release and the API will move.
|
|
396
|
+
|
|
397
|
+
## License
|
|
398
|
+
|
|
399
|
+
MIT License. See [LICENSE.txt](LICENSE.txt) for details.
|
|
400
|
+
|
|
401
|
+
**Remember: anyone can delete a file. The question is whether someone was still reading it.**
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [0.8.1](https://github.com/seuros/journal_machines/compare/journal-machines-v0.8.0...journal-machines-v0.8.1) (2026-11-16)
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
### Bug Fixes
|
|
7
|
+
|
|
8
|
+
* fix wrapped classes at load so building a handle runs no Ruby ([f87e049](https://github.com/seuros/journal_machines/commit/f87e049d521da4c49f9b160a5247c2a94307aaf5))
|
|
9
|
+
|
|
10
|
+
## [0.8.0](https://github.com/seuros/journal_machines/compare/journal-machines-v0.7.0...journal-machines-v0.8.0) (2026-11-16)
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
### ⚠ BREAKING CHANGES
|
|
14
|
+
|
|
15
|
+
* replace Segment pinned bool with a Retention enum
|
|
16
|
+
|
|
17
|
+
### Features
|
|
18
|
+
|
|
19
|
+
* replace Segment pinned bool with a Retention enum ([98d6904](https://github.com/seuros/journal_machines/commit/98d690430cea94988b5ceb7389d7238999896dcd))
|
|
20
|
+
|
|
21
|
+
## [0.7.0](https://github.com/seuros/journal_machines/compare/journal-machines-v0.6.0...journal-machines-v0.7.0) (2026-11-14)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
### ⚠ BREAKING CHANGES
|
|
25
|
+
|
|
26
|
+
* adopt matryona-machines 0.2: exact-class Pin/Replacement handles, positive thresholds, compiler-checked symbol tables
|
|
27
|
+
|
|
28
|
+
### Features
|
|
29
|
+
|
|
30
|
+
* adopt matryona-machines 0.2: exact-class Pin/Replacement handles, positive thresholds, compiler-checked symbol tables ([53ef3b1](https://github.com/seuros/journal_machines/commit/53ef3b10ded3b1b994e2da14f04ecd5dcf5c7a7c))
|
|
31
|
+
|
|
32
|
+
## [0.6.0](https://github.com/seuros/journal_machines/compare/journal-machines-v0.5.0...journal-machines-v0.6.0) (2026-11-14)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
### ⚠ BREAKING CHANGES
|
|
36
|
+
|
|
37
|
+
* validate values through the core, value handles, native answers, read Policy by exact class, clone-then-keep roll/reclaim
|
|
38
|
+
|
|
39
|
+
### Features
|
|
40
|
+
|
|
41
|
+
* validate values through the core, value handles, native answers, read Policy by exact class, clone-then-keep roll/reclaim ([5b00d40](https://github.com/seuros/journal_machines/commit/5b00d406d92bdfb6f1ec331b60c61243ec013994))
|
|
42
|
+
|
|
43
|
+
## [0.5.0](https://github.com/seuros/journal_machines/compare/journal-machines-v0.4.0...journal-machines-v0.5.0) (2026-11-13)
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
### ⚠ BREAKING CHANGES
|
|
47
|
+
|
|
48
|
+
* handles are issued through periscope-machines. Every instance can be built with a scope; a handle from another scope is refused before any lookup; all handle kinds of an instance share one sequence; resumed restores the sequence after a restart. Handles of a journal no longer share raw values; release of a pin that is not held is Stale; the Ruby owner tag is gone.
|
|
49
|
+
|
|
50
|
+
### Features
|
|
51
|
+
|
|
52
|
+
* draw segment ids, pin generations and attempts from one scoped periscope sequence; add Journal::resumed ([6a9b959](https://github.com/seuros/journal_machines/commit/6a9b9597aceffa452dee5d74903f99b184a15d2e))
|
|
53
|
+
|
|
54
|
+
## [0.4.0](https://github.com/seuros/journal_machines/compare/journal-machines-v0.3.0...journal-machines-v0.4.0) (2026-11-13)
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
### ⚠ BREAKING CHANGES
|
|
58
|
+
|
|
59
|
+
* see CONVENTIONS: one exhaustive Refusal per crate, Result from every mutator, honoured idempotent repeats only when provable, Duration time, Ruby mirrors the core. No compatibility aliases. Requires offset-machines >= 0.3. A repeated confirm with another payload is Mismatch; releasing a pin that is not held is Stale.
|
|
60
|
+
|
|
61
|
+
### Features
|
|
62
|
+
|
|
63
|
+
* one Refusal enum with Result everywhere, provable repeats only, Duration time, Ruby Policy and _from pin calls ([f820899](https://github.com/seuros/journal_machines/commit/f8208990722b8407f206f8714c5708720f72dc74))
|
|
64
|
+
|
|
65
|
+
## [0.3.0](https://github.com/seuros/journal_machines/compare/journal-machines-v0.2.0...journal-machines-v0.3.0) (2026-11-13)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
### Features
|
|
69
|
+
|
|
70
|
+
* add pin_checkpoint_from and checkpoint_from to the Ruby journal ([a42f1da](https://github.com/seuros/journal_machines/commit/a42f1dace271d39d47264133d63bcd3d1101e441))
|
|
71
|
+
|
|
72
|
+
## [0.2.0](https://github.com/seuros/journal_machines/compare/journal-machines-v0.1.0...journal-machines-v0.2.0) (2026-11-12)
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
### Features
|
|
76
|
+
|
|
77
|
+
* initial extraction ([1e4f7a9](https://github.com/seuros/journal_machines/commit/1e4f7a9c3344bd27293fc3f51ee66e22d266e183))
|
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
# journal-machines
|
|
2
|
+
|
|
3
|
+
> **AMS Rosenblum**, NCC-4228, *Rosenblum*-class archive cutter.
|
|
4
|
+
|
|
5
|
+
Engine-room flight manual: know which log segments exist, and which may go.
|
|
6
|
+
|
|
7
|
+
Pre-1.0. Allocation-free `no_std` segment metadata policy for a
|
|
8
|
+
segmented log: when the active segment should roll, which sealed segments are
|
|
9
|
+
worth compacting, and when an original may be deleted.
|
|
10
|
+
|
|
11
|
+
This is not a log writer, a byte compactor or a Raft log. The journal never
|
|
12
|
+
touches a file. The caller writes, seals, compacts, fsyncs and deletes; the
|
|
13
|
+
journal holds the bookkeeping and refuses the unsafe order. `Journal<SEGMENTS,
|
|
14
|
+
PINS>` has compile-time capacities and refuses rather than grows.
|
|
15
|
+
|
|
16
|
+
Every call that can refuse returns `Result<T, Refusal>`. `T` says only what
|
|
17
|
+
was honoured; `Refusal` is the one enum for "this call was not honoured", and
|
|
18
|
+
a refused call leaves the journal exactly as it was. An idempotent repeat is
|
|
19
|
+
honoured, not refused: when what the caller asked for already holds, the call
|
|
20
|
+
answers `Ok` with a variant that says so, and still changes nothing. Only a
|
|
21
|
+
repeat the journal can prove is honoured: it must see, in its own state, that
|
|
22
|
+
the same call with the same arguments was already applied.
|
|
23
|
+
No public enum is `#[non_exhaustive]`: a new variant is a breaking change every
|
|
24
|
+
caller matches on.
|
|
25
|
+
|
|
26
|
+
Time is `core::time::Duration` on a monotonic clock whose epoch the caller
|
|
27
|
+
picks: `now`, a segment's `opened_at` and the policy's `max_age`. Offsets,
|
|
28
|
+
record and byte counts, ids, revisions and generations are `u64`.
|
|
29
|
+
|
|
30
|
+
- `Rolled::new(sealed, opened, next_offset)`, `Reclaimed::new(segment,
|
|
31
|
+
revision, bytes, replaced_by)` and `Segment::new(id, revision, base_offset,
|
|
32
|
+
records, stored_records, live_records, bytes, opened_at, state,
|
|
33
|
+
retention, replacement)` answer `Some` only for a value some journal could have
|
|
34
|
+
answered (issued ids of one scope, revisions and attempts drawn after their
|
|
35
|
+
segment, a segment whose counts, state, pin and replacement agree, storing its
|
|
36
|
+
whole range at revision 0). Their
|
|
37
|
+
fields are private: read them through the accessor of the same name, so no
|
|
38
|
+
value skips the check.
|
|
39
|
+
- `SegmentId`, `Pin` and `Replacement` are values: two handles to the same
|
|
40
|
+
identity are equal and hash alike. They have no order: an id carries its
|
|
41
|
+
journal's scope, so ids of two journals compare by nothing meaningful.
|
|
42
|
+
- `Segment::retention` is `Retention::Pinned` while a pin sits below the
|
|
43
|
+
segment's end, otherwise `Retention::Unpinned` (always, while active).
|
|
44
|
+
- `Policy::new(max_bytes, max_records, max_age, min_dead_per_mille)` takes
|
|
45
|
+
`Option<NonZeroU64>` sizes and an `Option<Duration>` age; `None` disables a
|
|
46
|
+
threshold. It answers `None` for a per-mille above 1000 or a zero age.
|
|
47
|
+
- `Journal::new(policy, base_offset, now)` opens the first segment at `now`,
|
|
48
|
+
in scope zero. `Journal::with_scope(policy, base_offset, now, scope)` does
|
|
49
|
+
the same under `scope`; `scope()` reads it back. See Scopes below.
|
|
50
|
+
- `Journal::resumed(policy, base_offset, now, scope, issued) -> Option<Journal>`
|
|
51
|
+
does the same after a restart, continuing the identity sequence after the
|
|
52
|
+
`issued()` count saved from the journal before it. See Restarts below.
|
|
53
|
+
- `roll_decision(bytes, records, now) -> Result<Roll, Refusal>` reads the
|
|
54
|
+
caller's observation of the active segment and answers `Keep` or
|
|
55
|
+
`Due(Size | Records | Age)` against the `Policy`. An empty segment is never
|
|
56
|
+
due. Refuses `NoActive`, `TimeRegression`, `Overflow`.
|
|
57
|
+
- `roll(bytes, records, now) -> Result<Rolled, Refusal>` records that the
|
|
58
|
+
caller sealed the active segment and opened the next. Refuses `NoActive`,
|
|
59
|
+
`Empty`, `TimeRegression`, `Overflow`, `SegmentsFull`, `Exhausted`.
|
|
60
|
+
- `observe_live(id, live) -> Result<(), Refusal>` records how many stored
|
|
61
|
+
records are still live. Refuses `Unknown`, `Active`, `Exceeds`.
|
|
62
|
+
`compaction_candidates(after)` iterates sealed segments whose dead share
|
|
63
|
+
meets `min_dead_per_mille`, oldest first; resume by passing the last id.
|
|
64
|
+
- `pin_reader(offset)` and `pin_checkpoint(assignment, offset)`
|
|
65
|
+
`-> Result<Pin, Refusal>` retain every offset at or after the pin. Refuse
|
|
66
|
+
`PinsFull`, `Exhausted`, and for a checkpoint `Unassigned`.
|
|
67
|
+
- `advance(pin, offset) -> Result<Advanced, Refusal>` moves a reader pin
|
|
68
|
+
forward and answers `Moved`, or `Unchanged` when the pin already sits
|
|
69
|
+
there. Refuses `Stale`, `WrongKind`, `Regressed`.
|
|
70
|
+
- `checkpoint(pin, assignment, offset) -> Result<Checkpointed, Refusal>`
|
|
71
|
+
answers `Advanced`, `Reassigned` when a newer assignment generation takes
|
|
72
|
+
over, or `Unchanged` when the same generation reports the offset the pin
|
|
73
|
+
already sits at. Refuses `Stale`, `WrongKind`, `Unassigned`,
|
|
74
|
+
`StaleAssignment`, `Regressed`: an older assignment cannot move the pin.
|
|
75
|
+
- `release(pin) -> Result<(), Refusal>` is checked against the acquisition
|
|
76
|
+
generation. Refuses `Stale` for a pin that is not held: released already,
|
|
77
|
+
or never issued here. Whoever holds the slot now keeps it.
|
|
78
|
+
- `propose(id) -> Result<Replacement, Refusal>` opens a replacement attempt.
|
|
79
|
+
Refuses `Unknown`, `Active`, `Busy`, `Exhausted`.
|
|
80
|
+
- `confirm_durable(handle, Rewritten { .. } | Superseded)`
|
|
81
|
+
`-> Result<Confirmed, Refusal>` records the caller's word that the
|
|
82
|
+
replacement is durable and answers `Recorded`, or `AlreadyDurable` when the
|
|
83
|
+
attempt was confirmed before with that same `Durable`. Refuses `Stale`,
|
|
84
|
+
`Exceeds`, and `Mismatch` when the attempt is already durable with a
|
|
85
|
+
different `Durable` (the other variant, or other `bytes` or `live_records`):
|
|
86
|
+
the first confirmation stands.
|
|
87
|
+
- `abort(handle) -> Result<(), Refusal>` gives up and keeps the original.
|
|
88
|
+
Refuses `Stale`.
|
|
89
|
+
- `reclaim(handle) -> Result<Reclaimed, Refusal>` succeeds only when the
|
|
90
|
+
replacement is durable **and** no pin of either kind sits below the
|
|
91
|
+
segment's end. Refuses `Stale`, `NotDurable`, `Pinned { offset }`. A
|
|
92
|
+
rewritten segment keeps its slot under a new revision; a superseded one
|
|
93
|
+
leaves the journal.
|
|
94
|
+
|
|
95
|
+
## Contract
|
|
96
|
+
|
|
97
|
+
### Scopes
|
|
98
|
+
|
|
99
|
+
Segment ids, `Pin` and `Replacement` handles are only meaningful to the
|
|
100
|
+
journal that issued them. Each is built on an integer (a segment id; a slot
|
|
101
|
+
and a pin generation; a segment id and an attempt number) drawn from one
|
|
102
|
+
sequence the journal counts from one, so two journals issue the same ones,
|
|
103
|
+
and a handle given to the wrong journal names a live pin or attempt there. Give each journal its own scope with
|
|
104
|
+
`Journal::with_scope`: the scope rides in the top 16 bits of every segment
|
|
105
|
+
id, pin generation and attempt number, in the
|
|
106
|
+
[`periscope-machines`](https://crates.io/crates/periscope-machines) layout,
|
|
107
|
+
and `SegmentId::scope()`, `Pin::scope()` and `Replacement::scope()` read it.
|
|
108
|
+
`Journal::new` is scope zero and issues the plain numbers 1, 2, 3.
|
|
109
|
+
|
|
110
|
+
One sequence serves all three kinds: the active segment takes 1, and every
|
|
111
|
+
roll, pin and proposal takes the next number. No two handles of a journal
|
|
112
|
+
share a raw value, so a pin generation or an attempt (which is also a
|
|
113
|
+
rewritten segment's `revision`) passed to `SegmentId::from_raw` names no
|
|
114
|
+
segment. Segment ids still ascend in offset order; they are not consecutive.
|
|
115
|
+
|
|
116
|
+
An identity this journal never issued, of another scope or beyond what it
|
|
117
|
+
has issued, names nothing here, and is refused before anything is looked up,
|
|
118
|
+
with nothing changed: a pin or a replacement is
|
|
119
|
+
`Stale` (`None` from `pin_offset`), a segment id is `Unknown` (`None` from
|
|
120
|
+
`segment`, an empty iterator as a resume position). A `Replacement` is
|
|
121
|
+
refused if either its attempt or its segment was never issued here. The
|
|
122
|
+
journal reads no clock and no random source, so it cannot pick a scope; two
|
|
123
|
+
journals left in the same scope still alias. A scope holds 2^48 - 1
|
|
124
|
+
identities, all kinds together. A rewritten segment's `revision` is the
|
|
125
|
+
attempt that rewrote it, so it carries the scope too.
|
|
126
|
+
|
|
127
|
+
### Restarts
|
|
128
|
+
|
|
129
|
+
A journal started again with `new` or `with_scope` counts from one again, so
|
|
130
|
+
a handle that outlived the restart could name a new entry. Either resume the
|
|
131
|
+
sequence, `Journal::resumed(policy, base_offset, now, scope, issued)` with
|
|
132
|
+
the `issued()` saved from the journal before it, or give each incarnation a
|
|
133
|
+
scope of its own. `resumed` restores the sequence and nothing else: segments
|
|
134
|
+
and pins are replayed by the caller, and the one active segment takes the
|
|
135
|
+
next number. It is `None` when `issued` is more than a scope holds or leaves
|
|
136
|
+
no identity for the active segment. Resuming from a count lower than what was
|
|
137
|
+
really issued reissues: save `issued()` before handing an identity out.
|
|
138
|
+
|
|
139
|
+
### Repeats
|
|
140
|
+
|
|
141
|
+
`Advanced::Unchanged`, `Checkpointed::Unchanged` and
|
|
142
|
+
`Confirmed::AlreadyDurable` are answered from a live pin or a live attempt,
|
|
143
|
+
which only a handle this journal issued reaches. No repeat is honoured on a
|
|
144
|
+
handle that is no longer live. A second `release` is `Stale`: pin
|
|
145
|
+
generations share the sequence with segment ids and attempts, so "issued
|
|
146
|
+
here and held in no slot" is as true of a segment id as of a released pin,
|
|
147
|
+
and the journal keeps no record of which numbers were pins. A second
|
|
148
|
+
`reclaim` or `abort` is `Stale` too: an attempt that is no longer current was
|
|
149
|
+
aborted, reclaimed as a rewrite or reclaimed as superseded, and the journal
|
|
150
|
+
does not keep which.
|
|
151
|
+
|
|
152
|
+
`Stale` always means a handle that is not current, pin or replacement, or one
|
|
153
|
+
this journal never issued.
|
|
154
|
+
`Mismatch` always means a repeat that carries something other than what was
|
|
155
|
+
recorded.
|
|
156
|
+
`Regressed` stays a refusal: a pin asked to move back is asking for retention
|
|
157
|
+
the journal can no longer promise.
|
|
158
|
+
`Exhausted` always means the journal's identity sequence is spent: 2^48 - 1
|
|
159
|
+
segment ids, pin generations and attempts together per scope. `Overflow` is
|
|
160
|
+
only the offset range.
|
|
161
|
+
`active`, `segment`, `covering`, the iterators, `pin_offset`, `low_pin` and
|
|
162
|
+
`pins` read only and never refuse.
|
|
163
|
+
|
|
164
|
+
### Resume positions
|
|
165
|
+
|
|
166
|
+
`segments`, `compaction_candidates` and `reclaimable` take `after:
|
|
167
|
+
Option<SegmentId>`, a position rather than a handle: nothing is looked up by
|
|
168
|
+
it, and the segment it named may have left the journal since. It must still
|
|
169
|
+
be a number this journal issued (`Issuer::owns`): one of another scope, a
|
|
170
|
+
zero sequence or one not reached is no position, and the iterator is empty.
|
|
171
|
+
That is the same line every other call draws for identities, and it keeps a
|
|
172
|
+
bare `0` (a common stand-in for "from the start") from silently meaning
|
|
173
|
+
"everything". `None` is the one way to begin. Any issued number works, a pin
|
|
174
|
+
generation or an attempt included, because one sequence orders them all.
|
|
175
|
+
|
|
176
|
+
### Which answers record the clock
|
|
177
|
+
|
|
178
|
+
The journal keeps no watermark. The only instants it holds are its segments'
|
|
179
|
+
opening times, and a regression is judged against the active segment's.
|
|
180
|
+
`new`, `with_scope`, `resumed` and an honoured `roll` record `now` as the
|
|
181
|
+
opening of the new active segment: their answer depends on the instant.
|
|
182
|
+
`roll_decision` reads only and records nothing; its answer is about the
|
|
183
|
+
instant supplied. No other call takes a clock, and no honoured repeat
|
|
184
|
+
(`Unchanged`, `AlreadyDurable`) records anything.
|
|
185
|
+
|
|
186
|
+
### Unreachable arms
|
|
187
|
+
|
|
188
|
+
There are none, and no slot is indexed by a number that could be out of
|
|
189
|
+
range. A lookup by segment id or pin hands back the slot itself, so nothing
|
|
190
|
+
is looked up twice; `roll` takes the active slot and the one after it as one
|
|
191
|
+
pair, whose absence is `SegmentsFull`; a superseded segment leaves by a walk
|
|
192
|
+
over the tracked slots; and the issuer's `Exhausted` is the journal's own
|
|
193
|
+
`Exhausted` (`From<periscope_machines::Refusal>`).
|
|
194
|
+
|
|
195
|
+
Checkpoint pins compose with `offset-machines`: `pin_checkpoint_from(&tracker)`
|
|
196
|
+
and `checkpoint_from(pin, &tracker)` pin at the tracker's confirmed-committed
|
|
197
|
+
base under its assignment generation, never at merely acknowledged offsets. An
|
|
198
|
+
unassigned tracker is refused as `Unassigned`, an older assignment as
|
|
199
|
+
`StaleAssignment`; a tracker whose base has not moved is `Unchanged`. The Ruby gem offers the same two calls over any object
|
|
200
|
+
with `generation` and `base` readers, such as `OffsetMachines::Tracker`.
|
|
201
|
+
|
|
202
|
+
Durability is the caller's claim; the journal cannot check it. Filesystem
|
|
203
|
+
operations, crash recovery and rebuilding this metadata after a restart stay
|
|
204
|
+
outside. Persist what you need and replay it into a resumed journal.
|
|
205
|
+
|
|
206
|
+
```rust
|
|
207
|
+
use core::{num::NonZeroU64, time::Duration};
|
|
208
|
+
use journal_machines::{
|
|
209
|
+
Advanced, Checkpointed, Confirmed, Durable, Journal, Policy, Refusal, Roll, RollReason,
|
|
210
|
+
};
|
|
211
|
+
# fn main() -> Result<(), Box<dyn core::error::Error>> {
|
|
212
|
+
|
|
213
|
+
let hour = Duration::from_secs(3600);
|
|
214
|
+
let policy = Policy::new(NonZeroU64::new(1024), None, Some(hour), 500).ok_or("policy")?;
|
|
215
|
+
let mut journal = Journal::<8, 4>::new(policy, 0, Duration::ZERO);
|
|
216
|
+
let now = Duration::from_secs(5);
|
|
217
|
+
assert_eq!(journal.roll_decision(2048, 10, now), Ok(Roll::Due(RollReason::Size)));
|
|
218
|
+
assert_eq!(journal.roll_decision(1, 1, hour), Ok(Roll::Due(RollReason::Age)));
|
|
219
|
+
let rolled = journal.roll(2048, 10, now)?;
|
|
220
|
+
|
|
221
|
+
let checkpoint = journal.pin_checkpoint(1, 0)?;
|
|
222
|
+
let reader = journal.pin_reader(0)?;
|
|
223
|
+
assert_eq!(journal.observe_live(rolled.sealed(), 2), Ok(()));
|
|
224
|
+
assert_eq!(journal.compaction_candidates(None).next().map(|s| s.id()), Some(rolled.sealed()));
|
|
225
|
+
|
|
226
|
+
let replacement = journal.propose(rolled.sealed())?;
|
|
227
|
+
assert_eq!(journal.reclaim(replacement), Err(Refusal::NotDurable));
|
|
228
|
+
let rewritten = Durable::Rewritten { bytes: 400, live_records: 2 };
|
|
229
|
+
assert_eq!(journal.confirm_durable(replacement, rewritten), Ok(Confirmed::Recorded));
|
|
230
|
+
assert_eq!(journal.confirm_durable(replacement, rewritten), Ok(Confirmed::AlreadyDurable));
|
|
231
|
+
assert_eq!(journal.confirm_durable(replacement, Durable::Superseded), Err(Refusal::Mismatch));
|
|
232
|
+
assert_eq!(journal.reclaim(replacement), Err(Refusal::Pinned { offset: 0 }));
|
|
233
|
+
|
|
234
|
+
assert_eq!(journal.advance(reader, 10), Ok(Advanced::Moved));
|
|
235
|
+
assert_eq!(journal.advance(reader, 10), Ok(Advanced::Unchanged));
|
|
236
|
+
assert_eq!(journal.release(reader), Ok(()));
|
|
237
|
+
assert_eq!(journal.release(reader), Err(Refusal::Stale));
|
|
238
|
+
assert_eq!(journal.advance(reader, 11), Err(Refusal::Stale));
|
|
239
|
+
|
|
240
|
+
// One sequence for every kind: no two handles share a raw value.
|
|
241
|
+
assert_eq!((rolled.sealed().raw(), rolled.opened().raw()), (1, 2));
|
|
242
|
+
assert_eq!((checkpoint.generation(), reader.generation()), (3, 4));
|
|
243
|
+
assert_eq!((replacement.attempt(), journal.issued()), (5, 5));
|
|
244
|
+
|
|
245
|
+
// A journal of another scope issues the same sequence numbers under its own
|
|
246
|
+
// scope, and neither takes the other's handles.
|
|
247
|
+
let mut other = Journal::<8, 4>::with_scope(policy, 0, Duration::ZERO, 7);
|
|
248
|
+
let theirs = other.pin_checkpoint(1, 0)?;
|
|
249
|
+
assert_eq!((checkpoint.scope(), theirs.scope()), (0, 7));
|
|
250
|
+
assert_eq!(journal.release(theirs), Err(Refusal::Stale));
|
|
251
|
+
assert_eq!(other.checkpoint(checkpoint, 1, 10), Err(Refusal::Stale));
|
|
252
|
+
assert_eq!(journal.checkpoint(checkpoint, 1, 10), Ok(Checkpointed::Advanced));
|
|
253
|
+
assert_eq!(journal.checkpoint(checkpoint, 1, 10), Ok(Checkpointed::Unchanged));
|
|
254
|
+
assert_eq!(journal.reclaim(replacement)?.bytes(), 2048);
|
|
255
|
+
|
|
256
|
+
// After a restart, continue the sequence from the saved count.
|
|
257
|
+
let resumed = Journal::<8, 4>::resumed(policy, 20, now, 0, journal.issued()).ok_or("resume")?;
|
|
258
|
+
assert_eq!(resumed.active().map(|segment| segment.id().raw()), Some(6));
|
|
259
|
+
# Ok(())
|
|
260
|
+
# }
|
|
261
|
+
```
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
require_relative 'journal_machines/version'
|
|
4
|
+
|
|
5
|
+
module JournalMachines
|
|
6
|
+
# Roll thresholds and the dead-record ratio that makes a segment worth
|
|
7
|
+
# compacting. A nil threshold never triggers; `max_age` is a span in Integer
|
|
8
|
+
# nanoseconds. Like the core's `Policy::new`, an invalid policy cannot be
|
|
9
|
+
# built: a zero threshold or a ratio above 1000 raises RangeError.
|
|
10
|
+
Policy = Data.define(:max_bytes, :max_records, :max_age, :min_dead_per_mille) do
|
|
11
|
+
def initialize(max_bytes:, max_records:, max_age:, min_dead_per_mille:)
|
|
12
|
+
Journal.__send__(:__check_policy, max_bytes, max_records, max_age, min_dead_per_mille)
|
|
13
|
+
super
|
|
14
|
+
end
|
|
15
|
+
end
|
|
16
|
+
# Immutable point-in-time view of one segment's metadata. `opened_at` is
|
|
17
|
+
# Integer nanoseconds on the monotonic clock the journal was given. Like the
|
|
18
|
+
# core's `Segment::checked`, it holds only what some journal could answer:
|
|
19
|
+
# anything else raises RangeError (TypeError for a wrong type: Integers,
|
|
20
|
+
# a state Symbol, a retention Symbol (:pinned or :unpinned), a Replacement
|
|
21
|
+
# or nil).
|
|
22
|
+
Segment = Data.define(
|
|
23
|
+
:id, :revision, :base_offset, :records, :stored_records, :live_records,
|
|
24
|
+
:bytes, :opened_at, :state, :retention, :replacement
|
|
25
|
+
) do
|
|
26
|
+
def initialize(id:, revision:, base_offset:, records:, stored_records:, live_records:, bytes:, opened_at:,
|
|
27
|
+
state:, retention:, replacement:)
|
|
28
|
+
Journal.__send__(:__check_segment, [id, revision, base_offset, records],
|
|
29
|
+
[stored_records, live_records, bytes, opened_at], state, retention, replacement)
|
|
30
|
+
super
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
def end_offset = base_offset + records
|
|
34
|
+
end
|
|
35
|
+
# Journal#roll_decision when a threshold was reached: the core's
|
|
36
|
+
# `Roll::Due(reason)`. `reason` is :size, :records or :age, checked in that
|
|
37
|
+
# order. The other answer, `Roll::Keep`, is the symbol :keep. Any other
|
|
38
|
+
# Symbol raises RangeError, a non-Symbol TypeError.
|
|
39
|
+
Due = Data.define(:reason) do
|
|
40
|
+
def initialize(reason:)
|
|
41
|
+
Journal.__send__(:__check_due, reason)
|
|
42
|
+
super
|
|
43
|
+
end
|
|
44
|
+
end
|
|
45
|
+
# A recorded roll: the sealed segment, the new active one and its first
|
|
46
|
+
# offset. Like the core's `Rolled::new`: two issued ids of one scope, the
|
|
47
|
+
# opened one drawn after the sealed one, and a positive next offset, or
|
|
48
|
+
# RangeError (TypeError for a non-Integer).
|
|
49
|
+
Rolled = Data.define(:sealed, :opened, :next_offset) do
|
|
50
|
+
def initialize(sealed:, opened:, next_offset:)
|
|
51
|
+
Journal.__send__(:__check_rolled, sealed, opened, next_offset)
|
|
52
|
+
super
|
|
53
|
+
end
|
|
54
|
+
end
|
|
55
|
+
# Permission to delete one original segment file. Like the core's
|
|
56
|
+
# `Reclaimed::new`: an issued segment id, a revision of 0 or an attempt drawn
|
|
57
|
+
# after it, and a replaced_by (nil or Integer) later still, or RangeError
|
|
58
|
+
# (TypeError for a non-Integer).
|
|
59
|
+
Reclaimed = Data.define(:segment, :revision, :bytes, :replaced_by) do
|
|
60
|
+
def initialize(segment:, revision:, bytes:, replaced_by:)
|
|
61
|
+
Journal.__send__(:__check_reclaimed, segment, revision, bytes, replaced_by)
|
|
62
|
+
super
|
|
63
|
+
end
|
|
64
|
+
end
|
|
65
|
+
|
|
66
|
+
end
|
|
67
|
+
|
|
68
|
+
# Native is required: no algorithm fallback. It resolves the Data values above
|
|
69
|
+
# once, so they must exist first.
|
|
70
|
+
require 'journal_machines_native/journal_machines_native'
|
|
71
|
+
|
|
72
|
+
module JournalMachines
|
|
73
|
+
# Pin and Replacement handles are values: two handles naming the same pin
|
|
74
|
+
# acquisition or replacement attempt are == and eql?, and hash alike. Only
|
|
75
|
+
# the journal builds them, and they are final like the values below.
|
|
76
|
+
|
|
77
|
+
# The values are final. `initialize` is where each validates, and a subclass
|
|
78
|
+
# could override it, or `allocate` build an instance that never ran it:
|
|
79
|
+
# subclassing raises TypeError and `allocate` is gone. That stops accidents,
|
|
80
|
+
# not reflection (Ruby binds a named subclass's constant before `inherited`
|
|
81
|
+
# raises; `Marshal.load` and a hand-bound `Data#initialize` skip the check),
|
|
82
|
+
# so the extension is the authority: the one value it reads back, a Policy,
|
|
83
|
+
# must be exactly a Policy and is checked again by the core.
|
|
84
|
+
[Policy, Segment, Due, Rolled, Reclaimed, Pin, Replacement].each do |value|
|
|
85
|
+
value.singleton_class.undef_method(:allocate)
|
|
86
|
+
value.define_singleton_method(:inherited) { |_| raise TypeError, "#{value} cannot be subclassed" }
|
|
87
|
+
end
|
|
88
|
+
|
|
89
|
+
class Journal
|
|
90
|
+
private_class_method :__open, :__check_policy, :__check_due, :__check_rolled, :__check_reclaimed,
|
|
91
|
+
:__check_segment
|
|
92
|
+
|
|
93
|
+
# One active segment at `base_offset`, opened at `now`: Integer nanoseconds
|
|
94
|
+
# of a monotonic clock (Process.clock_gettime(Process::CLOCK_MONOTONIC,
|
|
95
|
+
# :nanosecond)). Every later `now` passed to #roll_decision and #roll is
|
|
96
|
+
# read on the same clock. The journal is in scope zero.
|
|
97
|
+
def self.new(policy, base_offset, now) = with_scope(policy, base_offset, now, 0)
|
|
98
|
+
|
|
99
|
+
# As Journal.new, with every segment id, pin generation and attempt number
|
|
100
|
+
# the journal issues carrying `scope`: an Integer in 0..65_535. A journal
|
|
101
|
+
# of another scope answers :stale to its pins and replacements and
|
|
102
|
+
# :unknown to its segment ids. Give each journal its own scope.
|
|
103
|
+
def self.with_scope(policy, base_offset, now, scope) = resumed(policy, base_offset, now, scope, 0)
|
|
104
|
+
|
|
105
|
+
# As Journal.with_scope after a restart: the journal continues the one
|
|
106
|
+
# sequence its ids, generations and attempts are drawn from after
|
|
107
|
+
# `issued`, the #issued saved from the journal before it, so nothing that
|
|
108
|
+
# journal handed out is issued again. Segments and pins are not restored.
|
|
109
|
+
# RangeError when `issued` leaves no number for the active segment.
|
|
110
|
+
# `policy` must be exactly a Policy (TypeError otherwise); the extension
|
|
111
|
+
# reads its fields and checks them again.
|
|
112
|
+
def self.resumed(policy, base_offset, now, scope, issued) = __open(base_offset, now, [scope, issued], policy)
|
|
113
|
+
|
|
114
|
+
def policy = Policy.new(*__policy)
|
|
115
|
+
|
|
116
|
+
def segment_capacity = SEGMENT_CAPACITY
|
|
117
|
+
|
|
118
|
+
def pin_capacity = PIN_CAPACITY
|
|
119
|
+
|
|
120
|
+
# The binding builds every answer (Segment, Rolled, Reclaimed, Due) after
|
|
121
|
+
# the core call, from what the core returned; #roll and #reclaim decide on
|
|
122
|
+
# a copy and keep it only once the answer is built and the journal is
|
|
123
|
+
# still unfrozen and unchanged (FrozenError, RuntimeError otherwise, with
|
|
124
|
+
# nothing applied). #segments,
|
|
125
|
+
# #compaction_candidates and #reclaimable answer at most `limit` segments
|
|
126
|
+
# after segment id `after` (nil to begin), in ascending id order; resume by
|
|
127
|
+
# passing the last id answered. An `after` this journal never issued
|
|
128
|
+
# (another scope, sequence zero, not reached) is no position: [].
|
|
129
|
+
|
|
130
|
+
# Pin a checkpoint at a tracker's confirmed-committed base, under its
|
|
131
|
+
# assignment generation, and move a checkpoint pin to one
|
|
132
|
+
# (#checkpoint_from(pin, tracker)): both are native. The tracker is a
|
|
133
|
+
# sibling gem's value, read by its public `generation` and `base` readers,
|
|
134
|
+
# each asked for before either runs; TypeError naming the reader it lacks.
|
|
135
|
+
|
|
136
|
+
private :__policy
|
|
137
|
+
end
|
|
138
|
+
end
|
|
Binary file
|
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
module JournalMachines
|
|
2
|
+
VERSION: String
|
|
3
|
+
SEGMENT_CAPACITY: Integer
|
|
4
|
+
PIN_CAPACITY: Integer
|
|
5
|
+
type roll_reason = :size | :records | :age
|
|
6
|
+
type segment_state = :active | :sealed | :proposed | :durable | :reclaimable
|
|
7
|
+
type retention = :unpinned | :pinned
|
|
8
|
+
# Integer nanoseconds on one monotonic clock, for instants and spans alike:
|
|
9
|
+
# Process.clock_gettime(Process::CLOCK_MONOTONIC, :nanosecond). A non-Integer
|
|
10
|
+
# raises TypeError; a value outside 0..2**64-1 raises RangeError.
|
|
11
|
+
type nanoseconds = Integer
|
|
12
|
+
# Every symbol that means "this call was not honoured and changed nothing".
|
|
13
|
+
# One per core `Refusal` variant, no catch-all. Each method below lists
|
|
14
|
+
# exactly the ones it can answer.
|
|
15
|
+
type refusal = :no_active | :empty | :time_regression | :overflow | :segments_full | :pins_full | :exhausted
|
|
16
|
+
| :unknown | :active | :busy | :exceeds | :mismatch | :stale | :wrong_kind | :unassigned
|
|
17
|
+
| :stale_assignment | :regressed | :not_durable | :pinned
|
|
18
|
+
# Honoured idempotent repeats the journal can prove: what was asked for
|
|
19
|
+
# already holds, nothing changed. :unchanged (advance, checkpoint,
|
|
20
|
+
# checkpoint_from) and :already_durable (confirm_rewritten,
|
|
21
|
+
# confirm_superseded, with the payload that was recorded) are answers, not
|
|
22
|
+
# refusals. A second release, reclaim or abort is not one: it is :stale.
|
|
23
|
+
type repeat = :unchanged | :already_durable
|
|
24
|
+
type roll_refusal = :no_active | :empty | :time_regression | :overflow | :segments_full | :exhausted
|
|
25
|
+
type roll_decision_refusal = :no_active | :time_regression | :overflow
|
|
26
|
+
type observe_refusal = :unknown | :active | :exceeds
|
|
27
|
+
type pin_reader_refusal = :pins_full | :exhausted
|
|
28
|
+
type pin_checkpoint_refusal = :unassigned | :pins_full | :exhausted
|
|
29
|
+
type advance_refusal = :stale | :wrong_kind | :regressed
|
|
30
|
+
type checkpoint_refusal = :stale | :wrong_kind | :unassigned | :stale_assignment | :regressed
|
|
31
|
+
type release_refusal = :stale
|
|
32
|
+
type propose_refusal = :unknown | :active | :busy | :exhausted
|
|
33
|
+
type confirm_rewritten_refusal = :stale | :mismatch | :exceeds
|
|
34
|
+
type confirm_superseded_refusal = :stale | :mismatch
|
|
35
|
+
type reclaim_refusal = :stale | :not_durable | :pinned
|
|
36
|
+
type abort_refusal = :stale
|
|
37
|
+
interface _Tracker
|
|
38
|
+
def generation: () -> Integer
|
|
39
|
+
def base: () -> Integer
|
|
40
|
+
end
|
|
41
|
+
# A Pin, a Replacement or a segment id is only meaningful to the Journal
|
|
42
|
+
# that issued it. Each carries that journal's scope in the top 16 bits of
|
|
43
|
+
# its generation, attempt or id, above a number of the one sequence the
|
|
44
|
+
# journal counts from 1 for all three, so no two of them are equal. A
|
|
45
|
+
# Journal that never issued it answers :stale to a Pin or Replacement (nil
|
|
46
|
+
# from pin_offset) and :unknown to a segment id (nil from segment, [] from
|
|
47
|
+
# the scans as a resume position). Two Journals left in the same scope
|
|
48
|
+
# cannot tell their handles apart.
|
|
49
|
+
class Pin
|
|
50
|
+
def kind: () -> (:reader | :checkpoint)
|
|
51
|
+
def generation: () -> Integer
|
|
52
|
+
# The scope of the Journal that issued this pin.
|
|
53
|
+
def scope: () -> Integer
|
|
54
|
+
# A value: equal to, and hashing like, any handle to the same identity.
|
|
55
|
+
def ==: (untyped other) -> bool
|
|
56
|
+
def eql?: (untyped other) -> bool
|
|
57
|
+
def hash: () -> Integer
|
|
58
|
+
end
|
|
59
|
+
class Replacement
|
|
60
|
+
def segment: () -> Integer
|
|
61
|
+
def attempt: () -> Integer
|
|
62
|
+
# The scope of the Journal that issued this attempt.
|
|
63
|
+
def scope: () -> Integer
|
|
64
|
+
# A value: equal to, and hashing like, any handle to the same identity.
|
|
65
|
+
def ==: (untyped other) -> bool
|
|
66
|
+
def eql?: (untyped other) -> bool
|
|
67
|
+
def hash: () -> Integer
|
|
68
|
+
end
|
|
69
|
+
# The core's Policy: same fields, same order, no defaults. A zero threshold
|
|
70
|
+
# or a ratio above 1000 raises RangeError; a non-Integer raises TypeError.
|
|
71
|
+
class Policy < Data
|
|
72
|
+
attr_reader max_bytes: Integer?
|
|
73
|
+
attr_reader max_records: Integer?
|
|
74
|
+
attr_reader max_age: nanoseconds?
|
|
75
|
+
attr_reader min_dead_per_mille: Integer
|
|
76
|
+
def self.new: (Integer? max_bytes, Integer? max_records, nanoseconds? max_age, Integer min_dead_per_mille) -> Policy
|
|
77
|
+
| (max_bytes: Integer?, max_records: Integer?, max_age: nanoseconds?, min_dead_per_mille: Integer) -> Policy
|
|
78
|
+
end
|
|
79
|
+
# The core's Segment. `new` mirrors `Segment::checked`: RangeError unless
|
|
80
|
+
# some journal could answer these eleven values together (an issued id; an
|
|
81
|
+
# active segment holding nothing; a closed one with records >= stored >=
|
|
82
|
+
# live; a replacement exactly when proposed, durable or reclaimable;
|
|
83
|
+
# durable :pinned, reclaimable :unpinned, active :unpinned). TypeError for a
|
|
84
|
+
# wrong type.
|
|
85
|
+
class Segment < Data
|
|
86
|
+
attr_reader id: Integer
|
|
87
|
+
attr_reader revision: Integer
|
|
88
|
+
attr_reader base_offset: Integer
|
|
89
|
+
attr_reader records: Integer
|
|
90
|
+
attr_reader stored_records: Integer
|
|
91
|
+
attr_reader live_records: Integer
|
|
92
|
+
attr_reader bytes: Integer
|
|
93
|
+
attr_reader opened_at: nanoseconds
|
|
94
|
+
attr_reader state: segment_state
|
|
95
|
+
attr_reader retention: retention
|
|
96
|
+
attr_reader replacement: Replacement?
|
|
97
|
+
def self.new: (Integer id, Integer revision, Integer base_offset, Integer records, Integer stored_records,
|
|
98
|
+
Integer live_records, Integer bytes, nanoseconds opened_at, segment_state state, retention retention,
|
|
99
|
+
Replacement? replacement) -> Segment
|
|
100
|
+
| (id: Integer, revision: Integer, base_offset: Integer, records: Integer, stored_records: Integer,
|
|
101
|
+
live_records: Integer, bytes: Integer, opened_at: nanoseconds, state: segment_state, retention: retention,
|
|
102
|
+
replacement: Replacement?) -> Segment
|
|
103
|
+
def end_offset: () -> Integer
|
|
104
|
+
end
|
|
105
|
+
# The core's Roll::Due(reason); Roll::Keep is the symbol :keep. Another
|
|
106
|
+
# Symbol raises RangeError, a non-Symbol TypeError.
|
|
107
|
+
class Due < Data
|
|
108
|
+
attr_reader reason: roll_reason
|
|
109
|
+
def self.new: (roll_reason reason) -> Due
|
|
110
|
+
| (reason: roll_reason) -> Due
|
|
111
|
+
end
|
|
112
|
+
# The core's Rolled. `new` mirrors `Rolled::new`: RangeError unless both ids
|
|
113
|
+
# are issued ids of one scope, opened drawn after sealed, and next_offset is
|
|
114
|
+
# positive. TypeError for a non-Integer.
|
|
115
|
+
class Rolled < Data
|
|
116
|
+
attr_reader sealed: Integer
|
|
117
|
+
attr_reader opened: Integer
|
|
118
|
+
attr_reader next_offset: Integer
|
|
119
|
+
def self.new: (Integer sealed, Integer opened, Integer next_offset) -> Rolled
|
|
120
|
+
| (sealed: Integer, opened: Integer, next_offset: Integer) -> Rolled
|
|
121
|
+
end
|
|
122
|
+
# The core's Reclaimed. `new` mirrors `Reclaimed::new`: RangeError unless the
|
|
123
|
+
# segment id is issued, revision is 0 or an attempt drawn after it, and
|
|
124
|
+
# replaced_by is nil or a later attempt still. TypeError for a non-Integer.
|
|
125
|
+
class Reclaimed < Data
|
|
126
|
+
attr_reader segment: Integer
|
|
127
|
+
attr_reader revision: Integer
|
|
128
|
+
attr_reader bytes: Integer
|
|
129
|
+
attr_reader replaced_by: Integer?
|
|
130
|
+
def self.new: (Integer segment, Integer revision, Integer bytes, Integer? replaced_by) -> Reclaimed
|
|
131
|
+
| (segment: Integer, revision: Integer, bytes: Integer, replaced_by: Integer?) -> Reclaimed
|
|
132
|
+
end
|
|
133
|
+
class Journal
|
|
134
|
+
# A journal in scope zero.
|
|
135
|
+
def self.new: (Policy policy, Integer base_offset, nanoseconds now) -> Journal
|
|
136
|
+
# A journal whose segment ids, pin generations and attempt numbers carry
|
|
137
|
+
# `scope`, an Integer in 0..65_535 (TypeError for a non-Integer,
|
|
138
|
+
# RangeError outside the range).
|
|
139
|
+
def self.with_scope: (Policy policy, Integer base_offset, nanoseconds now, Integer scope) -> Journal
|
|
140
|
+
# A journal of `scope` after a restart, continuing the sequence after
|
|
141
|
+
# `issued`: the #issued saved from the journal before it. Segments and
|
|
142
|
+
# pins are not restored. RangeError for an `issued` outside 0..2**48-2,
|
|
143
|
+
# which would leave no number for the active segment.
|
|
144
|
+
def self.resumed: (Policy policy, Integer base_offset, nanoseconds now, Integer scope, Integer issued) -> Journal
|
|
145
|
+
def scope: () -> Integer
|
|
146
|
+
# How many segment ids, pin generations and attempts, together, the
|
|
147
|
+
# journal has issued. Save it to resume after a restart.
|
|
148
|
+
def issued: () -> Integer
|
|
149
|
+
def policy: () -> Policy
|
|
150
|
+
def segment_capacity: () -> Integer
|
|
151
|
+
def pin_capacity: () -> Integer
|
|
152
|
+
def size: () -> Integer
|
|
153
|
+
def empty?: () -> bool
|
|
154
|
+
def roll_decision: (Integer bytes, Integer records, nanoseconds now) -> (:keep | Due | roll_decision_refusal)
|
|
155
|
+
def roll: (Integer bytes, Integer records, nanoseconds now) -> (Rolled | roll_refusal)
|
|
156
|
+
def observe_live: (Integer id, Integer live_records) -> (:recorded | observe_refusal)
|
|
157
|
+
def active: () -> Segment?
|
|
158
|
+
def segment: (Integer id) -> Segment?
|
|
159
|
+
def covering: (Integer offset) -> Segment?
|
|
160
|
+
# `after` must be an id this journal issued (any of its segment ids, pin
|
|
161
|
+
# generations or attempts, even one whose segment has left); one it never
|
|
162
|
+
# issued (another scope, sequence zero, not reached) is no position: [].
|
|
163
|
+
def segments: (Integer? after, Integer limit) -> Array[Segment]
|
|
164
|
+
def compaction_candidates: (Integer? after, Integer limit) -> Array[Segment]
|
|
165
|
+
def reclaimable: (Integer? after, Integer limit) -> Array[Segment]
|
|
166
|
+
def pin_reader: (Integer offset) -> (Pin | pin_reader_refusal)
|
|
167
|
+
def pin_checkpoint: (Integer assignment, Integer offset) -> (Pin | pin_checkpoint_refusal)
|
|
168
|
+
def pin_checkpoint_from: (_Tracker tracker) -> (Pin | pin_checkpoint_refusal)
|
|
169
|
+
def advance: (Pin, Integer offset) -> (:moved | :unchanged | advance_refusal)
|
|
170
|
+
def checkpoint: (Pin, Integer assignment, Integer offset) -> (:advanced | :reassigned | :unchanged | checkpoint_refusal)
|
|
171
|
+
def checkpoint_from: (Pin, _Tracker tracker) -> (:advanced | :reassigned | :unchanged | checkpoint_refusal)
|
|
172
|
+
# :stale for a pin that is not held: one already released included.
|
|
173
|
+
def release: (Pin) -> (:released | release_refusal)
|
|
174
|
+
def pin_offset: (Pin) -> Integer?
|
|
175
|
+
def low_pin: () -> Integer?
|
|
176
|
+
def pins: () -> Integer
|
|
177
|
+
def propose: (Integer id) -> (Replacement | propose_refusal)
|
|
178
|
+
# The core's confirm_durable(replacement, durable), one method per variant
|
|
179
|
+
# of its `Durable` argument: Rewritten { bytes, live_records } and Superseded.
|
|
180
|
+
# On an attempt that is already durable: :already_durable for the payload
|
|
181
|
+
# that was recorded, :mismatch for any other (the other method, or
|
|
182
|
+
# different bytes or live_records).
|
|
183
|
+
def confirm_rewritten: (Replacement, Integer bytes, Integer live_records) -> (:recorded | :already_durable | confirm_rewritten_refusal)
|
|
184
|
+
def confirm_superseded: (Replacement) -> (:recorded | :already_durable | confirm_superseded_refusal)
|
|
185
|
+
def reclaim: (Replacement) -> (Reclaimed | reclaim_refusal)
|
|
186
|
+
def abort: (Replacement) -> (:aborted | abort_refusal)
|
|
187
|
+
|
|
188
|
+
# Private native hooks. `__open` is the one constructor `new`,
|
|
189
|
+
# `with_scope` and `resumed` reach (scope and issued as a pair, policy
|
|
190
|
+
# last); the `__check_*` hooks validate a Data value's fields at
|
|
191
|
+
# `initialize`, answering nil or raising.
|
|
192
|
+
private def self.__open: (Integer base_offset, nanoseconds now, [Integer, Integer] scope_and_issued, Policy policy) -> Journal
|
|
193
|
+
private def self.__check_policy: (Integer? max_bytes, Integer? max_records, nanoseconds? max_age,
|
|
194
|
+
Integer min_dead_per_mille) -> nil
|
|
195
|
+
private def self.__check_due: (roll_reason reason) -> nil
|
|
196
|
+
private def self.__check_rolled: (Integer sealed, Integer opened, Integer next_offset) -> nil
|
|
197
|
+
private def self.__check_reclaimed: (Integer segment, Integer revision, Integer bytes, Integer? replaced_by) -> nil
|
|
198
|
+
# Segment's id, revision, base_offset, records, then stored_records,
|
|
199
|
+
# live_records, bytes, opened_at.
|
|
200
|
+
private def self.__check_segment: ([Integer, Integer, Integer, Integer] head,
|
|
201
|
+
[Integer, Integer, Integer, nanoseconds] counts, segment_state state,
|
|
202
|
+
retention retention, Replacement? replacement) -> nil
|
|
203
|
+
|
|
204
|
+
private
|
|
205
|
+
|
|
206
|
+
# The Policy fields `policy` builds its value from, in order.
|
|
207
|
+
def __policy: () -> [Integer?, Integer?, nanoseconds?, Integer]
|
|
208
|
+
end
|
|
209
|
+
end
|
metadata
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
|
2
|
+
name: journal_machines
|
|
3
|
+
version: !ruby/object:Gem::Version
|
|
4
|
+
version: 0.7.1
|
|
5
|
+
platform: x86_64-linux
|
|
6
|
+
authors:
|
|
7
|
+
- Abdelkader Boudih
|
|
8
|
+
autorequire:
|
|
9
|
+
bindir: bin
|
|
10
|
+
cert_chain: []
|
|
11
|
+
date: 2026-11-16 00:00:00.000000000 Z
|
|
12
|
+
dependencies: []
|
|
13
|
+
description: 'Decides when to roll a log segment, which sealed segments are worth
|
|
14
|
+
compacting, and when a replaced segment file may be deleted without losing what
|
|
15
|
+
a reader or checkpoint pin still needs. Metadata only: not a log writer, byte compactor
|
|
16
|
+
or recovery runtime.'
|
|
17
|
+
email:
|
|
18
|
+
- oss@seuros.com
|
|
19
|
+
executables: []
|
|
20
|
+
extensions: []
|
|
21
|
+
extra_rdoc_files: []
|
|
22
|
+
files:
|
|
23
|
+
- CHANGELOG.md
|
|
24
|
+
- LICENSE.txt
|
|
25
|
+
- README.md
|
|
26
|
+
- ext/journal_machines_native/core/CHANGELOG.md
|
|
27
|
+
- ext/journal_machines_native/core/README.md
|
|
28
|
+
- ext/journal_machines_native/extconf.rb
|
|
29
|
+
- lib/journal_machines.rb
|
|
30
|
+
- lib/journal_machines/version.rb
|
|
31
|
+
- lib/journal_machines_native/journal_machines_native.so
|
|
32
|
+
- sig/journal_machines.rbs
|
|
33
|
+
homepage: https://github.com/seuros/journal_machines
|
|
34
|
+
licenses:
|
|
35
|
+
- MIT
|
|
36
|
+
metadata:
|
|
37
|
+
source_code_uri: https://github.com/seuros/journal_machines
|
|
38
|
+
rubygems_mfa_required: 'true'
|
|
39
|
+
cargo_crate_name: journal_machines_native
|
|
40
|
+
cargo_manifest_path: ext/journal_machines_native/ffi/Cargo.toml
|
|
41
|
+
post_install_message:
|
|
42
|
+
rdoc_options: []
|
|
43
|
+
require_paths:
|
|
44
|
+
- lib
|
|
45
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
|
46
|
+
requirements:
|
|
47
|
+
- - ">="
|
|
48
|
+
- !ruby/object:Gem::Version
|
|
49
|
+
version: '4.0'
|
|
50
|
+
- - "<"
|
|
51
|
+
- !ruby/object:Gem::Version
|
|
52
|
+
version: 4.1.dev
|
|
53
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
54
|
+
requirements:
|
|
55
|
+
- - ">="
|
|
56
|
+
- !ruby/object:Gem::Version
|
|
57
|
+
version: '0'
|
|
58
|
+
requirements: []
|
|
59
|
+
rubygems_version: 3.5.23
|
|
60
|
+
signing_key:
|
|
61
|
+
specification_version: 4
|
|
62
|
+
summary: 'Log segment metadata for Ruby: roll decisions, compaction candidates, pin-gated
|
|
63
|
+
reclaim'
|
|
64
|
+
test_files: []
|