@cloudbitmaps/roaring 0.17.0 → 0.18.1
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/PRIVACY.md +12 -2
- package/README.md +11 -5
- package/dist/bin/export-segments.js +528 -0
- package/dist/bin/export-segments.js.map +3 -3
- package/dist/index.d.ts +308 -1
- package/dist/index.js +531 -0
- package/dist/index.js.map +3 -3
- package/package.json +2 -2
package/dist/index.d.ts
CHANGED
|
@@ -25,6 +25,7 @@
|
|
|
25
25
|
*/
|
|
26
26
|
import type { BudgetOption, GenerationEntry, GenerationMetadata, LoadGuard, LoadInput, LoadOptions, LoadRefusal, LoadResult, ReapRegistryTombstonesOptions, ReapRegistryTombstonesResult, RollbackResult, Clock, StorageChunkSource, ConsistencyReport, CostReport, DropResult, EstimateInput, ExportManifest, ExportOptions, ExportSink, IAuditSink, IStorageDriver, IKeystore, IMetricsSink, StorageBackend, PricingProfile, RetentionPolicy, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, SetRetentionResult, PinnedAt, IdRange, SegmentRef, Workload } from '@cloudbitmaps/core';
|
|
27
27
|
import type { SegmentInfo } from '@cloudbitmaps/core';
|
|
28
|
+
import type { CombineExpr, CombineManyFeedRecord, CombineManyOperandStats, CombineManyOutputStats, CombineManyStats } from '@cloudbitmaps/core';
|
|
28
29
|
import { deserializePortable } from './roaring-codec.js';
|
|
29
30
|
/**
|
|
30
31
|
* Wiring for a {@link CloudRoaring} store. **Only `storage` is required** — the minimal call is
|
|
@@ -298,6 +299,142 @@ export interface EraseSubjectResult {
|
|
|
298
299
|
* in prose means the compiler enforces it, and a caller's exhaustive `switch` has no dead branch.
|
|
299
300
|
*/
|
|
300
301
|
export type MaterializeRefusal = Exclude<LoadRefusal, 'superseded'>;
|
|
302
|
+
/**
|
|
303
|
+
* An expression over the operands of a {@link CloudRoaring.materializeMany} call: a string names an operand; a node holds
|
|
304
|
+
* exactly one of `and`, `or` or `andNot` over a non-empty list of expressions. `andNot` subtracts every entry after the
|
|
305
|
+
* first from the first, so it takes at least two. Plain JSON, so it can be logged and sent between tasks.
|
|
306
|
+
*/
|
|
307
|
+
export type Expr = CombineExpr;
|
|
308
|
+
/** What the call did to one operand: see {@link MaterializeManyStats.operands}. */
|
|
309
|
+
export type MaterializeManyOperandStats = CombineManyOperandStats;
|
|
310
|
+
/** What the call did to one output: see {@link MaterializeManyStats.outputs}. */
|
|
311
|
+
export type MaterializeManyOutputStats = CombineManyOutputStats;
|
|
312
|
+
/**
|
|
313
|
+
* What a {@link CloudRoaring.materializeMany} call did: the groups it ran, its requests by class, the chunk-read budget it
|
|
314
|
+
* used, the most it held resident, and, for each operand, the generation it was pinned at, began at and ended at.
|
|
315
|
+
*/
|
|
316
|
+
export type MaterializeManyStats = CombineManyStats;
|
|
317
|
+
/** One output of a {@link CloudRoaring.materializeMany} call. */
|
|
318
|
+
export interface MaterializeManyOutput {
|
|
319
|
+
/** The segment this output becomes a new generation of. Not an operand of the call, and named by no other output. */
|
|
320
|
+
readonly dest: Segment;
|
|
321
|
+
/** What to compute. */
|
|
322
|
+
readonly expr: Expr;
|
|
323
|
+
/** Subtracted from the result, as the entries of an `andNot` after the first are. Pinned operands it names are re-checked before the publish. */
|
|
324
|
+
readonly exclude?: Expr[];
|
|
325
|
+
/** As on {@link MaterializeOptions}. */
|
|
326
|
+
readonly guard?: LoadGuard;
|
|
327
|
+
/** As on {@link MaterializeOptions}. */
|
|
328
|
+
readonly allowEmpty?: boolean;
|
|
329
|
+
/** As on {@link MaterializeOptions}. */
|
|
330
|
+
readonly metadata?: GenerationMetadata;
|
|
331
|
+
/** As on {@link MaterializeOptions}. */
|
|
332
|
+
readonly audit?: IAuditSink;
|
|
333
|
+
/** Generations to keep below the new one, as on {@link MaterializeOptions}; overrides the call's `keep`. */
|
|
334
|
+
readonly keep?: number;
|
|
335
|
+
}
|
|
336
|
+
/**
|
|
337
|
+
* One record of the feed of {@link CloudRoaring.materializeMany}: the ids some of the fed operands hold at one chunk key.
|
|
338
|
+
* `key` is `id >>> 16`, an integer from 0 to 65,535, never below the previous record's; a key may arrive as several
|
|
339
|
+
* consecutive records, each carrying some of the operands, and one record per key is the usual shape. `operands` maps a
|
|
340
|
+
* declared fed name to its ids at the key: a real `Uint32Array` (not an `Int32Array`, `Buffer`, array or look-alike),
|
|
341
|
+
* strictly ascending, every id inside the key. A name is given at most once per key, and an empty array is the same as
|
|
342
|
+
* leaving the name out. The record is copied as it arrives, so the caller may drop or reuse its arrays once it has yielded it.
|
|
343
|
+
*/
|
|
344
|
+
export type MaterializeManyFeedRecord = CombineManyFeedRecord;
|
|
345
|
+
/**
|
|
346
|
+
* Operands that arrive as records in chunk-key order instead of being stored, for {@link MaterializeManyOptions.feed}.
|
|
347
|
+
* Outputs name a fed operand as they name a stored one.
|
|
348
|
+
*/
|
|
349
|
+
export interface MaterializeManyFeed {
|
|
350
|
+
/** The fed operand names, declared up front. A name is either stored or fed, never both. */
|
|
351
|
+
readonly names: string[];
|
|
352
|
+
/** The records, read once, in key order. */
|
|
353
|
+
readonly records: AsyncIterable<MaterializeManyFeedRecord>;
|
|
354
|
+
/**
|
|
355
|
+
* How many ids each fed operand holds over the whole feed, **required**: an object keyed by exactly `names`, or a
|
|
356
|
+
* function returning one (or a promise of one), called once after the last record and before any fed output is
|
|
357
|
+
* published. A feed whose count of ids for any operand differs (one that ended early, or skipped a key) refuses every
|
|
358
|
+
* fed output; so does a count that is missing, extra, thrown or rejected.
|
|
359
|
+
*/
|
|
360
|
+
readonly counts: (() => Record<string, number> | Promise<Record<string, number>>) | Record<string, number>;
|
|
361
|
+
}
|
|
362
|
+
/** The options of {@link CloudRoaring.materializeMany}. */
|
|
363
|
+
export interface MaterializeManyOptions extends IdRange {
|
|
364
|
+
/**
|
|
365
|
+
* The operands the expressions name: stored segments, and operands held in memory from {@link CloudRoaring.memory}. A held
|
|
366
|
+
* operand is accepted here and nowhere else.
|
|
367
|
+
*/
|
|
368
|
+
readonly operands: Record<string, Segment | MemoryOperand>;
|
|
369
|
+
/** The outputs, in the order their results come back. */
|
|
370
|
+
readonly outputs: ReadonlyArray<MaterializeManyOutput>;
|
|
371
|
+
/**
|
|
372
|
+
* Generations to keep below each new one: a non-negative integer, **required**, since a materialisation otherwise keeps
|
|
373
|
+
* every generation and a call of a thousand outputs would leave a thousand uncollected destinations on every refresh.
|
|
374
|
+
* An output's own `keep` overrides it.
|
|
375
|
+
*/
|
|
376
|
+
readonly keep: number;
|
|
377
|
+
/**
|
|
378
|
+
* Read every stored operand at the generation it has when the call starts, for the whole call (default `true`): the call
|
|
379
|
+
* pins each one that is not already pinned. It is one generation per operand, **not one instant across operands**.
|
|
380
|
+
* `false` reads each live, as a combine does, which can describe two generations of one operand and break its pruning, and runs
|
|
381
|
+
* **no re-check** of an operand an output subtracts: an opt-out list can move during the call and the outputs that subtract it are
|
|
382
|
+
* published (`stats.operands` still reports, from one read at the end, that it moved).
|
|
383
|
+
* An operand passed already pinned is used as it is whatever this says.
|
|
384
|
+
*/
|
|
385
|
+
readonly pin?: boolean;
|
|
386
|
+
/**
|
|
387
|
+
* The most resident bytes the call counts at once, default 256 MiB: the buffered outputs, the operand streams, the
|
|
388
|
+
* chunks being evaluated and the plan, counted as resident memory. Past it, outputs run in groups and the operands are read
|
|
389
|
+
* again for each group. Process memory is more than the count (measured 1.6 to 5 times; see the guide).
|
|
390
|
+
*/
|
|
391
|
+
readonly maxBufferedBytes?: number;
|
|
392
|
+
/**
|
|
393
|
+
* The most chunk reads the call may make, counted over all its groups. Default: the store's own `budget` when it was built
|
|
394
|
+
* with one (a ceiling below the plan throws `BudgetExceededError` before any chunk is read), else what the plan needs,
|
|
395
|
+
* with headroom. `false` lifts it. The budget used is in the result's stats.
|
|
396
|
+
*/
|
|
397
|
+
readonly budget?: BudgetOption;
|
|
398
|
+
/** Outputs published at once, default 8. */
|
|
399
|
+
readonly publishConcurrency?: number;
|
|
400
|
+
/** Range requests held ahead per operand, default 1. */
|
|
401
|
+
readonly concurrency?: number;
|
|
402
|
+
/** As on every combine. */
|
|
403
|
+
readonly allowAbsentOperands?: boolean;
|
|
404
|
+
/**
|
|
405
|
+
* Operands fed as records in chunk-key order, beside the stored ones; an output names a fed operand as it names a stored
|
|
406
|
+
* one. **A feed is read once, so a call with one runs its outputs as one group, and `maxBufferedBytes` is then required**:
|
|
407
|
+
* the feed's records and the fed outputs are counted against it as they arrive, and a fed call fails as soon as the count
|
|
408
|
+
* passes it. A fed output is published only after the whole feed was read and every end-of-feed check passed.
|
|
409
|
+
*/
|
|
410
|
+
readonly feed?: MaterializeManyFeed;
|
|
411
|
+
/**
|
|
412
|
+
* Fed and held operand names allowed to hold no id. A declared fed name that appears in no record is refused at the end
|
|
413
|
+
* of the feed, and a held operand that holds no id is refused before any request, because an operand that is empty is
|
|
414
|
+
* usually an upstream query that failed quietly. Naming something that is neither a fed nor a held operand is a
|
|
415
|
+
* {@link ValidationError}.
|
|
416
|
+
*/
|
|
417
|
+
readonly mayBeEmpty?: readonly string[];
|
|
418
|
+
}
|
|
419
|
+
/**
|
|
420
|
+
* What one output of {@link CloudRoaring.materializeMany} came to: exactly what its `*Into` would have returned (a
|
|
421
|
+
* {@link MaterializeResult}, published or refused with its `reason`), or `{ published: false, error }` for what it would
|
|
422
|
+
* have thrown, or for what stopped it: a lost race ({@link WriteConflictError}), a publish whose outcome is unknown
|
|
423
|
+
* ({@link TransientError}), a damaged operand ({@link IntegrityError}), a lapsed lease ({@link LeaseExpiredError}), a
|
|
424
|
+
* pinned exclude that moved ({@link StaleOperandError}), memory ({@link BudgetExceededError}), or, for an output that names a
|
|
425
|
+
* fed operand, a bad feed ({@link ValidationError}) or an erasure in this store while the call ran ({@link StaleOperandError}
|
|
426
|
+
* with `reason: 'erased'`).
|
|
427
|
+
*/
|
|
428
|
+
export type MaterializeManyOutcome = MaterializeResult | {
|
|
429
|
+
readonly published: false;
|
|
430
|
+
readonly error: Error;
|
|
431
|
+
};
|
|
432
|
+
/** The result of {@link CloudRoaring.materializeMany}. */
|
|
433
|
+
export interface MaterializeManyRun {
|
|
434
|
+
/** One per output, in the order given: one output's refusal or error never stops another. */
|
|
435
|
+
readonly outputs: MaterializeManyOutcome[];
|
|
436
|
+
readonly stats: MaterializeManyStats;
|
|
437
|
+
}
|
|
301
438
|
/** What an `*Into` verb wrote: the new generation of the destination, and whether it became current. */
|
|
302
439
|
export interface MaterializeResult {
|
|
303
440
|
/**
|
|
@@ -351,6 +488,13 @@ export declare class CloudRoaring {
|
|
|
351
488
|
private readonly requireEncryption;
|
|
352
489
|
/** Resolved store-level per-op budget (null = disabled); the admin scans use it, with a per-op override. */
|
|
353
490
|
private readonly budget;
|
|
491
|
+
/**
|
|
492
|
+
* Moved at the start and at the end of each `eraseSubject` this store runs. A `materializeMany` call with a feed records
|
|
493
|
+
* it when it begins and is refused once it has moved: it reads caller memory, which no erasure can reach.
|
|
494
|
+
*/
|
|
495
|
+
private erasureEpoch;
|
|
496
|
+
/** How many `eraseSubject` calls of this store are running: while any is, every check of the counter counts as moved. */
|
|
497
|
+
private erasuresRunning;
|
|
354
498
|
/**
|
|
355
499
|
* Refuse any option key the store does not take, at the top level or inside a group, naming each one.
|
|
356
500
|
*
|
|
@@ -409,6 +553,148 @@ export declare class CloudRoaring {
|
|
|
409
553
|
* **And by default it collects nothing**, unlike `load()`. See the `keep` default below.
|
|
410
554
|
*/
|
|
411
555
|
private materialize;
|
|
556
|
+
/**
|
|
557
|
+
* **Hold a set of ids in memory**, to be an operand of {@link CloudRoaring.materializeMany} and of no other verb.
|
|
558
|
+
*
|
|
559
|
+
* ```ts
|
|
560
|
+
* const vip = await store.memory([7, 42, 99_001]);
|
|
561
|
+
* await store.materializeMany({ operands: { vip, engaged: store.segment('cond-engaged') }, outputs: [...], keep: 12 });
|
|
562
|
+
* vip.release();
|
|
563
|
+
* ```
|
|
564
|
+
*
|
|
565
|
+
* It takes what {@link CloudRoaring.load} takes as input (ids as a sync or async iterable or a typed array, `{ bitmap }`
|
|
566
|
+
* or `{ serialized }`) and checks it the same way, with the same errors: the size cap, the structure, the safe
|
|
567
|
+
* deserializer and each id's range. **Only a real `Uint32Array` skips the per-id range check**; any other typed array goes
|
|
568
|
+
* through it, so `Int32Array([-1])` and `Float64Array([1.5])` throw {@link ValidationError}. An object with an `ascending`
|
|
569
|
+
* key is refused: ids that arrive in key order are a `feed`. An empty set is accepted here, and refused by
|
|
570
|
+
* `materializeMany` unless its name is in `mayBeEmpty`.
|
|
571
|
+
*
|
|
572
|
+
* The ids are held as the chunks a stored generation would hold, until {@link MemoryOperand.release}; between calls that
|
|
573
|
+
* memory is the caller's, and during a call it counts against `maxBufferedBytes`. There is no size option: the load's
|
|
574
|
+
* own cap applies to a serialized input.
|
|
575
|
+
*
|
|
576
|
+
* **Erasure.** Only `eraseSubject` moves the store's counter (at its start and at its end). One that started in this store
|
|
577
|
+
* since the handle began to be made, or is still running, makes a call that reads the handle fail the outputs that read it with
|
|
578
|
+
* {@link StaleOperandError} (`reason: 'erased'`), before any request and again just before each publish. An erasure in
|
|
579
|
+
* another store or another process is not seen, nor are `dropSegment`, `eraseNamespace`, `destroySegment` and the free
|
|
580
|
+
* function `eraseIdFromSegment`, which do not move it: the handle is the caller's copy, so build it from the source of truth at
|
|
581
|
+
* the start of each refresh and release it at the end.
|
|
582
|
+
*
|
|
583
|
+
* @throws {ValidationError} where a load of the same input would.
|
|
584
|
+
*/
|
|
585
|
+
memory(input: LoadInput): Promise<MemoryOperand>;
|
|
586
|
+
/**
|
|
587
|
+
* **Many outputs, each operand read once per group.** Each output is an expression over named stored operands (`and`, `or`, `andNot`, nested
|
|
588
|
+
* to depth 64) published as a new generation of its own `dest`, exactly as an `*Into` would publish it, but computed
|
|
589
|
+
* together: each operand's chunks are read once for all the outputs that use them, instead of once per output and
|
|
590
|
+
* once more for every scratch segment a nested expression would otherwise need.
|
|
591
|
+
*
|
|
592
|
+
* ```ts
|
|
593
|
+
* const run = await store.materializeMany({
|
|
594
|
+
* operands: { us: store.segment('us'), engaged: store.segment('engaged'), optOut: store.segment('opt-out') },
|
|
595
|
+
* outputs: [
|
|
596
|
+
* { dest: store.segment('send-1'), expr: { and: ['us', 'engaged'] }, exclude: ['optOut'] },
|
|
597
|
+
* { dest: store.segment('send-2'), expr: { andNot: ['us', 'engaged'] } },
|
|
598
|
+
* ],
|
|
599
|
+
* keep: 3,
|
|
600
|
+
* });
|
|
601
|
+
* run.outputs[0]; // a MaterializeResult, or { published: false, error }
|
|
602
|
+
* ```
|
|
603
|
+
*
|
|
604
|
+
* **Results.** `run.outputs[i]` is index-aligned with `outputs` and is exactly what output `i`'s `*Into` would have
|
|
605
|
+
* returned (a {@link MaterializeResult}: published, or refused with its `reason`), or `{ published: false, error }` for
|
|
606
|
+
* what it would have thrown. One output's refusal or error never stops another. The call itself throws only for bad
|
|
607
|
+
* input ({@link ValidationError} naming the output index and path, before any request), an operand that names no
|
|
608
|
+
* segment (unless `allowAbsentOperands`), and a `budget` its own plan exceeds, the last two before any chunk is read.
|
|
609
|
+
*
|
|
610
|
+
* **One generation per operand.** By default every stored operand is pinned for the call: read at the generation it had
|
|
611
|
+
* when the call started, however long the call runs and whatever loads land meanwhile. That is one generation per
|
|
612
|
+
* operand, not one instant across operands (two pins are two registry reads). `pin: false` reads live, as a combine does.
|
|
613
|
+
*
|
|
614
|
+
* **Every pinned operand an output subtracts is re-checked.** An output subtracts an operand when it is in its `exclude`
|
|
615
|
+
* or under any entry of an `andNot` after the first, at any depth. Immediately before the publishes the call re-reads the
|
|
616
|
+
* registry row of each such operand and compares its generation and incarnation, and the fingerprint of the current
|
|
617
|
+
* object where both reads carry one, with what was pinned (a name deleted and created again is a replacement though it
|
|
618
|
+
* is generation 0 again). If one was replaced, each output that subtracts it is
|
|
619
|
+
* not published and carries {@link StaleOperandError}; the others publish. It costs one registry read per such operand per
|
|
620
|
+
* group, and `stats.operands` carries every operand's pinned, start and end generation and whether it moved.
|
|
621
|
+
*
|
|
622
|
+
* **Memory.** Everything the pass holds resident is counted against `maxBufferedBytes` (default 256 MiB): each output's
|
|
623
|
+
* buffered chunks, the operand streams' ranges, the chunks being evaluated, and the plan itself, and a call whose plan alone
|
|
624
|
+
* passes it is refused before any chunk is read. When the outputs do not fit, they run in groups, each reading its operands
|
|
625
|
+
* once (so the operand reads grow with the total output size over the budget), and a group's buffers are released only as
|
|
626
|
+
* its publishes settle. A chunk count the index understated does not grow a group past the budget: the largest buffer is
|
|
627
|
+
* dropped and that output re-runs alone. An output that cannot fit alone has `BudgetExceededError` as its result. The count
|
|
628
|
+
* is the pass's own: process memory is more, measured at 1.6 times the ledger's high water on Linux and 2.5 to 5 times on
|
|
629
|
+
* macOS on the in-memory backend (the guide has the shapes and what is not counted).
|
|
630
|
+
*
|
|
631
|
+
* **Untrusted bytes.** Every operand chunk is decoded through the checks on untrusted tier data. A key an operand's index
|
|
632
|
+
* lists whose bytes are missing is an error for the outputs that read the operand, never an empty chunk.
|
|
633
|
+
*
|
|
634
|
+
* **Handles.** An expired or released handle anywhere in the call (an operand or a `dest`) is refused before any request,
|
|
635
|
+
* as on the `*Into` verbs. A leased operand's lease, and an operand's deadline, are checked before each chunk key
|
|
636
|
+
* is read: a lapse fails only the outputs that read that operand, never reads empty. Each `dest`'s lease and deadline
|
|
637
|
+
* are checked again just before its publish.
|
|
638
|
+
*
|
|
639
|
+
* **The chunk cache is bypassed:** the pass reads through the storage source and never writes the decoded-chunk cache, so
|
|
640
|
+
* a batch does not evict other readers' hot chunks. Each publish still invalidates its `dest` as an `*Into` does.
|
|
641
|
+
*
|
|
642
|
+
* **A limit of the form.** An output cannot name another output of the same call: a `dest` that is also an operand is
|
|
643
|
+
* refused. Chain two calls.
|
|
644
|
+
*
|
|
645
|
+
* **Held operands.** An operand may be a {@link MemoryOperand} from {@link CloudRoaring.memory}: ids the caller holds,
|
|
646
|
+
* read beside the stored ones and giving the same output byte for byte. It is read from memory (no request, and the
|
|
647
|
+
* shared chunk cache never sees it), counts against `maxBufferedBytes` while the call runs, and is refused when empty
|
|
648
|
+
* unless its name is in `mayBeEmpty`. A handle from another store, or a released one, is a {@link ValidationError}. An
|
|
649
|
+
* erasure in this store since the handle was made fails the outputs that read it with {@link StaleOperandError}
|
|
650
|
+
* (`reason: 'erased'`).
|
|
651
|
+
*
|
|
652
|
+
* **A feed.** `feed: { names, records, counts }` adds operands that arrive as records in chunk-key order, for conditions
|
|
653
|
+
* too many to hold or store. Each record is checked before the pass sees it (see {@link MaterializeManyFeedRecord}): a bad
|
|
654
|
+
* feed is refused, never read as fewer members, and **a fed output is published only after the whole feed was read and every
|
|
655
|
+
* end-of-feed check passed**, so a bad feed refuses every fed output and publishes none of them; outputs that name only
|
|
656
|
+
* stored operands are unaffected. At the end of the feed `counts` must equal the ids the feed held for each name, and a
|
|
657
|
+
* name that appeared in no record is refused unless it is in `mayBeEmpty`. A feed is read once, so the call runs its outputs
|
|
658
|
+
* as one group and **`maxBufferedBytes` is required**: each record is converted to compressed bitmaps as it arrives, the key
|
|
659
|
+
* in hand and its fed outputs are counted against the budget, and the call fails as soon as the count passes it, with
|
|
660
|
+
* {@link BudgetExceededError} for every fed output. **Erasure:** a fed call is refused at its next record, and before each
|
|
661
|
+
* fed publish, once `eraseSubject` has started in this store ({@link StaleOperandError}, `reason: 'erased'`).
|
|
662
|
+
*
|
|
663
|
+
* ```ts
|
|
664
|
+
* await store.materializeMany({
|
|
665
|
+
* operands: { unsub: store.segment('global-unsub') },
|
|
666
|
+
* feed: {
|
|
667
|
+
* names: ['us', 'engaged'],
|
|
668
|
+
* records: warehouseRecords(), // yields { key, operands: { us: Uint32Array, engaged: Uint32Array } } by key
|
|
669
|
+
* counts: () => warehouseCounts(),
|
|
670
|
+
* },
|
|
671
|
+
* maxBufferedBytes: 512 * 1024 * 1024,
|
|
672
|
+
* outputs: [{ dest: store.segment('send-1'), expr: { and: ['us', 'engaged'] }, exclude: ['unsub'] }],
|
|
673
|
+
* keep: 12,
|
|
674
|
+
* });
|
|
675
|
+
* ```
|
|
676
|
+
*/
|
|
677
|
+
materializeMany(options: MaterializeManyOptions): Promise<MaterializeManyRun>;
|
|
678
|
+
private epochNow;
|
|
679
|
+
/**
|
|
680
|
+
* Whether an erasure has started in this store since `at` was read, or was running when it was: one that is still
|
|
681
|
+
* running is seen by the count of those running, and one that has ended since by the counter, which its end moved.
|
|
682
|
+
* The one check every call that reads caller memory uses.
|
|
683
|
+
*/
|
|
684
|
+
private epochMoved;
|
|
685
|
+
/** A call's feed with the store's erasure counter: read once here, checked by the combine before any record is read. */
|
|
686
|
+
private feedOf;
|
|
687
|
+
/**
|
|
688
|
+
* The registry row of `ref`, read straight from the registry, not from a snapshot: a re-check must see a move. With
|
|
689
|
+
* `fingerprint`, the current generation's object is opened too (one tail read, as a pin of it makes), and its
|
|
690
|
+
* fingerprint is returned beside the row: a generation's number is identified by its row and its object, since a number
|
|
691
|
+
* can be taken again once its object is gone.
|
|
692
|
+
*/
|
|
693
|
+
private currentRowOf;
|
|
694
|
+
/** Throw what a read of `handle` must throw now: its lease error, or a refusal for a deadline that has passed. */
|
|
695
|
+
private assertReadable;
|
|
696
|
+
/** {@link assertReadable} for a destination, named by where it sits in the call. */
|
|
697
|
+
private assertWritable;
|
|
412
698
|
/**
|
|
413
699
|
* **Subject access (GDPR Art. 15 / CCPA right-to-know): which segments is this id a member of?**
|
|
414
700
|
*
|
|
@@ -499,6 +785,7 @@ export declare class CloudRoaring {
|
|
|
499
785
|
concurrency?: number;
|
|
500
786
|
budget?: BudgetOption;
|
|
501
787
|
}): Promise<EraseSubjectResult>;
|
|
788
|
+
private eraseSubjectRun;
|
|
502
789
|
/**
|
|
503
790
|
* Every generation still in the bucket for this segment, ascending, with the current one marked.
|
|
504
791
|
*
|
|
@@ -1185,6 +1472,26 @@ export interface SegmentStat {
|
|
|
1185
1472
|
/** The metadata the generation was loaded with; absent when it has none. */
|
|
1186
1473
|
readonly metadata?: GenerationMetadata;
|
|
1187
1474
|
}
|
|
1475
|
+
/**
|
|
1476
|
+
* A set of ids held in memory by {@link CloudRoaring.memory}, to be an operand of {@link CloudRoaring.materializeMany}
|
|
1477
|
+
* and of no other verb. The bytes are the caller's until {@link MemoryOperand.release}.
|
|
1478
|
+
*
|
|
1479
|
+
* It belongs to the store that made it. `eraseSubject` in that store, started after the handle began to be made or still
|
|
1480
|
+
* running when it was, fails the outputs of a `materializeMany` call that read it with {@link StaleOperandError}
|
|
1481
|
+
* (`reason: 'erased'`): the call does not throw, and its outputs that do not read the handle publish. Nothing else is
|
|
1482
|
+
* seen: an erasure in another store or process, and
|
|
1483
|
+
* `dropSegment`, `eraseNamespace`, `destroySegment` and the free function `eraseIdFromSegment`, do not move the counter.
|
|
1484
|
+
*/
|
|
1485
|
+
export declare class MemoryOperand {
|
|
1486
|
+
private readonly view;
|
|
1487
|
+
/** Not constructible: a handle comes from {@link CloudRoaring.memory}. */
|
|
1488
|
+
private constructor();
|
|
1489
|
+
/**
|
|
1490
|
+
* Zero and drop the bytes it holds. Any later use throws {@link ValidationError}; releasing twice does nothing. A call
|
|
1491
|
+
* still reading it fails the outputs that read it.
|
|
1492
|
+
*/
|
|
1493
|
+
release(): void;
|
|
1494
|
+
}
|
|
1188
1495
|
/**
|
|
1189
1496
|
* A handle bound to one segment — the read verbs, plus the three `*Into` verbs that write a **new generation**
|
|
1190
1497
|
* of another segment.
|
|
@@ -1586,5 +1893,5 @@ export declare class Segment {
|
|
|
1586
1893
|
}): Promise<CostReport>;
|
|
1587
1894
|
}
|
|
1588
1895
|
export { deserializePortable };
|
|
1589
|
-
export { MemoryStorage, LocalFsStorage, CrbmStorageChunkSource, destroySegment, eraseNamespace, excludingReservedRows, readRetentionPolicy, MIN_EXPIRES_AT_MS, LEASE_SKEW_MS, MAX_LEASE_MS, MAX_LEASES_PER_SEGMENT, InProcessKeystore, NodeAead, aadFor, CloudRoaringError, ValidationError, WriteConflictError, IntegrityError, NotFoundError, UnsupportedError, CapabilityError, TransientError, KeyUnavailableError, BudgetExceededError, LeaseExpiredError, LeaseLimitError, isCloudRoaringError, isWriteConflictError, isTransientError, isNotFoundError, isIntegrityError, isValidationError, isLeaseExpiredError, isLeaseLimitError, CrbmReader, BufferReader, CountingMetricsSink, RecordingAuditSink, DEFAULT_RETRY_POLICY, AWS_US_EAST_1_ONDEMAND, ELASTICACHE_REDIS_US_EAST_1_ONDEMAND, ONE_REDIS_HA_CLUSTER, } from '@cloudbitmaps/core';
|
|
1896
|
+
export { MemoryStorage, LocalFsStorage, CrbmStorageChunkSource, destroySegment, eraseNamespace, excludingReservedRows, readRetentionPolicy, MIN_EXPIRES_AT_MS, LEASE_SKEW_MS, MAX_LEASE_MS, MAX_LEASES_PER_SEGMENT, InProcessKeystore, NodeAead, aadFor, CloudRoaringError, ValidationError, WriteConflictError, IntegrityError, NotFoundError, UnsupportedError, CapabilityError, TransientError, KeyUnavailableError, BudgetExceededError, LeaseExpiredError, LeaseLimitError, StaleOperandError, isCloudRoaringError, isWriteConflictError, isTransientError, isNotFoundError, isIntegrityError, isValidationError, isLeaseExpiredError, isLeaseLimitError, isStaleOperandError, CrbmReader, BufferReader, CountingMetricsSink, RecordingAuditSink, DEFAULT_RETRY_POLICY, AWS_US_EAST_1_ONDEMAND, ELASTICACHE_REDIS_US_EAST_1_ONDEMAND, ONE_REDIS_HA_CLUSTER, } from '@cloudbitmaps/core';
|
|
1590
1897
|
export type { Aead, AeadSealed, AuditEvent, BlobReader, BlobSink, Budget, BudgetOption, ChunkRef, Clock, CodecBitmap, CodecInterface, ConsistencyErrorEntry, ConsistencyIssue, ConsistencyReport, CostReport, CrbmCrypto, CrbmReaderOptions, CrbmStorageChunkSourceOptions, DestroyResult, ClearRegistrySummary, DropResult, EncodedChunk, EraseDeps, EstimateInput, ExportFailure, ExportFormat, ExportManifest, ExportOptions, ExportSink, ExportWriter, ExportedSegment, GenKey, GenerationEntry, GenerationMetadata, GovernanceMeta, IAuditSink, IKeystore, IMetricsSink, IRegistryDriver, IStorageDriver, IdRange, InProcessKeystoreOptions, LoadGuard, LoadInput, LoadOptions, LoadRefusal, LoadResult, LocalFsStorageOptions, MemoryStorageOptions, MetricEvent, MetricOpName, MetricsSnapshot, NewRegistryRecord, PinnedAt, PinnedObject, PortableBitmap, PricingProfile, RedisNodeType, RedisSizing, RegCaps, RegistryPatch, RegistryRecord, RegistryStatus, RegistrySummary, ReapRegistryTombstonesOptions, ReapRegistryTombstonesResult, RegistryWriteOptions, LeaseEntry, RetentionPolicy, RetireEntry, RetireExpiredOptions, RetireExpiredResult, RetryPolicy, Rng, RollbackResult, SealedRegistrySummary, SegmentInfo, SegmentRef, SegmentSize, SegmentSizing, SetRetentionResult, StorageBackend, StorageCaps, StorageChunkSource, Token, Workload, WrappedDek, } from '@cloudbitmaps/core';
|