@optimystic/db-core 1.2.0 → 1.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/src/collection/collection.d.ts +40 -2
- package/dist/src/collection/collection.d.ts.map +1 -1
- package/dist/src/collection/collection.js +59 -4
- package/dist/src/collection/collection.js.map +1 -1
- package/dist/src/transactor/block-floors.d.ts +13 -0
- package/dist/src/transactor/block-floors.d.ts.map +1 -1
- package/dist/src/transactor/block-floors.js +12 -2
- package/dist/src/transactor/block-floors.js.map +1 -1
- package/dist/src/transform/cache-source.d.ts +29 -4
- package/dist/src/transform/cache-source.d.ts.map +1 -1
- package/dist/src/transform/cache-source.js +48 -7
- package/dist/src/transform/cache-source.js.map +1 -1
- package/package.json +1 -1
- package/src/collection/collection.ts +2118 -2061
- package/src/transactor/block-floors.ts +126 -105
- package/src/transform/cache-source.ts +370 -327
|
@@ -1,327 +1,370 @@
|
|
|
1
|
-
import type { IBlock, BlockHeader, BlockId, BlockSource, BlockType, ReadPurpose, Transforms } from "../index.js";
|
|
2
|
-
import { applyOperation } from "./helpers.js";
|
|
3
|
-
import { LruMap } from "../utility/lru-map.js";
|
|
4
|
-
import { createLogger } from "../logger.js";
|
|
5
|
-
import type { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
|
|
6
|
-
|
|
7
|
-
const log = createLogger('cache');
|
|
8
|
-
|
|
9
|
-
const DefaultMaxSize = 128;
|
|
10
|
-
|
|
11
|
-
/** The revision a source reports for an id, or undefined if the source can't report one.
|
|
12
|
-
* Duck-typed exactly like {@link Tracker}'s getGeneration probe — CacheSource layers over
|
|
13
|
-
* arbitrary BlockSources (including test doubles) that need not implement it. */
|
|
14
|
-
function sourceReadRevision(source: unknown, id: BlockId): number | undefined {
|
|
15
|
-
const src = source as { getReadRevision?: (id: BlockId) => number | undefined };
|
|
16
|
-
return typeof src.getReadRevision === 'function' ? src.getReadRevision(id) : undefined;
|
|
17
|
-
}
|
|
18
|
-
|
|
19
|
-
/** What the source says about `block`, the object it just returned for `id`: the revision the
|
|
20
|
-
* content is, and whether it may be kept and served again without re-asking.
|
|
21
|
-
*
|
|
22
|
-
* Prefers the source's per-OBJECT answer (`describeServed`, which TransactorSource provides) over
|
|
23
|
-
* the by-id {@link sourceReadRevision}. This runs after an `await`, so with two reads of one id in
|
|
24
|
-
* flight a by-id record describes whichever answer the source processed last — not necessarily
|
|
25
|
-
* this one — and would stamp one answer's content with the other's revision and verdict. A source
|
|
26
|
-
* that offers neither allows keeping at revision 0, the behaviour before either probe existed. */
|
|
27
|
-
function sourceServed(source: unknown, id: BlockId, block: IBlock): { rev: number; mayRetain: boolean } {
|
|
28
|
-
const src = source as { describeServed?: (block: IBlock) => { rev: number; mayRetain: boolean } | undefined };
|
|
29
|
-
const described = typeof src.describeServed === 'function' ? src.describeServed(block) : undefined;
|
|
30
|
-
return described ?? { rev: sourceReadRevision(source, id) ?? 0, mayRetain: true };
|
|
31
|
-
}
|
|
32
|
-
|
|
33
|
-
export class CacheSource<T extends IBlock> implements BlockSource<T> {
|
|
34
|
-
protected cache: LruMap<BlockId, T>;
|
|
35
|
-
/** Per-id monotonic counter, bumped whenever the cached content for an id changes.
|
|
36
|
-
* Consumers (e.g. {@link Tracker}'s materialized-block memo) read it via
|
|
37
|
-
* {@link getGeneration} to detect that a cached "source + ops" result has gone stale.
|
|
38
|
-
* Over-bumping is safe (it only forces a re-materialize); under-bumping is a correctness
|
|
39
|
-
* bug, so every content-changing site bumps. A benign LRU evict + reload also bumps. */
|
|
40
|
-
// NOTE: generations is never pruned — it retains one small (id → number) entry per distinct id
|
|
41
|
-
// ever touched, even after LRU eviction from `cache`. Bounded by the number of distinct blocks a
|
|
42
|
-
// collection sees over its lifetime; if that ever grows large enough to matter, evict alongside
|
|
43
|
-
// the LRU (dropping a generation is safe — a reload re-bumps from 0/absent, forcing re-materialize).
|
|
44
|
-
private generations = new Map<BlockId, number>();
|
|
45
|
-
/** Per-id committed revision of the content currently cached for that id. Learned from the
|
|
46
|
-
* source on a miss-load, advanced by {@link transformCache} when a commit folds new content
|
|
47
|
-
* in, and dropped alongside the cached block on delete/clear. Re-emitted on every cache HIT
|
|
48
|
-
* so a hit records a read dependency at the right revision — the whole point of this map, since
|
|
49
|
-
* the underlying source is never consulted on a hit. */
|
|
50
|
-
// NOTE: an LRU-evicted id keeps its `revisions` entry (eviction drops `cache` but not this map).
|
|
51
|
-
// That lingering entry is LOAD-BEARING, not a leak: every path that serves or forgets content for
|
|
52
|
-
// an id writes this map in the same step (keep, handThrough, clear, transformCache), so the entry
|
|
53
|
-
// is always the revision of the content LAST SERVED for the id — which is exactly what a write
|
|
54
|
-
// staged over a since-evicted read needs to declare as its base (a rev-only pin, see
|
|
55
|
-
// `PinnedBase.block` in base-pins.ts). Only `peek` pairs a revision with content, and it answers
|
|
56
|
-
// nothing for an evicted id, so the revision never pairs with a block it does not describe.
|
|
57
|
-
private revisions = new Map<BlockId, number>();
|
|
58
|
-
/** The most recent answer per id that this cache returned to a reader but did not keep — a
|
|
59
|
-
* below-floor answer, content older than a log entry the collection already walked says the
|
|
60
|
-
* block is (see {@link sourceServed}), or an answer overtaken while in flight over an id nothing
|
|
61
|
-
* is held for (see {@link admit}). NEVER served to a read: {@link tryGet} re-asks the source
|
|
62
|
-
* every time such an id is read, which is the whole point. It exists for the base probes alone
|
|
63
|
-
* ({@link peek} / {@link getCachedRevision}): a write staged over this content must declare the
|
|
64
|
-
* base it was really built on, at the revision it was really served at, so that the storage-side
|
|
65
|
-
* guard which refuses a transform whose declared base is not the one the member holds can fire
|
|
66
|
-
* instead of abstaining and applying edits computed against the old content over newer content.
|
|
67
|
-
* An id is never in both this map and `cache`/`revisions`. It leaves on its next keepable answer,
|
|
68
|
-
* on {@link clear}, and on any {@link transformCache} that touches it, so the map is bounded by
|
|
69
|
-
* the source's unmet floors plus the ids caught mid-flight by a clear or a fold. */
|
|
70
|
-
private unkept = new Map<BlockId, { block: T; rev: number }>();
|
|
71
|
-
|
|
72
|
-
constructor(
|
|
73
|
-
protected readonly source: BlockSource<T>,
|
|
74
|
-
maxSize = DefaultMaxSize,
|
|
75
|
-
/** Shared per-transaction read-dependency accumulator (same instance the collection's
|
|
76
|
-
* TransactorSource holds). Optional: log-walk caches that never form a transaction omit it. */
|
|
77
|
-
private readonly collector?: ReadDependencyCollector,
|
|
78
|
-
/** Pre-warm entries
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
*
|
|
82
|
-
*
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
*
|
|
108
|
-
*
|
|
109
|
-
*
|
|
110
|
-
*
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
//
|
|
117
|
-
//
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
//
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
*
|
|
143
|
-
*
|
|
144
|
-
*
|
|
145
|
-
*
|
|
146
|
-
*
|
|
147
|
-
*
|
|
148
|
-
*
|
|
149
|
-
*
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
*
|
|
169
|
-
*
|
|
170
|
-
*
|
|
171
|
-
*
|
|
172
|
-
*
|
|
173
|
-
*
|
|
174
|
-
*
|
|
175
|
-
*
|
|
176
|
-
*
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
*
|
|
200
|
-
*
|
|
201
|
-
*
|
|
202
|
-
*
|
|
203
|
-
*
|
|
204
|
-
*
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
*
|
|
216
|
-
*
|
|
217
|
-
*
|
|
218
|
-
*
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
*
|
|
246
|
-
*
|
|
247
|
-
*
|
|
248
|
-
*
|
|
249
|
-
|
|
250
|
-
this.
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
}
|
|
1
|
+
import type { IBlock, BlockHeader, BlockId, BlockSource, BlockType, ReadPurpose, Transforms } from "../index.js";
|
|
2
|
+
import { applyOperation } from "./helpers.js";
|
|
3
|
+
import { LruMap } from "../utility/lru-map.js";
|
|
4
|
+
import { createLogger } from "../logger.js";
|
|
5
|
+
import type { ReadDependencyCollector } from "../transaction/read-dependency-collector.js";
|
|
6
|
+
|
|
7
|
+
const log = createLogger('cache');
|
|
8
|
+
|
|
9
|
+
const DefaultMaxSize = 128;
|
|
10
|
+
|
|
11
|
+
/** The revision a source reports for an id, or undefined if the source can't report one.
|
|
12
|
+
* Duck-typed exactly like {@link Tracker}'s getGeneration probe — CacheSource layers over
|
|
13
|
+
* arbitrary BlockSources (including test doubles) that need not implement it. */
|
|
14
|
+
function sourceReadRevision(source: unknown, id: BlockId): number | undefined {
|
|
15
|
+
const src = source as { getReadRevision?: (id: BlockId) => number | undefined };
|
|
16
|
+
return typeof src.getReadRevision === 'function' ? src.getReadRevision(id) : undefined;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** What the source says about `block`, the object it just returned for `id`: the revision the
|
|
20
|
+
* content is, and whether it may be kept and served again without re-asking.
|
|
21
|
+
*
|
|
22
|
+
* Prefers the source's per-OBJECT answer (`describeServed`, which TransactorSource provides) over
|
|
23
|
+
* the by-id {@link sourceReadRevision}. This runs after an `await`, so with two reads of one id in
|
|
24
|
+
* flight a by-id record describes whichever answer the source processed last — not necessarily
|
|
25
|
+
* this one — and would stamp one answer's content with the other's revision and verdict. A source
|
|
26
|
+
* that offers neither allows keeping at revision 0, the behaviour before either probe existed. */
|
|
27
|
+
function sourceServed(source: unknown, id: BlockId, block: IBlock): { rev: number; mayRetain: boolean } {
|
|
28
|
+
const src = source as { describeServed?: (block: IBlock) => { rev: number; mayRetain: boolean } | undefined };
|
|
29
|
+
const described = typeof src.describeServed === 'function' ? src.describeServed(block) : undefined;
|
|
30
|
+
return described ?? { rev: sourceReadRevision(source, id) ?? 0, mayRetain: true };
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export class CacheSource<T extends IBlock> implements BlockSource<T> {
|
|
34
|
+
protected cache: LruMap<BlockId, T>;
|
|
35
|
+
/** Per-id monotonic counter, bumped whenever the cached content for an id changes.
|
|
36
|
+
* Consumers (e.g. {@link Tracker}'s materialized-block memo) read it via
|
|
37
|
+
* {@link getGeneration} to detect that a cached "source + ops" result has gone stale.
|
|
38
|
+
* Over-bumping is safe (it only forces a re-materialize); under-bumping is a correctness
|
|
39
|
+
* bug, so every content-changing site bumps. A benign LRU evict + reload also bumps. */
|
|
40
|
+
// NOTE: generations is never pruned — it retains one small (id → number) entry per distinct id
|
|
41
|
+
// ever touched, even after LRU eviction from `cache`. Bounded by the number of distinct blocks a
|
|
42
|
+
// collection sees over its lifetime; if that ever grows large enough to matter, evict alongside
|
|
43
|
+
// the LRU (dropping a generation is safe — a reload re-bumps from 0/absent, forcing re-materialize).
|
|
44
|
+
private generations = new Map<BlockId, number>();
|
|
45
|
+
/** Per-id committed revision of the content currently cached for that id. Learned from the
|
|
46
|
+
* source on a miss-load, advanced by {@link transformCache} when a commit folds new content
|
|
47
|
+
* in, and dropped alongside the cached block on delete/clear. Re-emitted on every cache HIT
|
|
48
|
+
* so a hit records a read dependency at the right revision — the whole point of this map, since
|
|
49
|
+
* the underlying source is never consulted on a hit. */
|
|
50
|
+
// NOTE: an LRU-evicted id keeps its `revisions` entry (eviction drops `cache` but not this map).
|
|
51
|
+
// That lingering entry is LOAD-BEARING, not a leak: every path that serves or forgets content for
|
|
52
|
+
// an id writes this map in the same step (keep, handThrough, clear, transformCache), so the entry
|
|
53
|
+
// is always the revision of the content LAST SERVED for the id — which is exactly what a write
|
|
54
|
+
// staged over a since-evicted read needs to declare as its base (a rev-only pin, see
|
|
55
|
+
// `PinnedBase.block` in base-pins.ts). Only `peek` pairs a revision with content, and it answers
|
|
56
|
+
// nothing for an evicted id, so the revision never pairs with a block it does not describe.
|
|
57
|
+
private revisions = new Map<BlockId, number>();
|
|
58
|
+
/** The most recent answer per id that this cache returned to a reader but did not keep — a
|
|
59
|
+
* below-floor answer, content older than a log entry the collection already walked says the
|
|
60
|
+
* block is (see {@link sourceServed}), or an answer overtaken while in flight over an id nothing
|
|
61
|
+
* is held for (see {@link admit}). NEVER served to a read: {@link tryGet} re-asks the source
|
|
62
|
+
* every time such an id is read, which is the whole point. It exists for the base probes alone
|
|
63
|
+
* ({@link peek} / {@link getCachedRevision}): a write staged over this content must declare the
|
|
64
|
+
* base it was really built on, at the revision it was really served at, so that the storage-side
|
|
65
|
+
* guard which refuses a transform whose declared base is not the one the member holds can fire
|
|
66
|
+
* instead of abstaining and applying edits computed against the old content over newer content.
|
|
67
|
+
* An id is never in both this map and `cache`/`revisions`. It leaves on its next keepable answer,
|
|
68
|
+
* on {@link clear}, and on any {@link transformCache} that touches it, so the map is bounded by
|
|
69
|
+
* the source's unmet floors plus the ids caught mid-flight by a clear or a fold. */
|
|
70
|
+
private unkept = new Map<BlockId, { block: T; rev: number }>();
|
|
71
|
+
|
|
72
|
+
constructor(
|
|
73
|
+
protected readonly source: BlockSource<T>,
|
|
74
|
+
maxSize = DefaultMaxSize,
|
|
75
|
+
/** Shared per-transaction read-dependency accumulator (same instance the collection's
|
|
76
|
+
* TransactorSource holds). Optional: log-walk caches that never form a transaction omit it. */
|
|
77
|
+
private readonly collector?: ReadDependencyCollector,
|
|
78
|
+
/** Pre-warm entries: the output of another cache's {@link snapshotEntries} for a pinned read
|
|
79
|
+
* view, or the blocks a refresh already fetched for its own log walk
|
|
80
|
+
* (`Collection.readLogEnds`). Blocks are adopted BY REFERENCE — a seeder that keeps its own
|
|
81
|
+
* handle on one must not mutate it, which is why {@link offerServed}, whose caller does keep
|
|
82
|
+
* one, clones instead. Per-id revisions ride along so a seeded HIT still records at the
|
|
83
|
+
* revision the block was committed at. Seeding does not bump generations (a fresh
|
|
84
|
+
* cache has no consumers with stale memos). */
|
|
85
|
+
seed?: ReadonlyArray<[BlockId, T, number]>,
|
|
86
|
+
) {
|
|
87
|
+
this.cache = new LruMap(maxSize);
|
|
88
|
+
if (seed) {
|
|
89
|
+
for (const [id, block, revision] of seed) {
|
|
90
|
+
this.cache.set(id, block);
|
|
91
|
+
this.revisions.set(id, revision);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
private bump(id: BlockId) {
|
|
97
|
+
this.generations.set(id, (this.generations.get(id) ?? 0) + 1);
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/** The current generation for an id — advances every time this cache's content for
|
|
101
|
+
* the id changes (miss-load, clear, or transformCache). Stable across pure cache hits. */
|
|
102
|
+
getGeneration(id: BlockId): number {
|
|
103
|
+
return this.generations.get(id) ?? 0;
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/** INVARIANT: what a read returns for an id is what this cache then describes for it — the
|
|
107
|
+
* block {@link peek} answers and the revision {@link getCachedRevision} answers, immediately
|
|
108
|
+
* after, are the content the reader holds, on every path (hit, kept, handed through, evicted
|
|
109
|
+
* since). A write staged over the returned content pins that revision as its base, so a read
|
|
110
|
+
* that returned one thing while the cache described another would put a wrong base on the
|
|
111
|
+
* commit — the one direction the storage-side guard cannot catch. {@link admit} is where the
|
|
112
|
+
* two are decided together. */
|
|
113
|
+
async tryGet(id: BlockId, purpose: ReadPurpose = 'value'): Promise<T | undefined> {
|
|
114
|
+
const hit = this.cache.get(id);
|
|
115
|
+
if (hit) {
|
|
116
|
+
// Cache hit: the source is never consulted, so re-emit the revision we learned when this
|
|
117
|
+
// id was first loaded/folded. Without this a block served from cache records NO read
|
|
118
|
+
// dependency (the original bug), so its stale-read check could never fire. Carry the
|
|
119
|
+
// caller's purpose so a navigation-only cache hit stays droppable from the conflict set.
|
|
120
|
+
const rev = this.revisions.get(id);
|
|
121
|
+
if (rev !== undefined) this.collector?.record(id, rev, purpose);
|
|
122
|
+
log('hit id=%s', id);
|
|
123
|
+
return structuredClone(hit);
|
|
124
|
+
}
|
|
125
|
+
const generationAtMiss = this.getGeneration(id);
|
|
126
|
+
const answer = await this.source.tryGet(id, purpose);
|
|
127
|
+
if (!answer) {
|
|
128
|
+
// Absent block: record nothing (matches TransactorSource, which skips missing blocks).
|
|
129
|
+
log('miss:absent id=%s', id);
|
|
130
|
+
return undefined;
|
|
131
|
+
}
|
|
132
|
+
const { rev, mayRetain } = sourceServed(this.source, id, answer);
|
|
133
|
+
const served = this.admit(id, answer, rev, mayRetain, generationAtMiss);
|
|
134
|
+
// Record the dependency at the revision RETURNED. On a miss the underlying TransactorSource
|
|
135
|
+
// already recorded the answer's own id@rev/purpose into the shared collector; max-wins
|
|
136
|
+
// (revision) + value-wins (purpose) collapse the two to one entry, at the higher revision.
|
|
137
|
+
this.collector?.record(id, served.rev, purpose);
|
|
138
|
+
return structuredClone(served.block);
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/** Decide, for an answer the source just gave for `id`, what the reader gets and what this cache
|
|
142
|
+
* describes for the id from now on — one decision, so the two cannot come apart.
|
|
143
|
+
*
|
|
144
|
+
* A keepable answer that is {@link stillWanted} is kept and returned. Otherwise the answer is
|
|
145
|
+
* either below its floor or was overtaken while in flight, and of two answers to one id the
|
|
146
|
+
* higher revision is the truer — so if content is HELD for the id (a concurrent read answered
|
|
147
|
+
* well, a folded commit, or content that met a floor this answer does not), the held content is
|
|
148
|
+
* what the reader gets, exactly as a hit a moment later would get it; the answer leaves no trace.
|
|
149
|
+
* Held content is never older than a below-floor answer: raising a floor forgets the id in the
|
|
150
|
+
* same step, so anything held for it since met the floor. With nothing held, the answer is
|
|
151
|
+
* handed through (see {@link handThrough}): returned, described, not kept. */
|
|
152
|
+
private admit(id: BlockId, answer: T, rev: number, mayRetain: boolean, generationAtMiss: number): { block: T; rev: number } {
|
|
153
|
+
if (mayRetain && this.stillWanted(id, rev, generationAtMiss)) {
|
|
154
|
+
this.keep(id, answer, rev, 'miss:loaded');
|
|
155
|
+
return { block: answer, rev };
|
|
156
|
+
}
|
|
157
|
+
const held = this.cache.get(id);
|
|
158
|
+
const heldRev = held === undefined ? undefined : this.revisions.get(id);
|
|
159
|
+
if (held !== undefined && heldRev !== undefined) {
|
|
160
|
+
log('miss:superseded id=%s rev=%d heldRev=%d unkeepable=%s', id, rev, heldRev, !mayRetain);
|
|
161
|
+
return { block: held, rev: heldRev };
|
|
162
|
+
}
|
|
163
|
+
this.handThrough(id, answer, rev);
|
|
164
|
+
return { block: answer, rev };
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/** Whether an answer at `rev`, asked for when this id's generation was `generationAtMiss`, is
|
|
168
|
+
* still one to keep now that it has arrived.
|
|
169
|
+
*
|
|
170
|
+
* A miss is decided before the `await` and acted on after it. If the generation has not moved,
|
|
171
|
+
* nothing happened to the id meanwhile and the answer is kept. If it has — a second read of the
|
|
172
|
+
* id landed first, a refresh cleared it, a commit folded in ({@link transformCache}) — this answer
|
|
173
|
+
* was asked for in a world that has since changed, and keeping it blindly is how old content gets
|
|
174
|
+
* remembered for good: nothing clears a block but a log entry naming it, and that entry may be
|
|
175
|
+
* the very thing that moved the generation. So it is then kept only to REPLACE strictly older
|
|
176
|
+
* content (every answer to one source is for one view, so of two the higher revision is the
|
|
177
|
+
* truer, whichever arrives last); what an overtaken answer's reader gets is {@link admit}'s call.
|
|
178
|
+
* Only a CACHED id is compared: `revisions` outlives an LRU-evicted block (see its NOTE). */
|
|
179
|
+
private stillWanted(id: BlockId, rev: number, generationAtMiss: number): boolean {
|
|
180
|
+
if (this.getGeneration(id) === generationAtMiss) {
|
|
181
|
+
return true;
|
|
182
|
+
}
|
|
183
|
+
const held = this.cache.has(id) ? this.revisions.get(id) : undefined;
|
|
184
|
+
const replacesOlder = held !== undefined && held < rev;
|
|
185
|
+
if (!replacesOlder) {
|
|
186
|
+
log('miss:overtaken id=%s rev=%d heldRev=%s', id, rev, held ?? 'none');
|
|
187
|
+
}
|
|
188
|
+
return replacesOlder;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/** Adopt an answer some other read already obtained for `id` — the collection header and log
|
|
192
|
+
* tail block that `Collection.readLogEnds` fetches AROUND this cache — so the next read of the
|
|
193
|
+
* id is a hit rather than a second fetch of a block this handle just received.
|
|
194
|
+
*
|
|
195
|
+
* Kept only when nothing strictly newer is held ({@link heldRevision}), on the same ground
|
|
196
|
+
* {@link admit} stands on: of two answers to one source the higher revision is the truer. The
|
|
197
|
+
* block is cloned on the way in — this cache stores the reference, and the caller's array is
|
|
198
|
+
* handed to other caches as a seed as well — and goes through {@link keep}, so the generation
|
|
199
|
+
* bump, the {@link unkept} eviction and the {@link revisions} entry all happen exactly as they
|
|
200
|
+
* do for an answer this cache fetched itself.
|
|
201
|
+
*
|
|
202
|
+
* The CALLER owns the floor and pin checks. The offered block did not come through this cache's
|
|
203
|
+
* source, so `sourceServed` can say nothing about it: there is no `describeServed` record for a
|
|
204
|
+
* block the source never returned, and the by-id fallback would describe some other read. */
|
|
205
|
+
offerServed(id: BlockId, block: T, rev: number): void {
|
|
206
|
+
const heldRev = this.heldRevision(id);
|
|
207
|
+
if (heldRev !== undefined && heldRev > rev) {
|
|
208
|
+
log('offer:superseded id=%s rev=%d heldRev=%d', id, rev, heldRev);
|
|
209
|
+
return;
|
|
210
|
+
}
|
|
211
|
+
this.keep(id, structuredClone(block), rev, 'offer:kept');
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
/** The revision of the content this cache HOLDS for `id` right now — cached, or handed through
|
|
215
|
+
* unkept — and `undefined` when it holds none. Distinct from {@link getCachedRevision}, which
|
|
216
|
+
* also answers for an LRU-evicted id: that revision describes content this cache no longer has,
|
|
217
|
+
* so it is the right answer for a base probe and the wrong one for "is there anything here to
|
|
218
|
+
* weigh an offer against?". */
|
|
219
|
+
// NOTE: the consequence is that an offer over an LRU-evicted id is accepted even when it is
|
|
220
|
+
// OLDER than the revision this cache last served for the id — a lagging replica answering the
|
|
221
|
+
// unpinned refresh read below what this handle has already seen, with no walked entry to floor
|
|
222
|
+
// the block. That is the same answer a pinned re-read of the evicted id would have been kept at,
|
|
223
|
+
// so the offer path is no worse than the read path it replaces; if lagging-replica staleness on
|
|
224
|
+
// the header or log tail ever shows up, refuse an offer below `getCachedRevision` here (a block
|
|
225
|
+
// never goes back a revision, so refusing is always right) rather than adding a floor for it.
|
|
226
|
+
private heldRevision(id: BlockId): number | undefined {
|
|
227
|
+
return this.cache.has(id) ? this.revisions.get(id) : this.unkept.get(id)?.rev;
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
/** A keepable answer: cached, and served to every later read of `id` until something clears it.
|
|
231
|
+
* `reason` names how the content got here, so a log read to count source loads is not misled by
|
|
232
|
+
* an offer this cache never fetched. */
|
|
233
|
+
private keep(id: BlockId, block: T, rev: number, reason: 'miss:loaded' | 'offer:kept') {
|
|
234
|
+
this.cache.set(id, block);
|
|
235
|
+
this.revisions.set(id, rev);
|
|
236
|
+
this.unkept.delete(id);
|
|
237
|
+
this.bump(id);
|
|
238
|
+
log('%s id=%s cacheSize=%d', reason, id, this.cache.size);
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
/** An answer this cache will not keep, over an id it holds nothing for: returned to this one
|
|
242
|
+
* reader and described to the base probes (see {@link unkept}), but the next read of `id` asks
|
|
243
|
+
* the source again. Only {@link admit} calls this, after establishing that nothing is held —
|
|
244
|
+
* a cached id is never also in {@link unkept}.
|
|
245
|
+
*
|
|
246
|
+
* Bumped like a load: the answer changes what this cache can say about the id, and the bump is
|
|
247
|
+
* what sends a base pin or a materialized memo built on the previous answer back to be
|
|
248
|
+
* re-judged. */
|
|
249
|
+
private handThrough(id: BlockId, block: T, rev: number) {
|
|
250
|
+
this.revisions.delete(id);
|
|
251
|
+
this.unkept.set(id, { block, rev });
|
|
252
|
+
this.bump(id);
|
|
253
|
+
log('miss:unkept id=%s rev=%d', id, rev);
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
/** The base this cache can describe for `id`, without consulting the source: the cached block,
|
|
257
|
+
* or the content last handed through unkept (see {@link unkept}) — either way the content the
|
|
258
|
+
* most recent {@link tryGet} of the id returned, unless it has been evicted since. Cloned
|
|
259
|
+
* (callers apply ops to it) and recency-neutral ({@link LruMap.peek}) — an observation pass must
|
|
260
|
+
* neither pay a network read nor reshape eviction order. Records no read dependency: the caller
|
|
261
|
+
* that peeks already read the block through {@link tryGet} (that is how this cache learned it),
|
|
262
|
+
* so the dependency exists; a digest pass merely re-describes it. */
|
|
263
|
+
peek(id: BlockId): T | undefined {
|
|
264
|
+
const block = this.cache.peek(id) ?? this.unkept.get(id)?.block;
|
|
265
|
+
return block === undefined ? undefined : structuredClone(block);
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
/** Whether a later {@link tryGet} of `id` is answered from memory with the content this cache
|
|
269
|
+
* holds now. `false` for content handed through unkept, which {@link peek} still describes — so
|
|
270
|
+
* a consumer that would FREEZE a read result ({@link Tracker}'s materialized memo) asks this, not
|
|
271
|
+
* {@link peek}. Recency-neutral. */
|
|
272
|
+
retains(id: BlockId): boolean {
|
|
273
|
+
return this.cache.has(id);
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
/** The committed revision of the content this cache last served for `id` — the source-reported
|
|
277
|
+
* materialized revision learned on miss-load (see {@link revisions}) or handed through
|
|
278
|
+
* ({@link unkept}), NOT the block's own `state.latest.rev`. Answers for an LRU-evicted id too
|
|
279
|
+
* (see the NOTE on {@link revisions}): that is the revision a write staged over the evicted
|
|
280
|
+
* read was computed against, and what a rev-only base pin carries. {@link peek} returns
|
|
281
|
+
* `undefined` for the evicted id, so the revision never pairs with content it does not describe.
|
|
282
|
+
* `undefined` once the id has been cleared or folded away, or if it was never served. */
|
|
283
|
+
getCachedRevision(id: BlockId): number | undefined {
|
|
284
|
+
return this.revisions.get(id) ?? this.unkept.get(id)?.rev;
|
|
285
|
+
}
|
|
286
|
+
|
|
287
|
+
/** Upgrade an already-captured read of `id` to a `value` read in the shared collector,
|
|
288
|
+
* retaining it in the conflict set. The B-tree point-lookup descent calls this (through the
|
|
289
|
+
* Tracker, which forwards) to pin the terminal leaf after recording the interior nodes as
|
|
290
|
+
* `navigation`. No-op when no collector is wired (log-walk caches) or the id was never
|
|
291
|
+
* recorded. Duck-typed by the Tracker; keep the name in sync with Tracker.markReadValue. */
|
|
292
|
+
markReadValue(id: BlockId): void {
|
|
293
|
+
this.collector?.markValue(id);
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
generateId(): BlockId {
|
|
297
|
+
return this.source.generateId();
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
createBlockHeader(type: BlockType, newId?: BlockId): BlockHeader {
|
|
301
|
+
return this.source.createBlockHeader(type, newId);
|
|
302
|
+
}
|
|
303
|
+
|
|
304
|
+
clear(blockIds: BlockId[] | undefined = undefined) {
|
|
305
|
+
if (blockIds) {
|
|
306
|
+
for (const id of blockIds) {
|
|
307
|
+
this.cache.delete(id);
|
|
308
|
+
this.revisions.delete(id);
|
|
309
|
+
this.unkept.delete(id);
|
|
310
|
+
this.bump(id);
|
|
311
|
+
}
|
|
312
|
+
} else {
|
|
313
|
+
for (const [id] of this.cache) {
|
|
314
|
+
this.bump(id);
|
|
315
|
+
}
|
|
316
|
+
for (const id of this.unkept.keys()) {
|
|
317
|
+
this.bump(id);
|
|
318
|
+
}
|
|
319
|
+
this.cache.clear();
|
|
320
|
+
this.revisions.clear();
|
|
321
|
+
this.unkept.clear();
|
|
322
|
+
}
|
|
323
|
+
}
|
|
324
|
+
|
|
325
|
+
/** A cloned copy of the current cache contents with each id's committed revision, in LRU
|
|
326
|
+
* order (oldest first, so replaying into another LruMap preserves eviction order). For
|
|
327
|
+
* building a pinned read view ONLY (see {@link Collection.createReadTracker}): pass the
|
|
328
|
+
* result as the `seed` of a fresh, PRIVATE CacheSource. Blocks are cloned on the way out,
|
|
329
|
+
* so the seeded cache shares no mutable state with this one. */
|
|
330
|
+
snapshotEntries(): Array<[BlockId, T, number]> {
|
|
331
|
+
const entries: Array<[BlockId, T, number]> = [];
|
|
332
|
+
for (const [id, block] of this.cache) {
|
|
333
|
+
entries.push([id, structuredClone(block), this.revisions.get(id) ?? 0]);
|
|
334
|
+
}
|
|
335
|
+
return entries;
|
|
336
|
+
}
|
|
337
|
+
|
|
338
|
+
/** Mutates the cache without affecting the source. `revision` is the committed revision this
|
|
339
|
+
* transform lands at; the stored per-id revision advances to it so a later read records a
|
|
340
|
+
* dependency at the NEW revision (recording the old one would spuriously fail validation). */
|
|
341
|
+
transformCache(transform: Transforms, revision: number) {
|
|
342
|
+
for (const blockId of transform.deletes ?? []) {
|
|
343
|
+
this.cache.delete(blockId);
|
|
344
|
+
this.revisions.delete(blockId);
|
|
345
|
+
this.unkept.delete(blockId);
|
|
346
|
+
this.bump(blockId);
|
|
347
|
+
}
|
|
348
|
+
for (const [, block] of Object.entries(transform.inserts ?? {})) {
|
|
349
|
+
this.cache.set(block.header.id, structuredClone(block) as T);
|
|
350
|
+
this.revisions.set(block.header.id, revision);
|
|
351
|
+
this.unkept.delete(block.header.id);
|
|
352
|
+
this.bump(block.header.id);
|
|
353
|
+
}
|
|
354
|
+
for (const [blockId, operations] of Object.entries(transform.updates ?? {})) {
|
|
355
|
+
const block = this.cache.get(blockId);
|
|
356
|
+
if (block) {
|
|
357
|
+
for (const op of operations) {
|
|
358
|
+
applyOperation(block, op);
|
|
359
|
+
this.bump(blockId);
|
|
360
|
+
}
|
|
361
|
+
this.revisions.set(blockId, revision);
|
|
362
|
+
} else if (this.unkept.delete(blockId)) {
|
|
363
|
+
// The commit superseded the unkept base, and the ops are NOT folded into it: it was
|
|
364
|
+
// never trusted as this id's content, so the result would not be either. The id stays
|
|
365
|
+
// out of memory and the next read asks the source, which now holds `revision`.
|
|
366
|
+
this.bump(blockId);
|
|
367
|
+
}
|
|
368
|
+
}
|
|
369
|
+
}
|
|
370
|
+
}
|