Crate javm_bench 

Shared runners for the bench harness (benches/bench.rs) and the sub-VM benches (benches/sub_vm_recurse.rs, benches/sub_vm_data_recurse.rs).

The bench measures the full per-invocation lifecycle:

• Nub::put_cap_with_hash for each cap the invocation requires (Data blobs the Image references, the Image itself, the empty root cnode, the Instance). Each put is a single BTreeMap::get + refcount.fetch_add(1) after warm-up — i.e. a few tens of nanoseconds per cap.
• Nub::invoke_cached(instance_hash, endpoint, args, gas).

• run_interpreter — Nub::new_local() drives the byte-PVM interpreter (javm-exec) in-process.
• run_recompiler — the process-wide Nub::hyperlight() singleton drives the in-kernel JIT path through the same invoke_cached API.

BuiltCaps holds the pre-built Cap graph + its precomputed hashes. Construction happens once per workload at bench warm-up via BuiltCaps::for_image; the iter loop reuses the resulting handles.

Linux x86-64 only — nub pulls the Hyperlight host stack unconditionally.

Structs

BuiltCaps

Pre-built Cap graph for one (image, endpoint) bench cell.

PtCacheTop

Top instance of the page-table-cache bench: a single image whose endpoint 0 (A) derive_spawns a child of the same image once and repeatedly host_calls its echo endpoint (B).

RawRun

Raw invocation outcome for differential testing — the four InvocationResult fields with no clean-halt assertion.

SubVmTop

Top-of-recursion Cap::Instance published for a sub-VM bench.

Constants

ABORT_SENTINEL

exit_reason reported when a recompiler run aborts the VM — a guest CPU fault delivered as an unhandled IDT vector (e.g. #DE from idiv on INT_MIN/-1) surfaces as a host Err(GuestAborted), not an InvocationResult. Distinct from every real PVM2 exit reason (0..=7).

INITIAL_GAS

Default initial-gas budget for the bench.

Functions

build_pt_cache_top

Build + publish (once) the page-table-cache image and its top Instance into nub from the SSZ-encoded Image blob. Returns the top instance hash so the bench loop can invoke endpoint 0 directly.

build_sub_vm_top

Build + publish (once) the recurse Image, its cnode, and the top Instance into nub from the SSZ-encoded Image blob. Returns the top instance hash so the bench loop can invoke it directly.

hex_short

First 8 bytes of a CapHash as lowercase hex (bench logging).

invoke

Bench helper: drive one invocation through an already-locked Nub. Used inside iter_batched’s routine closure so the timed body is just the host-call round-trip + JIT path (no mutex acquire, no cap publish, no sandbox rebuild).

invoke_pt_cache

One page-table-cache bench iteration: invoke endpoint 0, which host_calls the resident B n times. Asserts a clean trampoline halt and that the summed echoes match. Returns (return_value, gas_used).

invoke_sub_vm

One sub-VM bench iteration: invoke the top instance with depth and panic unless it halted cleanly on the trampoline HostCall(0).

invoke_sub_vm_expect

Like invoke_sub_vm but also asserts the top-level return value. Used by the data-recurse correctness check to confirm each level reads its pinned RO data + writes its initial RW data correctly (not just that it halts).

invoke_sub_vm_gas

Like invoke_sub_vm but returns (return_value, gas_used) after asserting a clean trampoline halt. Used by the sub_vm_gas_parity test to check the recompiler’s category-#3 charge is identical per recursion level (gas affine in depth — a multi-frame determinism guard).

nub_hyperlight_lock

Bench-side accessor for the long-lived Hyperlight Nub. Returned guard holds the singleton mutex for the duration of one criterion iter_batched step (setup + routine).

run_interpreter

Drive built[endpoint_idx] through the PVM2 (RISC-V) interpreter via a fresh Nub::new_local() (the Local backend has no per-invocation state, so a fresh Nub each call is fine — and matches the chain’s per-event allocation model).

run_interpreter_raw

Interpreter run with no clean-halt assertion (cf. run_interpreter). The Local backend never aborts the host, so invoke_cached returns Ok in practice; an Err is still mapped to the abort sentinel for symmetry with the recompiler.

run_pt_cache_bench

Run the page-table-cache criterion bench: endpoint 0 host_calls the resident B a swept number of times. Publishes the top once (the kernel stays warm), runs an n=1/2 sanity check, then sweeps {10, 100, 1000} CALLs with Throughput::Elements(n) so the reported figure is per-CALL.

run_recompiler

Drive built[endpoint_idx] through the in-kernel JIT via the long- lived Hyperlight Nub. Warm-cache path: subsequent calls with the same Image hit the JIT compile cache. Useful for measuring steady-state execute throughput in isolation.

run_recompiler_raw

Recompiler run with no clean-halt assertion (cf. run_recompiler).

run_recurse_bench

Run the full sub-VM recurse criterion bench for blob, labelled label. Publishes the top instance once (the kernel stays warm: the JIT cache holds the compiled image, the cap cache holds the Image/Top-Instance/CNode), runs a depth-0/1 sanity check, then sweeps depths {10, 100, 1000}.

Type Aliases

NubGuard

Cloneable handle to the process-wide Hyperlight Nub.