Skip to content

seal

seal #

Sealing: a workspace tree becomes an immutable object, named by its own hash.

  1. seal_tree hashes and measures a tree, renames it to objects/<hash> (an equal tree already there wins and the copy is dropped) and write-protects it, all outside the index.
  2. One index transaction then records the object, names it, and pins it, so no other process's eviction ever sees it unheld.

Looking a call up is the reverse, in one transaction: resolve its names, check every object is still on disk, and pin them.

lookup_call(scratch, key, count) #

The call key's count results, pinned, or None unless every one is present.

Source code in capturegraph-lib/capturegraph/scratch/store/seal.py
def lookup_call(scratch: Scratch, key: CallKey, count: int) -> list[Pinned] | None:
    """The call ``key``'s ``count`` results, pinned, or ``None`` unless every one is present."""
    now = time.time()
    with scratch.database.transaction() as db:
        hashes = names.call_results(db, key)
        if len(hashes) != count or not all(scratch.object_dir(hash).is_dir() for hash in hashes):
            return None
        for hash in hashes:
            row = objects.get(db, hash)
            if row is not None:
                objects.touch(db, hash, bumped_score(row, now), now)
        return [Pinned(scratch, hash) for hash in hashes]

seal_call(scratch, key, workspace, stems, compute_seconds) #

Seal workspace/<stem> for each stem as the call key's results, in order.

Source code in capturegraph-lib/capturegraph/scratch/store/seal.py
def seal_call(
    scratch: Scratch,
    key: CallKey,
    workspace: LiveDir,
    stems: list[str],
    compute_seconds: float,
) -> list[Pinned]:
    """Seal ``workspace/<stem>`` for each stem as the call ``key``'s results, in order."""
    sealed = [seal_tree(scratch, workspace.path / stem) for stem in stems]
    with scratch.database.transaction() as db:
        for position, (hash, size_bytes) in enumerate(sealed):
            objects.seed(db, hash, size_bytes)
            objects.raise_compute(db, hash, compute_seconds)
            names.point(db, names.call_name(key, position), hash, kept=False)
        held = [Pinned(scratch, hash) for hash, _ in sealed]
    workspace.release()
    scratch.evict()
    return held

seal_tree(scratch, source) #

Move the tree at source into objects/ under its own hash, not yet indexed.

Returns:

Type Description
tuple[ContentHash, int]

The object's hash and size in bytes, for the caller to objects.seed.

Source code in capturegraph-lib/capturegraph/scratch/store/seal.py
def seal_tree(scratch: Scratch, source: Path) -> tuple[ContentHash, int]:
    """Move the tree at ``source`` into ``objects/`` under its own hash, not yet indexed.

    Returns:
        The object's hash and size in bytes, for the caller to ``objects.seed``.
    """
    hash = scratch.hash_tree(source)
    destination = scratch.object_dir(hash)
    if promote(source, destination):
        protect_files(destination)
        scratch.file_hashes.move(source, destination)
    else:
        scratch.file_hashes.forget(source)
    return hash, tree_size(destination)