Skip to content

Decouple allocator runtime files from checkpoint generations #758

Description

@zhanglei1949

Motivation

Allocator mmap backing files are runtime scratch state, not durable checkpoint contents. The database currently stores them under checkpoint-N/allocator, even though startup removes and recreates that directory and recovery does not consume those files. This couples allocator lifetime to checkpoint publication and GC, makes published checkpoints contain mutable runtime files, and forces checkpoint preparation to know the future published checkpoint path.

Proposal

Move allocator backing files out of checkpoint directories into an independently managed runtime workspace under the database directory.

  • Give each open database instance an isolated runtime directory.
  • Manage allocator backing files in runtime generations so the next empty allocator state can be prepared before a destructive checkpoint.
  • After publishing and reopening the graph, atomically install the prepared allocator state.
  • Release the retired allocator mmap/buffer state before promptly deleting its runtime generation.
  • Clean abandoned runtime generations on startup/close without interfering with concurrently opened read-only instances.
  • Keep WAL generation ownership unchanged because WAL files participate in recovery.

Acceptance criteria

  • Published checkpoint directories no longer contain an allocator subdirectory.
  • Allocator mmap files live in an instance-isolated runtime generation.
  • Checkpoint success rotates to a fresh allocator generation and removes the retired generation after references are released.
  • Failed preparation cleans the unused generation and leaves the current runtime intact.
  • Database close and startup recovery clean allocator runtime directories safely.
  • Tests cover rotation, failure cleanup, restart cleanup, and isolation.

Out of scope

Changing the published_path API or WAL publication protocol. Those changes should follow separately after this refactor is merged.

Metadata

Metadata

Assignees

Labels

storeStorage layer

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions