frozen_run

Replayable run plans: every resolved setting, the model’s hash and the toolchain and runtime identities, saved so another host can rebuild the same run.

Every name on this page is imported from helia_profiler.

API tier: experimental

Generated from the src/helia_profiler tree f38e378c801d34438affb680257217e0b58d2cd1.

Machine-readable model

FrozenModelclassThe model a plan was frozen against, identified by content.
ToolchainIdentityclassThe compiler a plan expects: name and exact version, never a path.
FrozenRuntimeclassThe engine and kernel sources a profile build uses.
LocalInputclassA local file or directory the build reads instead of a pinned source.
FrozenRunclassA resolved, replayable run plan.

FrozenModel(path: str, sha256: str, size_bytes: int) -> None

dataclass

The model a plan was frozen against, identified by content.

API tier: experimental

path: str

sha256: str

size_bytes: int

ToolchainIdentity(name: str, version: str | None, unavailable_reason: str | None = None) -> None

dataclass

The compiler a plan expects: name and exact version, never a path.

version holds the version-bearing lines of <compiler> --version; it is None when the compiler could not be run, with the reason in unavailable_reason.

API tier: experimental

name: str

version: str | None

unavailable_reason: str | None = None

lines: tuple[str, ...]

The version-bearing lines version joins, or none when it is unknown.

FrozenRuntime(
    name: str,
    version: str | None,
    source_commit: str | None,
    kernels_module: str | None = None,
    kernels_commit: str | None = None,
    unavailable_reason: str | None = None,
) -> None

dataclass

The engine and kernel sources a profile build uses.

Commits are NSX module or source revisions from the compatibility baseline or the installed package. kernels_commit is None when the engine links no kernel library or its provider is overridden.

API tier: experimental

name: str

version: str | None

source_commit: str | None

kernels_module: str | None = None

kernels_commit: str | None = None

unavailable_reason: str | None = None

LocalInput(setting: str, path: str, kind: str, sha256: str | None = None) -> None

dataclass

A local file or directory the build reads instead of a pinned source.

Files are identified by content. A directory is recorded by path only, so a plan with one is not portable to another host.

API tier: experimental

setting: str

path: str

kind: str

sha256: str | None = None

FrozenRun(
    settings: Mapping[str, Any],
    model: FrozenModel,
    baseline_id: str,
    baseline_fingerprint: str,
    qualification: str,
    overrides: tuple[str, ...],
    local_inputs: tuple[LocalInput, ...],
    environment: Mapping[str, str],
    toolchain: ToolchainIdentity,
    runtime: FrozenRuntime | None,
    hpx_version: str,
) -> None

dataclass

A resolved, replayable run plan. Build it with :meth:Session.freeze.

API tier: experimental

settings: Mapping[str, Any]

model: FrozenModel

baseline_id: str

baseline_fingerprint: str

qualification: str

overrides: tuple[str, ...]

local_inputs: tuple[LocalInput, ...]

environment: Mapping[str, str]

toolchain: ToolchainIdentity

runtime: FrozenRuntime | None

hpx_version: str

intent_hash: str

The hpx.intent hash of what this plan asks for; the HPX release is not part of it.

portable: bool

Whether every input is pinned or content-identified, so another host can rebuild it.

A compiler environment variable makes a plan host-specific, since the files it may name are not tracked, and so do a dependency selector that names a branch, tag or version rather than a commit and a custom heliaRT release, whose archive is not content-identified.

to_dict() -> dict[str, Any]

from_dict(data: Mapping[str, Any]) -> FrozenRun

classmethod

save(path: str | Path) -> Path

Write the plan as JSON, refusing its source model path or aliases.

load(path: str | Path) -> FrozenRun

classmethod

Read a plan written by :meth:save, verifying its intent hash.

config(*, model: str | Path | None = None, host: Mapping[str, Any] | None = None) -> ProfileConfig

The :class:ProfileConfig this plan describes, on this host.

host supplies host-local settings for the replaying host, for example {"target": {"jlink_serial": "..."}, "output": {"dir": "..."}}; any other key is refused. Refuses when this HPX carries a different baseline, when the model (the recorded path, or model when it moved) has a different hash, when a local input differs or is missing, or when this host would build something else: a source-path environment variable set, unset or changed, another compiler version, or another engine runtime. Only the model can move; other local files must be at their recorded paths.

build(fixture: TypedFixture, **options: Any = {}) -> CompiledBuild

Compile this plan for fixture’s pinned inputs; see :func:~helia_profiler.build.

Machine-readable: frozen_run.json · frozen_run.md, complete and lossless.