Skip to main content

hyperlight_host/sandbox/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright 2025 The Hyperlight Authors.
3
4/// Functionality for creating and configuring `Sandbox`es.
5pub mod builder;
6/// Configuration needed to establish a sandbox.
7pub mod config;
8/// Host-side file mapping preparation for `map_file_cow`.
9pub(crate) mod file_mapping;
10/// Functionality for reading, but not modifying host functions
11pub(crate) mod host_funcs;
12/// Functionality for dealing with initialized sandboxes that can
13/// call 0 or more guest functions
14mod initialized;
15/// Deprecated path for the items in the `initialized` module.
16#[deprecated(since = "0.18.0", note = "use hyperlight_host::sandbox")]
17pub mod initialized_multi_use {
18    #[allow(deprecated)]
19    pub use super::initialized::MultiUseSandbox;
20    pub use super::initialized::{PtRootFinder, Sandbox, SandboxStatus};
21}
22pub(crate) mod outb;
23/// Functionality for creating uninitialized sandboxes, manipulating them,
24/// and converting them to initialized sandboxes.
25pub mod uninitialized;
26/// Functionality for properly converting `UninitializedSandbox`es to
27/// initialized `Sandbox`es.
28pub(crate) mod uninitialized_evolve;
29
30/// Representation of a snapshot of a `Sandbox`.
31pub mod snapshot;
32
33/// Trait used by the macros to paper over the differences between hyperlight and hyperlight-wasm
34mod callable;
35
36/// Module for tracing guest execution
37#[cfg(feature = "trace_guest")]
38pub(crate) mod trace;
39
40/// Trait used by the macros to paper over the differences between hyperlight and hyperlight-wasm
41pub use callable::Callable;
42/// Re-export for `SandboxConfiguration` type
43pub use config::SandboxConfiguration;
44/// Re-export for the deprecated `MultiUseSandbox` name
45#[allow(deprecated)]
46pub use initialized::MultiUseSandbox;
47/// Re-export for the `Sandbox` type
48pub use initialized::{PtRootFinder, Sandbox, SandboxStatus};
49/// Re-export for `GuestBinary` type
50pub use uninitialized::GuestBinary;
51/// Re-export for `UninitializedSandbox` type
52pub use uninitialized::UninitializedSandbox;
53
54#[cfg(test)]
55mod tests {
56    use std::sync::Arc;
57    use std::thread;
58
59    use crossbeam_queue::ArrayQueue;
60    use hyperlight_testing::simple_guest_as_pathbuf;
61
62    use crate::sandbox::uninitialized::GuestBinary;
63    use crate::{Sandbox, UninitializedSandbox, new_error};
64
65    #[test]
66    fn check_create_and_use_sandbox_on_different_threads() {
67        let unintializedsandbox_queue = Arc::new(ArrayQueue::<UninitializedSandbox>::new(10));
68        let sandbox_queue = Arc::new(ArrayQueue::<Sandbox>::new(10));
69
70        for i in 0..10 {
71            let simple_guest_path = simple_guest_as_pathbuf();
72            let unintializedsandbox =
73                UninitializedSandbox::new(GuestBinary::FilePath(simple_guest_path), None)
74                    .unwrap_or_else(|_| panic!("Failed to create UninitializedSandbox {}", i));
75
76            unintializedsandbox_queue
77                .push(unintializedsandbox)
78                .unwrap_or_else(|_| panic!("Failed to push UninitializedSandbox {}", i));
79        }
80
81        let thread_handles = (0..10)
82            .map(|i| {
83                let uq = unintializedsandbox_queue.clone();
84                let sq = sandbox_queue.clone();
85                thread::spawn(move || {
86                    let uninitialized_sandbox = uq.pop().unwrap_or_else(|| {
87                        panic!("Failed to pop UninitializedSandbox thread {}", i)
88                    });
89                    let host_funcs = uninitialized_sandbox
90                        .host_funcs
91                        .try_lock()
92                        .map_err(|_| new_error!("Error locking"));
93
94                    assert!(host_funcs.is_ok());
95
96                    host_funcs
97                        .unwrap()
98                        .host_print(format!(
99                            "Printing from UninitializedSandbox on Thread {}\n",
100                            i
101                        ))
102                        .unwrap();
103
104                    let sandbox = uninitialized_sandbox.evolve().unwrap_or_else(|_| {
105                        panic!("Failed to initialize UninitializedSandbox thread {}", i)
106                    });
107
108                    sq.push(sandbox).unwrap_or_else(|_| {
109                        panic!("Failed to push UninitializedSandbox thread {}", i)
110                    })
111                })
112            })
113            .collect::<Vec<_>>();
114
115        for handle in thread_handles {
116            handle.join().unwrap();
117        }
118
119        let thread_handles = (0..10)
120            .map(|i| {
121                let sq = sandbox_queue.clone();
122                thread::spawn(move || {
123                    let sandbox = sq
124                        .pop()
125                        .unwrap_or_else(|| panic!("Failed to pop Sandbox thread {}", i));
126                    let host_funcs = sandbox
127                        .host_funcs
128                        .try_lock()
129                        .map_err(|_| new_error!("Error locking"));
130
131                    assert!(host_funcs.is_ok());
132
133                    host_funcs
134                        .unwrap()
135                        .host_print(format!("Print from Sandbox on Thread {}\n", i))
136                        .unwrap();
137                })
138            })
139            .collect::<Vec<_>>();
140
141        for handle in thread_handles {
142            handle.join().unwrap();
143        }
144    }
145}