@zenfs/core 2.7.6 → 2.8.0

package/dist/backends/single_buffer/v2.d.ts

@@ -0,0 +1,257 @@
+import type { ArrayOf } from 'memium';
+import { BPlusTree, type BPlusTreeStorage } from 'memium/bplustree';
+import { EpochTable, Mutex } from 'memium/locks';
+import type { UUID } from 'node:crypto';
+import { BufferView } from 'utilium/buffer';
+import type { UsageInfo } from '../../internal/filesystem.js';
+import type { StoreFS } from '../store/fs.js';
+import { SyncMapTransaction, type SyncMapStore } from '../store/map.js';
+import type { Store } from '../store/store.js';
+declare const Extent_base: import("memium").StructConstructor<BufferView<any>>;
+/** A range of bytes */
+export declare class Extent extends Extent_base {
+    static name: string;
+    accessor offset: number;
+    accessor size: number;
+}
+/** Where the data for an ID is stored */
+export declare class DataExtent extends Extent {
+    static name: string;
+    /** Bytes allocated, which can exceed `size` so data can grow in place */
+    accessor capacity: number;
+}
+declare const Commit_base: import("memium").StructConstructor<BufferView<any>>;
+/** The roots and allocator state written by a transaction */
+export declare class Commit extends Commit_base {
+    static name: string;
+    /** crc32c of the rest of the commit */
+    accessor checksum: number;
+    accessor generation: bigint;
+    /** ID to extent */
+    accessor index_root: number;
+    accessor index_count: number;
+    /** Free extents by offset */
+    accessor free_root: number;
+    /** Free extents by size then offset */
+    accessor size_root: number;
+    accessor free_count: number;
+    accessor free_bytes: number;
+    /** The newest block in the list of spare blocks for tree nodes */
+    accessor spare_head: number;
+    /** Spare blocks listed by `spare_head` */
+    accessor spare_count: number;
+    /** Spare blocks in the entire list */
+    accessor spare_total: number;
+    /** Blocks listing extents that are free once no reader can see them */
+    accessor pending_head: number;
+    accessor pending_tail: number;
+    accessor pending_bytes: number;
+    protected computeChecksum(): number;
+    update(): void;
+    isValid(generation: bigint): boolean;
+}
+declare const State_base: import("memium").StructConstructor<BufferView<any>>;
+/** State shared by every thread using a file system, which is followed by an epoch table */
+export declare class State extends State_base {
+    static name: string;
+    /** Held by writers */
+    accessor lock: bigint;
+    /** The generation of the current commit */
+    accessor generation: bigint;
+    accessor next_id: bigint;
+    /** The current and previous commits, at their generation modulo 2 */
+    accessor commits: ArrayOf<Commit>;
+}
+declare const PendingHeader_base: import("memium").StructConstructor<BufferView<any>>;
+/** The start of a block listing extents retired by a generation, which is followed by the extents */
+export declare class PendingHeader extends PendingHeader_base {
+    static name: string;
+    accessor next: number;
+    accessor count: number;
+    accessor generation: bigint;
+}
+declare const SpareHeader_base: import("memium").StructConstructor<BufferView<any>>;
+/**
+ * The start of a block listing spare blocks, which is followed by their offsets.
+ * The newest block's count is in the commit instead.
+ */
+export declare class SpareHeader extends SpareHeader_base {
+    static name: string;
+    accessor next: number;
+    accessor count: number;
+}
+declare const SuperBlock_base: import("memium").StructConstructor<BufferView<any>>;
+/**
+ * The super block for version 2 of the single-buffer format.
+ * Bytes 0 through 12 have the same layout in every version.
+ */
+export declare class SuperBlock extends SuperBlock_base {
+    static name: string;
+    /** crc32c of the bytes from 4 up to `lock` */
+    accessor checksum: number;
+    accessor magic: number;
+    /**
+     * The version of the on-disk format
+     * 1: v1.10.0+, append-only metadata blocks
+     * 2: copy-on-write B+ trees
+     */
+    accessor version: number;
+    /** Which format of `Inode` is used */
+    accessor inode_format: number;
+    /** Features that must be supported to mount the file system. None are defined. */
+    accessor required_features: number;
+    /** Features that may be ignored. None are defined. */
+    accessor optional_features: number;
+    /** Size of tree nodes and other metadata blocks */
+    accessor block_size: number;
+    /** The size of the entire file system, including the super block */
+    accessor total_bytes: bigint;
+    accessor uuid: Uint8Array;
+    /** Byte offset of the shared state */
+    accessor state_offset: number;
+    accessor epoch_slots: number;
+    /** An optional label for the file system */
+    accessor label: Uint8Array;
+    protected accessor _padding: Uint8Array;
+    /** Held while the file system is created or upgraded. Not covered by the checksum. */
+    accessor lock: bigint;
+    protected computeChecksum(): number;
+    update(): void;
+    /** Checks that a file system of `byteLength` bytes can be mounted using this super block */
+    validate(byteLength: number): void;
+}
+/**
+ * A transaction that changes a file system, which is built from copies of the blocks it changes.
+ * Nothing it does is visible until it is committed.
+ */
+export declare class WriteTransaction implements BPlusTreeStorage {
+    protected readonly store: SingleBufferStore;
+    protected readonly spareScale: number;
+    readonly buffer: ArrayBufferLike;
+    readonly pageSize: number;
+    readonly generation: bigint;
+    /** ID to extent */
+    readonly index: BPlusTree<bigint, DataExtent>;
+    /** Free extents by offset */
+    protected readonly byOffset: BPlusTree<number, number>;
+    /** Free extents by size then offset */
+    protected readonly bySize: BPlusTree<bigint, void>;
+    protected freeBytes: number;
+    protected spareHead: number;
+    protected spareCount: number;
+    protected spareTotal: number;
+    /** Spare blocks listed by the base commit in the newest list block, which can not be overwritten */
+    protected spareFloor: number;
+    protected readonly spareCapacity: number;
+    protected pendingHead: number;
+    protected pendingTail: number;
+    protected pendingBytes: number;
+    /** Blocks allocated by this transaction */
+    protected readonly fresh: Set<number>;
+    /** Blocks no commit references, which can be reused immediately */
+    protected recycled: number[];
+    /** Extents that become free once no reader can see them */
+    protected retired: [offset: number, size: number][];
+    /** Whether the free trees are being changed, during which spares are not refilled */
+    protected changingFreeTrees: boolean;
+    /**
+     * @param base The commit this transaction starts from
+     * @param spareScale Multiplies the number of spare blocks to keep
+     */
+    constructor(store: SingleBufferStore, base: Commit, spareScale: number);
+    offsetOf(block: number): number;
+    alloc(): number;
+    free(block: number): void;
+    /** Minimum blocks available for tree nodes, enough to copy and split a path in both free trees */
+    protected lowWater(): number;
+    /** Blocks that can be allocated without changing the free trees */
+    protected availableBlocks(): number;
+    /** Takes a spare block, if there are any */
+    protected popSpare(): number | undefined;
+    /** Adds a free block to the spare blocks */
+    protected pushSpare(block: number): void;
+    /** Refills the spare blocks if they are below the low-water mark */
+    protected refillSpares(): void;
+    protected changeFreeTrees<T>(change: () => T): T;
+    /** Removes the free extent at `offset`, then returns everything after its first `size` bytes to free space */
+    protected split(offset: number, length: number, size: number): void;
+    /** Takes the smallest free extent that fits `size` bytes */
+    protected takeBestFit(size: number): number;
+    /** Allocates `size` bytes for data, leaving enough blocks to change the free trees */
+    allocate(size: number): number;
+    /** Frees an extent no reader can see, merging it with adjacent free extents */
+    freeExtent(offset: number, size: number): void;
+    /** Frees an extent once no reader can see this transaction's base */
+    retire(offset: number, size: number): void;
+    /** Frees extents retired by generations that readers no longer see */
+    protected releasePending(oldest: bigint | undefined): void;
+    protected appendPending(offset: number, size: number): void;
+    /** Records retired extents in the pending list, then writes this transaction's roots and allocator state to `commit` */
+    commit(commit: Commit): void;
+}
+export interface FormatOptions {
+    /** Byte ranges that are already in use */
+    used?: [start: number, end: number][];
+    uuid?: Uint8Array;
+    label?: Uint8Array;
+    /** The first ID to allocate */
+    nextId?: bigint;
+    /** Adds existing data in the first transaction */
+    populate?(tx: WriteTransaction): void;
+}
+export interface SingleBufferStoreOptions {
+    /** Erases the buffer and creates a new file system */
+    format?: boolean | FormatOptions;
+}
+/**
+ * A store for version 2 of the single-buffer format.
+ *
+ * Every change is a transaction that copies what it modifies.
+ * Readers never block, and an interrupted writer does not change the file system.
+ * @category Stores and Transactions
+ */
+export declare class SingleBufferStore extends DataView<ArrayBufferLike> implements SyncMapStore {
+    readonly flags: readonly ["partial"];
+    readonly name = "sbfs";
+    readonly type = 1935828595;
+    get uuid(): UUID;
+    protected readonly superblock: SuperBlock;
+    /**
+     * The entire file system
+     * @internal
+     */
+    readonly bytes: Uint8Array;
+    /** @internal */
+    readonly blockSize: number;
+    /** @internal */
+    readonly epochs: EpochTable;
+    protected readonly mutex: Mutex;
+    protected readonly generation: BigInt64Array;
+    protected readonly nextId: BigInt64Array;
+    protected readonly commits: [Commit, Commit];
+    /** The index of the version being read */
+    protected readonly index: BPlusTree<bigint, DataExtent>;
+    /**
+     * Opens a file system, or creates one if `format` is set.
+     * When creating one, byte ranges in `used` are kept, and the first transaction runs `populate` after making everything else free.
+     */
+    constructor(buffer: ArrayBufferLike | ArrayBufferView, byteOffset?: number, byteLength?: number, options?: SingleBufferStoreOptions);
+    /** Reads the current commit, retrying if a writer replaces it while reading */
+    protected withCurrentCommit<T>(read: (commit: Commit, generation: bigint) => T): T;
+    /** Runs `read` against the current version, which stays valid until `read` returns */
+    protected read<T>(read: (index: BPlusTree<bigint, DataExtent>) => T): T;
+    /** Runs `change` in a write transaction, retrying with more spare blocks if the free trees run out of them */
+    write<T>(change: (tx: WriteTransaction) => T): T;
+    keys(): number[];
+    get(id: number, offset?: number, end?: number): Uint8Array | undefined;
+    set(id: number, data: Uint8Array, offset?: number): void;
+    delete(id: number): void;
+    allocId(): [ino: number, data: number];
+    usage(): UsageInfo;
+    protected _fs?: StoreFS<Store> | undefined;
+    get fs(): StoreFS<Store> | undefined;
+    set fs(fs: StoreFS<Store> | undefined);
+    sync(): Promise<void>;
+    transaction(): SyncMapTransaction;
+}
+export {};