NAME

Developer::Dashboard::PaxCache - MD5-keyed, non-blocking, per-machine PAX compile cache

PURPOSE

Decides, for one Perl source file at a time, whether the current invocation should run a cached PAX-compiled standalone binary or fall back to the normal interpreted path - and if the cache is missing or stale, triggers at most one detached background compile so a later invocation can benefit, without ever blocking the invocation that discovered the cache was stale.

WHY IT EXISTS

DD-871/DD-872 measured that PAX (a sibling adaptive Perl compiler/packager) can compile this project's CLI entrypoints cleanly and run them roughly 36x faster than interpreted Perl. DD-877 turns that measurement into a real, safe caching layer: correctness only holds if a compile never blocks the user (owner decision, Q-157) and if overlapping invocations of the same stale source never each spawn their own redundant compile process - a defect the owner explicitly flagged as "make sure to prevent this disaster" (Telegram msg #1975, 2026-09-15) after asking what would happen if a second invocation arrived while the first invocation's background compile was still running.

WHEN TO USE

Any internal CLI command that wants to transparently benefit from a PAX compiled binary, once one exists and is fresh, calls resolve() with its own source file's path before deciding how to run itself.

HOW TO USE

my $cache = Developer::Dashboard::PaxCache->new( paths => $paths );
my $binary_path = $cache->resolve('/path/to/share/private-cli/ps1');
if ( defined $binary_path ) {
    exec { $binary_path } $binary_path, @ARGV;
}
# else: fall through to the normal interpreted dispatch path.

WHAT USES IT

bin/dashboard's _exec_switchboard_command calls this immediately before its existing command_argv_for_path resolution, currently scoped to the ps1 command only as a proof of concept under epic DDE-002.

EXAMPLES

Example 1:

perl -Ilib -MDeveloper::Dashboard::PaxCache -e 1

Do a direct compile-and-load check against the module from a source checkout.

Example 2:

prove -lv t/181-paxcache-coverage.t

Run the focused regression tests that exercise cache-hit, cache-miss, stale-MD5, no-pax-installed, and the overlapping-invocation concurrency guard directly.

Example 3:

HARNESS_PERL_SWITCHES=-MDevel::Cover prove -lr t

Recheck the module under the repository coverage gate rather than relying on a load-only probe.

Example 4:

prove -lr t

Put any module-level change back through the entire repository suite before release.