Use event instead of termination callback by kvega005 · Pull Request #40767 · microsoft/WSL

kvega005 · 2026-06-10T23:00:05Z

Summary of the Pull Request

Reworks how WSLC session termination is surfaced to clients. The previous design used a push-style ITerminationCallback that could only be subscribed at session-creation time (via WSLCSessionSettings), so it was unavailable when opening an existing session. This replaces it with a pull model that mirrors the process-exit-event pattern: a one-off "terminated" event plus a cached termination reason that any holder of an IWSLCSession can query — whether the session was created or opened.

PR Checklist

Closes: Link to issue #xxx
Communication: I've discussed this with core contributors already.
Tests: Added/updated if needed and all pass
Localization: All end user facing strings can be localized (no new user-facing strings)
Dev docs: Added/updated if needed
Documentation updated:

Detailed Description of the Pull Request / Additional comments

Two distinct lifecycle events on the session:

m_sessionTerminatingEvent (existing) — signaled at the start of teardown to cancel in-flight operations.
m_sessionTerminatedEvent (new) — signaled once teardown is complete ("the session is done"), via either an explicit Terminate() or an unexpected VM exit. This is the event handed to clients.

Runtime (service / per-user session):

IWSLCSession gains GetTerminationEvent (returns a duplicated, caller-owned handle to the terminated event that stays valid after the session is released) and GetTerminationReason (returns the cached reason + details; fails with ERROR_INVALID_STATE until the session has actually terminated, so callers can distinguish "still running" from "terminated for an unknown reason").
HcsVirtualMachine (service) computes the termination reason from the HCS exit status in OnExit and caches it; IWSLCVirtualMachine gains GetTerminationReason.
WSLCSession::Terminate() captures the reason once: it defaults to Shutdown for an explicit terminate (VM still alive = we shut it down), and pulls the real crash/shutdown reason from the VM when the VM exited on its own. Capture happens under the exclusive lock before the VM reference is released, and the terminated event is signaled last so any observer sees a fully torn-down session.
m_terminated bool removed — m_sessionTerminatedEvent.is_signaled() is now the single source of truth for GetState/GetTerminationReason.

SDK (wslcsdk):

Removed WslcSetSessionSettingsTerminationCallback and the ITerminationCallback/TerminationCallback plumbing (files, CMake, .def, WiX proxy/stub registration).
Added WslcGetSessionTerminationEvent and WslcGetSessionTerminationReason.
WslcSessionOptionsInternal shrank (removed callback + context fields); opaque WSLC_SESSION_OPTIONS_SIZE updated accordingly.

IDL: removed the ITerminationCallback interface and the TerminationCallback field from WSLCSessionSettings; added the new methods to IWSLCSession and IWSLCVirtualMachine.

Validation Steps Performed

Updated runtime tests: WSLCTests.cpp::TerminationEvent waits on IWSLCSession::GetTerminationEvent, verifies GetTerminationReason returns ERROR_INVALID_STATE before termination and Shutdown after an explicit Terminate().
Updated SDK tests: WslcSdkTests.cpp::TerminationEventViaTerminate and TerminationEventViaRelease wait on the SDK-returned event (including verifying the handle stays valid after the session is released) and check the reason via WslcGetSessionTerminationReason.

Copilot

Pull request overview

This PR reworks how WSLC session termination is exposed to consumers by replacing the session-creation-time push callback (ITerminationCallback) with a pull model: a one-off termination event plus a cached termination reason that can be queried by any holder of an IWSLCSession (including when opening existing sessions).

Changes:

Adds termination event + termination reason APIs to the runtime/session and service VM layers, and updates session state tracking to use the terminated event.
Updates the public SDK surface to expose WslcGetSessionTerminationEvent / WslcGetSessionTerminationReason, and removes termination-callback plumbing (code, exports, and MSI proxy/stub registration).
Updates WSLC runtime + SDK tests to validate event signaling, handle lifetime, and reason availability semantics.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/windows/WSLCTests.cpp	Replaces callback-based termination test with event + reason polling/verification.
test/windows/WslcSdkTests.cpp	Updates SDK tests to wait on the returned termination event and query termination reason.
src/windows/wslcsession/WSLCVirtualMachine.h	Adds a helper to fetch cached termination reason/details from the underlying VM.
src/windows/wslcsession/WSLCSession.h	Adds terminated event + cached termination reason/details; removes `m_terminated`.
src/windows/wslcsession/WSLCSession.cpp	Implements `GetTerminationEvent`/`GetTerminationReason`, populates cached reason during teardown, and signals terminated event at completion.
src/windows/WslcSDK/WslcsdkPrivate.h	Shrinks internal session options; removes stored termination callback COM pointer.
src/windows/WslcSDK/wslcsdk.h	Updates public SDK API: removes termination callback API, adds termination event + reason APIs, adjusts opaque options size.
src/windows/WslcSDK/wslcsdk.def	Updates exports to remove callback setter and add termination event/reason getters.
src/windows/WslcSDK/wslcsdk.cpp	Removes callback wiring during session creation; implements `WslcGetSessionTerminationEvent` and `WslcGetSessionTerminationReason`.
src/windows/WslcSDK/TerminationCallback.h	Removed (callback mechanism deleted).
src/windows/WslcSDK/TerminationCallback.cpp	Removed (callback mechanism deleted).
src/windows/WslcSDK/CMakeLists.txt	Removes TerminationCallback sources/headers from the SDK build.
src/windows/service/inc/wslc.idl	Removes `ITerminationCallback` and adds new termination event/reason methods to session + VM interfaces.
src/windows/service/exe/HcsVirtualMachine.h	Adds cached termination reason/details members and declares `GetTerminationReason`.
src/windows/service/exe/HcsVirtualMachine.cpp	Caches termination reason/details on exit before signaling the exit event; implements `GetTerminationReason`.
msipackage/package.wix.in	Removes COM registration for `ITerminationCallback` interface.

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

OneBlue

Looks like there are some build errors, but overall design LGTM

OneBlue · 2026-06-11T21:43:06Z

+    // Returns the cached termination reason and details. The values are only meaningful
+    // after the termination event has been signaled; before that the reason is
+    // WSLCVirtualMachineTerminationReasonUnknown and Details is an empty string.
+    HRESULT GetTerminationReason([out] WSLCVirtualMachineTerminationReason* Reason, [out] LPWSTR* Details);


Long term I think we should parse the Details into fields so the caller doesn't have to deal with HCS's json format.

But I think this is fine for now, since this is already a major improvement on the previous design

I started making the change, but it ends up adding a bunch of new structs and touches a lot of files, so, I think will do this in a follow up PR. I'm confident I can get it in before private preview.

… terminateEvent

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

PR #40767 (terminateEvent) removed ITerminationCallback / WSLCSessionSettings.TerminationCallback from the IDL but left the WSLCVirtualMachineFactory (introduced later by factory PR #40770, which its branch merged from master) still referencing them, so the branch did not compile. Drop the dead member and assignments; the VM now caches the reason for WSLCSession to pull. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Kevin's PR #40767 (event-model termination) moved m_vmExitEvent.SetEvent() in OnExit() to after a new std::lock_guard(m_lock) that caches the termination reason. ~HcsVirtualMachine already holds m_lock across the 5s exit-event wait and HcsCloseComputeSystem (which drains in-flight HCS callbacks). An in-flight OnExit() therefore blocks acquiring m_lock, so it never signals the exit event nor drains, and the close never completes: a hard deadlock that StuckVmTermination reliably reproduces. Drop the broad lock from the dtor. By the time the compute system is closed no further callbacks can run, so the remaining teardown is safe unguarded. Flag to Kevin to fold into #40767. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

PR #40767 (terminateEvent) removed ITerminationCallback / WSLCSessionSettings.TerminationCallback from the IDL but left the WSLCVirtualMachineFactory (introduced later by factory PR #40770, which its branch merged from master) still referencing them, so the branch did not compile. Drop the dead member and assignments; the VM now caches the reason for WSLCSession to pull. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Kevin's PR #40767 (event-model termination) moved m_vmExitEvent.SetEvent() in OnExit() to after a new std::lock_guard(m_lock) that caches the termination reason. ~HcsVirtualMachine already holds m_lock across the 5s exit-event wait and HcsCloseComputeSystem (which drains in-flight HCS callbacks). An in-flight OnExit() therefore blocks acquiring m_lock, so it never signals the exit event nor drains, and the close never completes: a hard deadlock that StuckVmTermination reliably reproduces. Drop the broad lock from the dtor. By the time the compute system is closed no further callbacks can run, so the remaining teardown is safe unguarded. Flag to Kevin to fold into #40767. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.

+    // Returns the cached termination reason and details. The values are only meaningful after the
+    // termination event has been signaled; before that the reason is
+    // WSLCVirtualMachineTerminationReasonUnknown and Details is an empty string.


Copilot

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

 interface IWSLCSession : IUnknown
 {
    HRESULT GetId([out] ULONG* Id);
    HRESULT GetState([out] WSLCSessionState* State);

+    // Returns a one-off event that is signaled when the session terminates, whether due to an
+    // explicit Terminate() call or an unexpected VM exit. The returned handle is owned by the
+    // caller and remains valid (and observes the signaled state) even after the session is released.
+    HRESULT GetTerminationEvent([out, system_handle(sh_event)] HANDLE* Event);
+
+    // Returns the cached termination reason and details. These are only available after the
+    // termination event has been signaled; before that the call fails.
+    HRESULT GetTerminationReason([out] WSLCVirtualMachineTerminationReason* Reason, [out] LPWSTR* Details);


    // Returns an event that is signaled when the VM exits (graceful or forced).
    HRESULT GetTerminationEvent([out, system_handle(sh_event)] HANDLE* Event);
+
+    // Returns the cached termination reason and details. These are only available after the
+    // termination event has been signaled; before that the call fails.
+    HRESULT GetTerminationReason([out] WSLCVirtualMachineTerminationReason* Reason, [out] LPWSTR* Details);


OneBlue · 2026-06-13T00:15:42Z

        auto session = static_cast<Session*>(context);
+
+        WslcSessionTerminationReason reason = WSLC_SESSION_TERMINATION_REASON_UNKNOWN;
+        LOG_IF_FAILED(WslcGetSessionTerminationReason(session->m_session.get(), &reason));
+
        session->m_terminatedEvent(static_cast<SessionTerminationReason>(reason));
    }


This is not true because Session's destructor will destroy m_terminationWait before releasing the session

Use event instead of termination callback

1beaebc

Copilot AI review requested due to automatic review settings June 10, 2026 23:00

Copilot started reviewing on behalf of kvega005 June 10, 2026 23:00 View session

Copilot AI reviewed Jun 10, 2026

View reviewed changes

Comment thread src/windows/wslcsession/WSLCSession.cpp

Comment thread src/windows/wslcsession/WSLCSession.cpp

Comment thread src/windows/service/inc/wslc.idl

Comment thread src/windows/service/inc/wslc.idl

kvega005 added 3 commits June 10, 2026 16:20

Fux build

c9da34e

Fix

2fb90c0

Address feedback

be6b59c

Copilot AI review requested due to automatic review settings June 10, 2026 23:43

Copilot started reviewing on behalf of kvega005 June 10, 2026 23:43 View session

Copilot AI reviewed Jun 10, 2026

View reviewed changes

Comment thread src/windows/service/inc/wslc.idl Outdated

kvega005 and others added 2 commits June 11, 2026 09:49

Merge remote-tracking branch 'origin/master' into terminateEvent

9491b63

Merge branch 'master' into terminateEvent

d45f540

Copilot AI review requested due to automatic review settings June 11, 2026 18:55

Copilot started reviewing on behalf of kvega005 June 11, 2026 18:59 View session

Copilot AI reviewed Jun 11, 2026

View reviewed changes

Comment thread src/windows/service/inc/wslc.idl Outdated

Comment thread src/windows/service/inc/wslc.idl

Comment thread src/windows/service/inc/wslc.idl Outdated

kvega005 marked this pull request as ready for review June 11, 2026 21:02

kvega005 requested a review from a team as a code owner June 11, 2026 21:02

Merge branch 'master' into terminateEvent

c6a975e

OneBlue reviewed Jun 11, 2026

View reviewed changes

kvega005 added 2 commits June 11, 2026 15:10

Address feedback.

aa4bd4b

Merge branch 'terminateEvent' of https://github.com/kvega005/WSL into…

acd9ccb

… terminateEvent

OneBlue mentioned this pull request Jun 11, 2026

Move the SDK API to its own IDL file #40784

Open

6 tasks

Copilot AI review requested due to automatic review settings June 11, 2026 23:05

Merge branch 'master' into terminateEvent

7f173d9

Copilot started reviewing on behalf of kvega005 June 11, 2026 23:06 View session

Copilot AI reviewed Jun 11, 2026

View reviewed changes

Comment thread src/windows/service/inc/wslc.idl

Comment thread src/windows/service/inc/wslc.idl Outdated

Comment thread src/windows/service/inc/wslc.idl

kvega005 and others added 2 commits June 12, 2026 11:06

Merge branch 'master' into terminateEvent

2e3d6be

Fix build

69c14fc

Copilot AI review requested due to automatic review settings June 12, 2026 21:19

Merge branch 'master' into terminateEvent

41e819f

Copilot started reviewing on behalf of kvega005 June 12, 2026 21:20 View session

Copilot AI reviewed Jun 12, 2026

View reviewed changes

kvega005 and others added 2 commits June 12, 2026 14:27

Update comments

3ff43bc

Merge branch 'master' into terminateEvent

41bc8c6

Copilot AI review requested due to automatic review settings June 12, 2026 21:56

Copilot started reviewing on behalf of kvega005 June 12, 2026 21:56 View session

Copilot AI reviewed Jun 12, 2026

View reviewed changes

OneBlue approved these changes Jun 13, 2026

View reviewed changes

Conversation

kvega005 commented Jun 10, 2026

Summary of the Pull Request

PR Checklist

Detailed Description of the Pull Request / Additional comments

Validation Steps Performed

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

OneBlue left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

OneBlue Jun 11, 2026

Choose a reason for hiding this comment

Uh oh!

kvega005 Jun 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

OneBlue Jun 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants