Rename MultiUseSandbox to Sandbox by jprendes · Pull Request #1866 · hyperlight-dev/hyperlight

jprendes · 2026-09-30T22:23:40Z

SingleUseSandbox was removed long ago, so the "multi use" qualifier
distinguishes nothing. Sandbox is the plain name for an initialized sandbox.

Two commits:

Rename the type. MultiUseSandbox stays as a deprecated alias.
Move it out of sandbox::initialized_multi_use into the private
sandbox::initialized module. sandbox::initialized_multi_use stays as a
deprecated public facade.

Backwards compatibility

Nothing breaks. Both old paths still resolve, and both warn:

hyperlight_host::MultiUseSandbox
hyperlight_host::sandbox::initialized_multi_use

hyperlight-wasm imports MultiUseSandbox from the crate root in
wasm_sandbox.rs and loaded_wasm_sandbox.rs, and never uses the module
path. It keeps building, with a deprecation warning.

Why the module is private

Every public item in it is already re-exported one level up, so the module
path adds no API surface.

Deprecating the module in place, rather than moving the type out of it, does
not work. Module deprecation is inherited by the items defined inside it and
follows them through re-exports, so hyperlight_host::Sandbox would warn on
every use. #[allow(deprecated)] on the re-export only silences the defining
crate, not downstream callers.

Also

The component macro emits ::hyperlight_host::sandbox::Sandbox rather than
an internal module path.
test_log_trace pointed at sandbox/initialized.rs, a file that did not
exist, so it exercised the "not found" path instead of an invalid binary as
its comment claims. It now reads the crate manifest, which always exists and
is never a valid guest binary.

The "multi use" qualifier once distinguished this type from SingleUseSandbox, which no longer exists. Sandbox is the plain name for an initialized sandbox. MultiUseSandbox remains as a deprecated alias, so existing callers keep compiling and get a warning pointing at the new name. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Jorge Prendes <jorge.prendes@gmail.com>

The initialized module holds the initialized sandbox type. Sandbox, SandboxStatus and PtRootFinder are reached through hyperlight_host::Sandbox or hyperlight_host::sandbox. The module is private because every public item in it is already re-exported one level up. sandbox::initialized_multi_use stays as a deprecated facade so existing callers keep compiling. Keeping the type in a deprecated module is not an option. Module deprecation is inherited by the items defined inside it and follows them through re-exports, which would warn on every use of the canonical hyperlight_host::Sandbox path. The log tracing test pointed at sandbox/initialized.rs, a file that did not exist, so it took the "not found" path instead of testing an invalid binary as intended. It now reads the crate manifest, which always exists and is never a valid guest binary. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Jorge Prendes <jorge.prendes@gmail.com>

Copilot

Copilot review overview

🟡 Changes recommended

The legacy public module path lacks a downstream compile test for the stated compatibility guarantee.

Review effort: Balanced
Findings: 1

Open (1)

Add downstream compile test for public compatibility path · New

What changed in this PR

Renames the initialized sandbox type to Sandbox while preserving deprecated compatibility aliases and paths.

Changes:

Introduces Sandbox and deprecated MultiUseSandbox aliases.
Moves implementation into private sandbox::initialized.
Updates consumers, documentation, tests, and isolated-test paths.

File	Description
`src/hyperlight_host/tests/wit_test.rs`	Uses `Sandbox`.
`src/hyperlight_host/tests/snapshot_goldens/fixtures.rs`	Updates golden fixtures.
`src/hyperlight_host/tests/snapshot_goldens/checks.rs`	Updates golden checks.
`src/hyperlight_host/tests/integration_test.rs`	Updates integration tests.
`src/hyperlight_host/tests/common/mod.rs`	Updates test helpers.
`src/hyperlight_host/src/sandbox/uninitialized.rs`	Returns `Sandbox` and fixes invalid-binary test.
`src/hyperlight_host/src/sandbox/uninitialized_evolve.rs`	Constructs `Sandbox`.
`src/hyperlight_host/src/sandbox/snapshot/mod.rs`	Updates API documentation.
`src/hyperlight_host/src/sandbox/snapshot/file/mod.rs`	Updates snapshot example.
`src/hyperlight_host/src/sandbox/snapshot/file_tests.rs`	Migrates snapshot tests.
`src/hyperlight_host/src/sandbox/mod.rs`	Adds exports and compatibility facade.
`src/hyperlight_host/src/sandbox/initialized.rs`	Renames the primary type.
`src/hyperlight_host/src/sandbox/host_funcs.rs`	Updates constructor documentation.
`src/hyperlight_host/src/sandbox/file_mapping.rs`	Updates API link.
`src/hyperlight_host/src/sandbox/config.rs`	Updates snapshot links.
`src/hyperlight_host/src/sandbox/builder.rs`	Uses the primary type directly.
`src/hyperlight_host/src/mem/memory_region.rs`	Updates mapping documentation.
`src/hyperlight_host/src/lib.rs`	Exports `Sandbox` and deprecated alias.
`src/hyperlight_host/src/func/host_functions.rs`	Implements registration for `Sandbox`.
`src/hyperlight_host/src/error.rs`	Updates recovery links.
`src/hyperlight_host/examples/func_ctx/main.rs`	Updates example terminology.
`src/hyperlight_host/examples/crashdump/main.rs`	Updates crashdump documentation.
`src/hyperlight_host/benches/benchmarks.rs`	Migrates benchmarks.
`src/hyperlight_component_util/src/host.rs`	Emits the public `Sandbox` path.
`Justfile`	Updates isolated-test module paths.
`fuzz/fuzz_targets/host_print.rs`	Migrates fuzz state type.
`fuzz/fuzz_targets/host_call.rs`	Migrates fuzz state type.
`fuzz/fuzz_targets/guest_trace.rs`	Migrates fuzz state type.
`fuzz/fuzz_targets/guest_call.rs`	Migrates fuzz state type.
`docs/virtio-host-guest-communication.md`	Updates sandbox terminology.
`docs/msr.md`	Updates restore API name.
`docs/hyperlight-metrics-logs-and-traces.md`	Updates log-level API name.
`docs/how-to-debug-a-hyperlight-guest.md`	Updates debugging guidance.
`docs/cancellation.md`	Updates call-path terminology.
`CHANGELOG.md`	Documents the rename and compatibility paths.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Preserving hyperlight_host::sandbox::initialized_multi_use is a compatibility guarantee, so it needs a guard. An integration test compiles as a separate crate, which is the only way to prove the path is reachable from outside hyperlight_host. The in-crate test it replaces resolved the aliases through crate paths, which says nothing about what downstream users can reach. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Jorge Prendes <jorge.prendes@gmail.com>

simongdavies

a couple of minor things, otherwise LGTM

The name says what the function does. It takes an UninitializedSandbox and returns a Sandbox. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Jorge Prendes <jorge.prendes@gmail.com>

The mu prefix stood for "multi use", which the type name no longer carries. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Jorge Prendes <jorge.prendes@gmail.com>

hyperlight-gh-bot · 2026-10-01T20:23:28Z

Benchmark Results

Measured commit: 8d8147b6d5d6
Baseline commit: ff297a6a5dc3

kvm / amd (Linux) (➖ stable)

No benchmark improved or regressed.

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`779.00 ns` (➖ 1.00x slower)
`vec_bytes`	`608.14 ns` (➖ 1.04x slower)
		`374.47 µs` (➖ 1.00x slower)

payload_allocation

	`slot_pool_segmented`
`262144`	`524.64 ns` (➖ 1.01x slower)
`65536`	`142.19 ns` (➖ 1.01x slower)

sandboxes

	`create_initialized_and_drop`
`medium`	`78.80 ms` (➖ 1.01x slower)

slot_pool

	`alloc_dealloc_1500`	`alloc_dealloc_4096`	`alloc_dealloc_128`
	`7.80 ns` (➖ 1.01x slower)	`7.73 ns` (➖ 1.00x faster)	`8.13 ns` (➖ 1.05x slower)

snapshot_files

	`load_snapshot_unverified`
`small`	`92.25 µs` (➖ 1.01x slower)

virtq_readonly

	`slot_pool_segmented_fragmented`	`slot_pool_segmented`
`262144`	`7.15 µs` (➖ 1.07x faster)	`7.29 µs` (➖ 1.00x slower)
`65536`	`2.10 µs` (➖ 1.01x slower)	`1.95 µs` (➖ 1.01x slower)

virtq_readwrite

	`slot_pool_segmented_fragmented`	`slot_pool_segmented`
`65536`	`6.22 µs` (➖ 1.00x faster)	`6.20 µs` (➖ 1.00x faster)
`8192`	`1.05 µs` (➖ 1.00x faster)	`1.07 µs` (➖ 1.02x faster)
`262144`		`27.14 µs` (➖ 1.01x slower)

kvm / intel (Linux) (➖ stable)

No benchmark improved or regressed.

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`792.21 ns` (➖ 1.12x slower)
`vec_bytes`	`599.45 ns` (➖ 1.13x slower)
		`737.67 µs` (➖ 1.08x slower)

payload_allocation

	`slot_pool_segmented`
`262144`	`571.97 ns` (➖ 1.13x slower)
`65536`	`154.12 ns` (➖ 1.13x slower)

sandboxes

	`create_initialized_and_drop`
`medium`	`82.25 ms` (➖ 1.05x slower)

slot_pool

	`alloc_dealloc_1500`	`alloc_dealloc_4096`	`alloc_dealloc_128`
	`7.78 ns` (➖ 1.12x slower)	`7.79 ns` (➖ 1.13x slower)	`7.81 ns` (➖ 1.13x slower)

snapshot_files

	`load_snapshot_unverified`
`small`	`50.49 µs` (➖ 1.12x slower)

virtq_readonly

	`slot_pool_segmented_fragmented`	`slot_pool_segmented`
`262144`	`8.54 µs` (➖ 1.13x slower)	`8.56 µs` (➖ 1.13x slower)
`65536`	`2.40 µs` (➖ 1.12x slower)	`2.43 µs` (➖ 1.13x slower)

virtq_readwrite

	`slot_pool_segmented_fragmented`	`slot_pool_segmented`
`65536`	`8.12 µs` (➖ 1.16x slower)	`8.02 µs` (➖ 1.14x slower)
`8192`	`852.30 ns` (➖ 1.14x slower)	`829.57 ns` (➖ 1.13x slower)
`262144`		`33.27 µs` (➖ 1.12x slower)

mshv3 / amd (Linux) (➖ stable)

No benchmark improved or regressed.

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`919.62 ns` (➖ 1.04x faster)
`vec_bytes`	`711.84 ns` (➖ 1.02x slower)
		`325.44 µs` (➖ 1.07x slower)

payload_allocation

	`slot_pool_segmented`
`262144`	`751.66 ns` (➖ 1.05x slower)
`65536`	`194.29 ns` (➖ 1.01x faster)

sandboxes

	`create_initialized_and_drop`
`medium`	`59.40 ms` (➖ 1.07x slower)

slot_pool

	`alloc_dealloc_1500`	`alloc_dealloc_4096`	`alloc_dealloc_128`
	`10.27 ns` (➖ 1.07x slower)	`10.95 ns` (➖ 1.11x slower)	`10.16 ns` (➖ 1.05x slower)

snapshot_files

	`load_snapshot_unverified`
`small`	`86.05 µs` (➖ 1.04x slower)

virtq_readonly

	`slot_pool_segmented_fragmented`	`slot_pool_segmented`
`262144`	`9.65 µs` (➖ 1.03x slower)	`8.96 µs` (➖ 1.05x faster)
`65536`	`2.25 µs` (➖ 1.08x faster)	`2.46 µs` (➖ 1.02x slower)

virtq_readwrite

	`slot_pool_segmented_fragmented`	`slot_pool_segmented`
`65536`	`8.05 µs` (➖ 1.05x faster)	`8.36 µs` (➖ 1.22x faster)
`8192`	`1.27 µs` (➖ 1.04x faster)	`1.36 µs` (➖ 1.11x slower)
`262144`		`36.77 µs` (➖ 1.01x faster)

mshv3 / intel (Linux) (➖ stable)

No benchmark improved or regressed.

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`933.48 ns` (➖ 1.01x slower)
`vec_bytes`	`662.10 ns` (➖ 1.00x slower)
		`767.17 µs` (➖ 1.02x slower)

payload_allocation

	`slot_pool_segmented`
`262144`	`642.06 ns` (➖ 1.00x faster)
`65536`	`165.83 ns` (➖ 1.01x faster)

sandboxes

	`create_initialized_and_drop`
`medium`	`74.24 ms` (➖ 1.09x slower)

slot_pool

	`alloc_dealloc_1500`	`alloc_dealloc_4096`	`alloc_dealloc_128`
	`8.85 ns` (➖ 1.13x faster)	`8.79 ns` (➖ 1.00x slower)	`8.81 ns` (➖ 1.00x slower)

snapshot_files

	`load_snapshot_unverified`
`small`	`45.72 µs` (➖ 1.04x faster)

virtq_readonly

	`slot_pool_segmented_fragmented`	`slot_pool_segmented`
`262144`	`7.85 µs` (➖ 1.00x slower)	`7.88 µs` (➖ 1.01x slower)
`65536`	`2.26 µs` (➖ 1.00x slower)	`2.32 µs` (➖ 1.01x slower)

virtq_readwrite

	`slot_pool_segmented_fragmented`	`slot_pool_segmented`
`65536`	`7.57 µs` (➖ 1.01x faster)	`7.66 µs` (➖ 1.01x faster)
`8192`	`877.87 ns` (➖ 1.03x slower)	`890.74 ns` (➖ 1.02x slower)
`262144`		`36.19 µs` (➖ 1.03x faster)

hyperv-ws2025 / amd (Windows) (➖ stable)

No benchmark improved or regressed.

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`1.30 µs` (➖ 1.13x slower)
`vec_bytes`	`808.21 ns` (➖ 1.10x slower)
		`2.20 ms` (➖ 1.12x faster)

payload_allocation

	`slot_pool_segmented`
`262144`	`789.65 ns` (➖ 1.04x faster)
`65536`	`268.22 ns` (➖ 1.18x slower)

sandboxes

	`create_initialized_and_drop`
`medium`	`108.38 ms` (➖ 1.05x slower)

slot_pool

	`alloc_dealloc_1500`	`alloc_dealloc_4096`	`alloc_dealloc_128`
	`9.96 ns` (➖ 1.07x faster)	`10.11 ns` (➖ 1.01x faster)	`10.12 ns` (➖ 1.00x faster)

snapshot_files

	`load_snapshot_unverified`
`small`	`719.63 µs` (➖ 1.25x faster)

virtq_readonly

	`slot_pool_segmented_fragmented`	`slot_pool_segmented`
`262144`	`9.09 µs` (➖ 1.09x faster)	`9.10 µs` (➖ 1.07x faster)
`65536`	`2.37 µs` (➖ 1.01x faster)	`2.43 µs` (➖ 1.00x slower)

virtq_readwrite

	`slot_pool_segmented_fragmented`	`slot_pool_segmented`
`65536`	`9.23 µs` (➖ 1.06x faster)	`8.91 µs` (➖ 1.03x faster)
`8192`	`1.31 µs` (➖ 1.01x slower)	`1.29 µs` (➖ 1.01x faster)
`262144`		`52.02 µs` (➖ 1.33x slower)

hyperv-ws2025 / intel (Windows) (➖ stable)

No benchmark improved or regressed.

Benchmark Results

function_call_codec

	`encode_control`	`decode_vec_bytes_copy`
`byte_chunks`	`1.22 µs` (➖ 1.12x faster)
`vec_bytes`	`803.61 ns` (➖ 1.06x slower)
		`3.31 ms` (➖ 1.11x slower)

payload_allocation

	`slot_pool_segmented`
`262144`	`755.43 ns` (➖ 1.01x slower)
`65536`	`211.30 ns` (➖ 1.01x slower)

sandboxes

	`create_initialized_and_drop`
`medium`	`124.63 ms` (➖ 1.10x slower)

slot_pool

	`alloc_dealloc_1500`	`alloc_dealloc_4096`	`alloc_dealloc_128`
	`10.17 ns` (➖ 1.02x slower)	`10.08 ns` (➖ 1.04x faster)	`10.70 ns` (➖ 1.03x slower)

snapshot_files

	`load_snapshot_unverified`
`small`	`613.91 µs` (➖ 1.07x slower)

virtq_readonly

	`slot_pool_segmented_fragmented`	`slot_pool_segmented`
`262144`	`7.77 µs` (➖ 1.03x slower)	`7.59 µs` (➖ 1.03x faster)
`65536`	`2.39 µs` (➖ 1.06x slower)	`2.28 µs` (➖ 1.02x faster)

virtq_readwrite

	`slot_pool_segmented_fragmented`	`slot_pool_segmented`
`65536`	`8.56 µs` (➖ 1.01x faster)	`8.56 µs` (➖ 1.01x faster)
`8192`	`1.15 µs` (➖ 1.10x faster)	`1.21 µs` (➖ 1.08x slower)
`262144`		`58.83 µs` (➖ 1.39x slower)

_{Reported by cargo ci bench-report --candidate run:36889370315 --baseline run:36796040416 --config-file bench_report.toml.}

Copilot AI balanced review requested due to automatic review settings September 30, 2026 22:23

jprendes requested review from andreiltd, danbugs, dblnz, devigned, jsturtevant, ludfjig, simongdavies, squillace and syntactically as code owners September 30, 2026 22:23

jprendes added kind/refactor For PRs that restructure or remove code without adding new functionality. area/API Related to the API or public interface ready-for-review PR is ready for (re-)review labels Sep 30, 2026

Copilot started reviewing on behalf of jprendes September 30, 2026 22:27 View session

jprendes force-pushed the rename-multi-use-sandbox branch from fc66057 to 97ea8d9 Compare September 30, 2026 22:28

Copilot AI reviewed Sep 30, 2026

View reviewed changes

Comment thread src/hyperlight_host/src/sandbox/mod.rs

This comment has been minimized.

Sign in to view

simongdavies previously approved these changes Oct 1, 2026

View reviewed changes

Comment thread src/hyperlight_host/src/sandbox/uninitialized.rs

Comment thread src/hyperlight_host/src/sandbox/uninitialized_evolve.rs Outdated

Comment thread fuzz/fuzz_targets/host_call.rs Outdated

Rename evolve_impl_multi_use to initialize_sandbox

376235c

The name says what the function does. It takes an UninitializedSandbox and returns a Sandbox. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Jorge Prendes <jorge.prendes@gmail.com>

jprendes dismissed simongdavies’s stale review via 376235c October 1, 2026 16:02

Rename mu_sbox to sandbox in the fuzz targets

8d8147b

The mu prefix stood for "multi use", which the type name no longer carries. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Jorge Prendes <jorge.prendes@gmail.com>

simongdavies approved these changes Oct 1, 2026

View reviewed changes

jprendes merged commit c7e9ad9 into hyperlight-dev:main Oct 1, 2026
108 of 111 checks passed

github-actions Bot removed the ready-for-review PR is ready for (re-)review label Oct 1, 2026

Conversation

jprendes commented Sep 30, 2026

Backwards compatibility

Why the module is private

Also

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

This comment has been minimized.

This comment has been minimized.

simongdavies left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hyperlight-gh-bot Bot commented Oct 1, 2026

Benchmark Results

Benchmark Results

function_call_codec

payload_allocation

sandboxes

slot_pool

snapshot_files

virtq_readonly

virtq_readwrite

Benchmark Results

function_call_codec

payload_allocation

sandboxes

slot_pool

snapshot_files

virtq_readonly

virtq_readwrite

Benchmark Results

function_call_codec

payload_allocation

sandboxes

slot_pool

snapshot_files

virtq_readonly

virtq_readwrite

Benchmark Results

function_call_codec

payload_allocation

sandboxes

slot_pool

snapshot_files

virtq_readonly

virtq_readwrite

Benchmark Results

function_call_codec

payload_allocation

sandboxes

slot_pool

snapshot_files

virtq_readonly

virtq_readwrite

Benchmark Results

function_call_codec

payload_allocation

sandboxes

slot_pool

snapshot_files

virtq_readonly

virtq_readwrite

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants