Design: WslcGetCLISession API for inner-loop development#40133

Draft

yeelam-gordon wants to merge 1 commit intomasterfrom

design/wslc-get-cli-session-api

yeelam-gordon commented Apr 8, 2026

Summary

Design document for the WslcGetCLISession public API in the WSLC library.

This API returns the active CLI session for the current process, enabling inner-loop development flows (build, run, debug) where a Windows application needs to interact with the container session established by the WSLC toolchain.

Key Design Decisions

STDAPI/HRESULT return type consistent with all existing WSL public APIs
Ref-counted owned handle caller gets an owned reference; WslcCloseSession() only releases the caller's ref, never the CLI session itself
Process-scoped publish-once via CAS thread-safe singleton, never replaced
#ifdef _DEBUG pattern debug builds reuse CLI session, release builds create standalone session; container lifecycle code is identical

Files Changed

doc/docs/technical-documentation/wslc-get-cli-session-api.md design document
doc/mkdocs.yml added to site navigation under WSLC API section

Review Notes

This is a design document only no implementation code. Looking for feedback on:

API surface and naming
Ownership/lifetime model
Error code allocation
Implementation file locations

Copilot AI review requested due to automatic review settings

April 8, 2026 01:47

yeelam-gordon force-pushed the design/wslc-get-cli-session-api branch from c3b264f to 64e7eca Compare

April 8, 2026 01:48

Copilot started reviewing on behalf of yeelam-gordon

April 8, 2026 01:48

yeelam-gordon force-pushed the design/wslc-get-cli-session-api branch from 64e7eca to a0130f4 Compare

April 8, 2026 01:50


          Add WslcGetCLISession API design document

Design document for the WslcGetCLISession public API in the WSLC library.
This API returns the active CLI session for the current process, primarily
for inner-loop development (build, run, debug) flows.

Key design decisions:
- STDAPI/HRESULT return type (consistent with existing WSL APIs)
- Ref-counted owned handle (safe, consistent with WslcSession lifecycle)
- Process-scoped publish-once via CAS (thread-safe singleton)
- Intentional global ref leak (reclaimed by process exit)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

yeelam-gordon force-pushed the design/wslc-get-cli-session-api branch from a0130f4 to 5020809 Compare

April 8, 2026 01:51

Copilot AI reviewed

View reviewed changes

Contributor

Copilot AI left a comment

Pull request overview

Adds documentation describing a proposed WSLC public API (WslcGetCLISession) for retrieving a process-scoped “toolchain” session to support inner-loop (build/run/debug) scenarios, and exposes it in the MkDocs site navigation.

Changes:

Added a new technical design document for the proposed WslcGetCLISession API (surface, lifetime/ownership model, error code, implementation sketch, and test strategy).
Updated MkDocs navigation to include a new “WSLC API” section pointing at the design doc.
Updated .github/copilot-instructions.md content and structure (links, build/test/debug guidance, repo navigation).

Reviewed changes

Copilot reviewed 1 out of 1 changed files in this pull request and generated 5 comments.

File	Description
`doc/mkdocs.yml`	Adds a “WSLC API” nav entry so the new design doc is discoverable on the docs site.
`doc/docs/technical-documentation/wslc-get-cli-session-api.md`	New design doc specifying the proposed API and its intended semantics/implementation approach.
`.github/copilot-instructions.md`	Restructures contributor/Copilot guidance and adds links/checklists for build/test/debug workflows.

doc/docs/technical-documentation/wslc-get-cli-session-api.md

Comment on lines +29 to +41

+              The following types are established in the WSLC public API surface and are referenced by this design:
+              ```c
+              // Opaque session handle (ref-counted)
+              typedef struct WslcSession_s* WslcSession;
+              // Standard WSLC lifecycle APIs (already exist)
+              STDAPI WslcCreateSession(_In_ const WslcSessionConfig* config, _Out_ WslcSession* session);
+              STDAPI WslcCloseSession(_In_ WslcSession session);
+              // Increment session reference count (already exists)
+              void WslcSessionAddRef(_In_ WslcSession session);
+              ```

Copilot AI Apr 8, 2026

This section states the WSLC public API types/functions “already exist”, but there are currently no Wslc* symbols in this repo (e.g., no WslcCreateSession/WslcCloseSession definitions under src/). To avoid readers assuming these are already available, either link to the existing header location or reword this block as proposed prerequisite types for the future WSLC surface.

Copilot uses AI. Check for mistakes.

doc/docs/technical-documentation/wslc-get-cli-session-api.md

Comment on lines +153 to +155

+. Stores the session in a process-global atomic pointer with release semantics.
+. Calls `AddRef` on the session (the CLI retains its own reference separately).
+. Silently ignores subsequent calls (the `std::call_once` guard ensures only the first invocation takes effect). Debug builds should assert that this function is not called more than once.

Copilot AI Apr 8, 2026

The “Internal Publication Mechanism” text says subsequent publishes are “silently ignored” via std::call_once, but the implementation sketch uses only a CAS and then assert(false) on the else-path. Please make the design intent consistent (ignore vs fail-fast) and align the described mechanism (call_once vs CAS-only).

Suggested change

      
            1. Stores the session in a process-global atomic pointer with release semantics.
          
            2. Calls `AddRef` on the session (the CLI retains its own reference separately).
          
            3. Silently ignores subsequent calls (the `std::call_once` guard ensures only the first invocation takes effect). Debug builds should assert that this function is not called more than once.
          
            1. Attempts to publish the session into a process-global atomic pointer using a compare-and-swap operation with release semantics; only the first successful call stores the pointer.
          
            2. Calls `AddRef` on the session only when publication succeeds (the CLI retains its own reference separately).
          
            3. Does not replace an already-published session. Subsequent calls are ignored after the CAS fails; debug builds should assert to catch unexpected duplicate publication attempts.

Copilot uses AI. Check for mistakes.

doc/docs/technical-documentation/wslc-get-cli-session-api.md

Comment on lines +218 to +220

		```

		> Global reference lifetime: The `AddRef` performed by `WslcPublishCLISession` is intentionally never released. The global reference is "leaked" and reclaimed by process exit. This is a deliberate design choice — there is no safe point during shutdown to release the global reference because other code may still hold derived references obtained from `WslcGetCLISession`. When the Windows app closes or is terminated, the OS reclaims all process memory including ref counts — no cleanup is needed. The session's destructor-side cleanup (e.g., closing hvsocket connections) is handled by the toolchain's own reference, which it releases during its normal shutdown path.

Copilot AI Apr 8, 2026

The “Global reference lifetime” note says the global AddRef is never released (so the session won’t be destroyed until process exit), but then claims destructor-side cleanup is handled when the toolchain releases its own reference during normal shutdown. Those two statements conflict: if the global ref remains, the destructor won’t run at toolchain shutdown. Please clarify the intended cleanup model (process-exit only vs explicit shutdown/Reset API) so implementers don’t rely on destructor cleanup that won’t happen.

Copilot uses AI. Check for mistakes.

doc/docs/technical-documentation/wslc-get-cli-session-api.md

Comment on lines +159 to +170

+              ### 6. Implementation Location
+              The new API is implemented within the WSLC library. The following files are involved:
+              | File | Action | Purpose |
+              |------|--------|---------|
+              | `src/windows/wslc/inc/wslc.h` | **Modify** | Public header — add `WslcGetCLISession` declaration and `WSLC_E_NO_CLI_SESSION` error code |
+              | `src/windows/wslc/core/cli_session.h` | **Add new** | Internal header — declare `WslcPublishCLISession` |
+              | `src/windows/wslc/core/cli_session.cpp` | **Add new** | Implementation — `g_cliSession` atomic, `WslcPublishCLISession`, `WslcGetCLISession` |
+              | `src/windows/wslc/wslc.def` | **Modify** | DLL exports — add `WslcGetCLISession` entry |
+              | `src/windows/wslc/core/session.cpp` | **Modify** | Existing session init — call `WslcPublishCLISession` after session creation |
+              | `src/windows/wslc/core/session.h` | **Reference only** | Existing session internals — understand `WslcSession_s` and `WslcSessionAddRef` |

Copilot AI Apr 8, 2026

The proposed implementation file paths reference src/windows/wslc/... and test/windows/wslc/..., but this repository snapshot doesn’t currently contain a src/windows/wslc tree. If those directories will be introduced later, consider calling that out explicitly (or link to the planned location) so the design doc doesn’t read as if it matches current repo structure.

Copilot uses AI. Check for mistakes.

doc/docs/technical-documentation/wslc-get-cli-session-api.md


		> Note: The exact file paths follow the WSLC project structure convention. The key principle is: the public declaration goes in the public header (`wslc.h`), the implementation goes in the `core/` subdirectory alongside other session management code, and the export goes in the `.def` file.

		### 5. Naming: `WslcGetCLISession`

Copilot AI Apr 8, 2026

Section numbering is out of order here ("### 6. Implementation Location" appears before "### 5. Naming"). Reordering or renumbering would make the document easier to follow and reduces confusion when referencing sections in future discussions.

Suggested change

      
            ### 5. Naming: `WslcGetCLISession`
          
            ### 7. Naming: `WslcGetCLISession`

Copilot uses AI. Check for mistakes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet