NAME

Developer::Dashboard::Pax::Tier1 - emits and smoke-tests native C artifacts for a guarded SSA region

SYNOPSIS

use Developer::Dashboard::Pax::Tier1;

my $planner = Developer::Dashboard::Pax::Tier1->new( out_dir => '.pax/native' );
my $result  = $planner->compile($ssa_unit);

DESCRIPTION

Given one guarded SSA region (the output of region selection over a hot loop or leaf op PAX has decided is worth native-compiling), compile matches the region's native_shape against a small set of known shapes (an i64 sum loop, a masked-mix accumulator loop, a binary i64 leaf op) and, when a match is found, emits a standalone C translation unit for it, compiles that C with the system cc/gcc into both a shared library and (where the shape supports it) a smoke-testable executable, and reports the resulting artifact alongside tier-1 (Cranelift-equivalent C ABI, see Developer::Dashboard::Pax::Backend::Tier1CraneliftEquivalent) and tier-2 (LLVM, see Developer::Dashboard::Pax::Backend::Tier2LLVM) backend metadata. No native toolchain available, or no shape emitter matched, both degrade to a fallback_artifact/native_probe_trampoline rather than failing the whole compile.

METHODS

new, compile

new takes backend (default portable-fallback) and out_dir (default .pax/native). compile takes one SSA unit hash and returns the artifact-description hash described above.

PURPOSE

Turns a single guarded SSA region into a real, compiled, smoke-tested native artifact (or an honest fallback description when that isn't possible on the current machine), so everything above this module in the pipeline - PAX's build/run CLI, standalone binary packaging - can treat "was this region natively compiled, and does the artifact actually work" as one small, testable question answered in one place.

WHY IT EXISTS

The C emission and the "did it actually work" smoke test (running the compiled executable with two sample inputs and comparing the observed output against the expected one) are both genuinely fallible - the host may lack a C compiler, or the emitted source may fail to build - and every caller needs the SAME honest answer about which happened. Centralizing the match-shape/emit-C/compile/smoke-test sequence here means a region that falls back to interpretation is indistinguishable in behavior, but not in reporting, from one that was successfully compiled natively.

WHEN TO USE

Edit this file when adding support for a new native-shape kind (extend _c_source_for_region's shape dispatch and add a matching _c_*_body emitter), when changing how the smoke test is run or judged, or when the tier-1/tier-2 backend metadata this module attaches to a result needs to change shape.

HOW TO USE

Construct a Tier1 planner with an out_dir for its generated C sources, shared libraries and executables, then call compile with one SSA unit that has already been through guard insertion and region selection. Read the returned hash's status field first (native_artifact vs fallback_artifact) before trusting library_path/executable_path, since a fallback result legitimately omits them.

WHAT USES IT

PAX's own build pipeline (Developer::Dashboard::Pax::CLI's build command path) invokes this once per region GuardedSSA and region selection have marked as native-compilation-eligible; the standalone binary packaging path (StandaloneImage/StandaloneRuntime) consumes the resulting artifact paths when assembling a compiled binary.

EXAMPLES

Example 1:

my $planner = Developer::Dashboard::Pax::Tier1->new;
my $result  = $planner->compile({
    region_id    => 'r1',
    native_shape => { kind => 'i64_binary_leaf', op => 'add', smoke_left => 2, smoke_right => 3, smoke_expected => 5 },
});
# $result->{status} eq 'native_artifact' on a host with a working cc

Example 2:

perl -Ilib -MDeveloper::Dashboard::Pax::Tier1 -e 1

Confirm the module loads cleanly from a source checkout before wiring in a new native shape.