Skip to content

Improve InterruptHandle::kill() documentation and clarify boolean return value #1121

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Copilot wants to merge 10 commits into from
Closed

Improve InterruptHandle::kill() documentation and clarify boolean return value #1121

Changes from 9 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
f936bc0
Initial plan
Copilot Dec 16, 2025
c34ddfa
Remove misleading boolean return from InterruptHandle::kill()
Copilot Dec 16, 2025
c8e471e
Add error logging for WHvCancelRunVirtualProcessor failure
Copilot Dec 16, 2025
5350a8c
Update kill() documentation to accurately describe timing behavior
Copilot Dec 16, 2025
ad4591d
Make tracing-tracy optional to fix gdb test build failures
Copilot Dec 16, 2025
0daa0fd
Restore boolean return value from InterruptHandle::kill() with improv…
Copilot Dec 18, 2025
21cdb54
Improve unsafe block scope in Windows kill() implementation
Copilot Dec 18, 2025
28890e7
Revert Cargo.toml changes to tracing-tracy
Copilot Dec 18, 2025
8b7a60c
Remove error logging for WHvCancelRunVirtualProcessor failure
Copilot Dec 18, 2025
533f3a8
Improve kill() documentation with clearer structure
Copilot Dec 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions src/hyperlight_host/src/hypervisor/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -208,8 +208,17 @@ pub(crate) trait InterruptHandleImpl: InterruptHandle {
pub trait InterruptHandle: Send + Sync + Debug {
/// Interrupt the corresponding sandbox from running.
///
/// - If this is called while the the sandbox currently executing a guest function call, it will interrupt the sandbox and return `true`.
/// - If this is called while the sandbox is not running (for example before or after calling a guest function), it will do nothing and return `false`.
/// This method sets a cancellation flag that prevents or stops the execution of guest code.
///
/// # 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.

@ludfjig ludfjig Dec 18, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think something like

/// Cancel guest execution in the corresponding sandbox.
///
/// If a guest call is in progress, it will be cancelled and the guest function call
/// will return an error. If called before a guest call is made, it has no effect on
/// future guest calls.
///
/// # Returns
/// - `true` if a guest call was in progress and the vcpu was actively running.
/// - `false` otherwise (no guest call in progress, or guest call in progress but vcpu
///   not yet running). Any in-progress guest call will still be cancelled.
///
/// # Platform behavior
/// - **Linux**: If the vcpu is running, this function will block for the duration of
///   the time it takes for the vcpu thread to be interrupted.
/// - **Windows**: This function returns immediately after requesting cancellation.
fn kill(&self) -> bool;

would be better @copilot

Copilot AI Dec 18, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated the documentation in commit 533f3a8. The new format is clearer and more user-focused, with separate sections for the return value and platform-specific behavior.

///
/// # Note
/// This function will block for the duration of the time it takes for the vcpu thread to be interrupted.
Expand Down