[galletas1712]

Closed pending design discussion: At the requester’s direction, this implementation is deferred while #521 discusses PageBroker staging, direct restore, artifact-addressed integration, ownership and isolation. The branch and measurements are retained as experimental evidence. This is not an approved design, and no further implementation is planned before that discussion.

What type of PR is this?

• enhancement

What this PR does / why we need it:

Cold NFS images make CRIU wait on thousands of small reads while rebuilding large ghost files. Prefetch non-page images with 32 bounded readers and 1 MiB buffers before CRIU starts. On the eight-B200 GLM-5.3-NVFP4 fixture, median agent restore fell from 31.514 to 25.401 seconds (19.4%), including prefetch time.

The helper applies only to NFS, skips CPU page payloads, and uses ordinary reclaimable file cache. It opens at most 32 files at once and uses at most 32 MiB of read buffers per restore. It changes no backing-device settings and requires no CRIU fork or new configuration option. Prefetch failures leave CRIU to read and validate images normally. Preparation time remains part of the existing timing summary.

This replaces the shared read-ahead approach in #523. Detailed image contents, mechanism, alternatives, cold/warm measurements and limitations are in #521.

Which issue(s) this PR fixes:

Related to #521. Implementation deferred pending discussion.

How was this tested?

• 34 real GLM restores across controls and candidates, 204/204 semantic inference requests passed. The final comparison uses four cold restores per arm in balanced order. Additional matched warm-cache checks passed.
• 33 focused NFS microbenchmarks with verified cache state and NFS counters.
• make test build passed across all modules.
• CRIU package race tests passed, including payload exclusion and rejection of replaced symlink/FIFO entries.
• All three Go-module linters, Helm lint and TOC verification passed.
• Full make check still fails at the dependency scan, reproduced previously on the unchanged main commit. No dependency versions are changed here.

Special notes for your reviewer:

The file cache is shared for the same filesystem files and can remain until reclaimed. It is not private reserved memory or a persistent setting. The largest gain requires cold buffered images and enough cache headroom. Warm images pay a small extra read-pass cost.

The benchmark held the existing VAST mount configuration and 128 KiB read-ahead unchanged, with 4 CPU / 4 GiB for the agent. The PageBroker pool was fixed at 16 lanes and 32 CPU throughout this comparison. This study does not measure an additive gain over the earlier pool-versus-stock experiment.

Does this PR introduce an API change?

NONE

Additional documentation, e.g. enhancement proposals, usage docs:

CRIU images on NFS

Checklist

• Commits are signed off.
• make check test passes locally. The dependency-scan baseline failure remains.
• Documentation is updated where behavior changed.

Relationship to PageBroker staged restore

The measured workload uses PageBroker DirectRestore (the default added by #468), as confirmed by the retained broker logs. DirectRestore prepares a transaction and retains the GPU source but does not copy CPU images before CRIU.

Existing StagedRestore does pre-download: PosixCopyEngine recursively copies checkpoint files, including pages-*.img and non-page images, into PageBroker's memory-backed staging directory before CRIU. It skips the GPU payload directory, which CustomStorage still reads from the original source. For this checkpoint, full CPU staging includes 73.30 GB of CPU pages in addition to 554.49 MB of non-page images. The new helper instead prefetches only non-page images and preserves direct CPU-page reads.

The helper checks the actual filesystem type and skips tmpfs/local staging, so it does not repeat prefetch after ordinary StagedRestore. Its measured speedup applies to direct NFS image consumption. It does not accelerate the existing serial StageRestore copy itself, and this study did not compare full staged mode against direct plus prefetch.

Pending #475 routes storage-bound artifacts through StagedArtifactRestore, and #508's PVC backend delegates that copy to PosixCopyEngine. Those paths therefore already stage these images and would bypass this helper. Their end-to-end performance, staging memory requirement and preservation of the direct CPU-page path need separate qualification. #251's current head retains direct/staged selection for legacy restores. Merely making PageBroker mandatory does not imply full staging.

If CPU image preparation is consolidated into PageBroker, the useful operation for this workload is selective preparation of non-page images while CPU pages and GPU payloads remain direct. Reusing full StagedRestore unchanged is not equivalent. No such consolidation is implemented or benchmarked by this PR.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}