Restore boolean return value from InterruptHandle::kill() with improved docs

Based on feedback, restored the boolean return value for kill() but updated
the documentation to clarify what it means:
- The boolean indicates whether a signal was sent, not whether cancellation succeeded
- On Linux: true if signal was sent to vCPU thread, false if vCPU not running
- On Windows: true if WHvCancelRunVirtualProcessor called successfully, false otherwise
- A false return doesn't mean failure - the cancellation flag is always set

Restored all test assertions that were checking the return value.

Co-authored-by: jsturtevant <[email protected]>

Author: Copilot

docs/cancellation.md

@@ -166,6 +166,7 @@ sequenceDiagram
     end
     
     deactivate IH
+    IH-->>Caller: sent_signal
     deactivate IH
 ```
 

src/hyperlight_host/benches/benchmarks.rs

@@ -245,7 +245,7 @@ fn bench_guest_call_interrupt_latency(b: &mut criterion::Bencher, size: SandboxS
                 // Small delay to ensure the guest function is running in VM before interrupting
                 thread::sleep(std::time::Duration::from_millis(10));
                 let kill_start = Instant::now();
-                interrupt_handle.kill();
+                assert!(interrupt_handle.kill());
                 kill_start
             });
 

src/hyperlight_host/src/hypervisor/mod.rs

@@ -209,18 +209,20 @@ pub trait InterruptHandle: Send + Sync + Debug {
     /// Interrupt the corresponding sandbox from running.
     ///
     /// This method sets a cancellation flag that prevents or stops the execution of guest code.
-    /// The effectiveness of this call depends on timing relative to the guest function call lifecycle:
     ///
-    /// - **Before guest call starts** (before `clear_cancel()` in `MultiUseSandbox::call()`):
-    ///   The cancellation request will be cleared and ignored.
-    /// - **After guest call starts but before entering guest code** (after `clear_cancel()`, before `run_vcpu()`):
-    ///   Will prevent the guest from executing.
-    /// - **While executing guest code**: Will interrupt the vCPU.
-    /// - **After guest call completes**: Has no effect (cancellation is cleared at the start of the next call).
+    /// # Return Value
+    ///
+    /// The return value indicates whether a signal was sent to interrupt a running vCPU:
+    /// - On Linux: Returns `true` if a signal was sent to the vCPU thread, `false` if the vCPU was not running.
+    /// - On Windows: Returns `true` if `WHvCancelRunVirtualProcessor` was called successfully, `false` otherwise.
+    ///
+    /// **Important**: A return value of `false` does not mean the cancellation failed. The cancellation flag is
+    /// always set, which will prevent or stop execution. A `false` return simply means no signal was sent because
+    /// the vCPU was not actively running at that moment.
     ///
     /// # Note
     /// This function will block for the duration of the time it takes for the vcpu thread to be interrupted.
-    fn kill(&self);
+    fn kill(&self) -> bool;
 
     /// Used by a debugger to interrupt the corresponding sandbox from running.
     ///
@@ -381,13 +383,13 @@ impl InterruptHandleImpl for LinuxInterruptHandle {
 
 #[cfg(any(kvm, mshv3))]
 impl InterruptHandle for LinuxInterruptHandle {
-    fn kill(&self) {
+    fn kill(&self) -> bool {
         // Release ordering ensures that any writes before kill() are visible to the vcpu thread
         // when it checks is_cancelled() with Acquire ordering
         self.state.fetch_or(Self::CANCEL_BIT, Ordering::Release);
 
         // Send signals to interrupt the vcpu if it's currently running
-        self.send_signal();
+        self.send_signal()
     }
 
     #[cfg(gdb)]
@@ -520,7 +522,7 @@ impl InterruptHandleImpl for WindowsInterruptHandle {
 
 #[cfg(target_os = "windows")]
 impl InterruptHandle for WindowsInterruptHandle {
-    fn kill(&self) {
+    fn kill(&self) -> bool {
         use windows::Win32::System::Hypervisor::WHvCancelRunVirtualProcessor;
 
         // Release ordering ensures that any writes before kill() are visible to the vcpu thread
@@ -531,7 +533,7 @@ impl InterruptHandle for WindowsInterruptHandle {
         // This ensures we see the running state set by the vcpu thread
         let state = self.state.load(Ordering::Acquire);
         if state & Self::RUNNING_BIT == 0 {
-            return;
+            return false;
         }
 
         // Take read lock to prevent race with WHvDeletePartition in set_dropped().
@@ -541,19 +543,23 @@ impl InterruptHandle for WindowsInterruptHandle {
             Ok(guard) => guard,
             Err(e) => {
                 log::error!("Failed to acquire partition_state read lock: {}", e);
-                return;
+                return false;
             }
         };
 
         if guard.dropped {
-            return;
+            return false;
         }
 
         unsafe {
-            if let Err(e) = WHvCancelRunVirtualProcessor(guard.handle, 0, 0) {
-                log::error!("Failed to cancel running virtual processor: {}", e);
+            match WHvCancelRunVirtualProcessor(guard.handle, 0, 0) {
+                Ok(_) => true,
+                Err(e) => {
+                    log::error!("Failed to cancel running virtual processor: {}", e);
+                    false
+                }
             }
-        };
+        }
     }
     #[cfg(gdb)]
     fn kill_from_debugger(&self) -> bool {

src/hyperlight_host/src/metrics/mod.rs

@@ -118,7 +118,7 @@ mod tests {
             // interrupt the guest function call to "Spin" after 1 second
             let thread = thread::spawn(move || {
                 thread::sleep(Duration::from_secs(1));
-                interrupt_handle.kill();
+                assert!(interrupt_handle.kill());
             });
 
             multi

src/hyperlight_host/tests/integration_test.rs

@@ -87,7 +87,7 @@ fn interrupt_in_progress_guest_call() {
     // kill vm after 1 second
     let thread = thread::spawn(move || {
         thread::sleep(Duration::from_secs(1));
-        interrupt_handle.kill();
+        assert!(interrupt_handle.kill());
         barrier2.wait(); // wait here until main thread has returned from the interrupted guest call
         barrier2.wait(); // wait here until main thread has dropped the sandbox
         assert!(interrupt_handle.dropped());
@@ -122,7 +122,7 @@ fn interrupt_guest_call_in_advance() {
 
     // kill vm before the guest call has started
     let thread = thread::spawn(move || {
-        interrupt_handle.kill();
+        assert!(!interrupt_handle.kill()); // should return false since vcpu is not running yet
         barrier2.wait();
         barrier2.wait(); // wait here until main thread has dropped the sandbox
         assert!(interrupt_handle.dropped());
@@ -274,9 +274,10 @@ fn interrupt_moved_sandbox() {
     let thread2 = thread::spawn(move || {
         barrier.wait();
         thread::sleep(Duration::from_secs(1));
-        interrupt_handle.kill();
+        assert!(interrupt_handle.kill());
 
-        interrupt_handle2.kill();
+        // make sure this returns true, which means the sandbox wasn't killed incorrectly before
+        assert!(interrupt_handle2.kill());
     });
 
     let res = sbox2.call::<i32>("Spin", ()).unwrap_err();