WSL 容器 SDK 中 WslcStopContainer 的完整使用指南：从停止信号、超时语义到源码级实现-平芜编程栈

WSL 容器 SDK 中 WslcStopContainer 的完整使用指南：从停止信号、超时语义到源码级实现

【免费下载链接】WSLWindows Subsystem for Linux项目地址: https://gitcode.com/GitHub_Trending/ws/WSL

导读

WslcStopContainer是 Windows Subsystem for Linux（WSL）容器 SDK（WslcSDK）中用于停止 WSL 容器的核心 C 语言 API。它允许调用方以可控的方式向运行中的容器发送 Linux 信号（如 SIGTERM、SIGKILL），并指定超时时间，是容器生命周期管理（创建 → 启动 → 停止 → 删除）中承上启下的关键一环。读完本文，你将掌握WslcStopContainer的完整签名与参数语义、WslcSignal枚举的取值与选择策略、超时参数的隐藏细节，并通过仓库源码理解其内部调用链与错误处理机制，能够在自己的 WSL 容器管理程序中正确、安全地停止容器。

一、API 概览：签名与参数语义

WslcStopContainer的原型定义于 WslcSDK 公共头文件 src/windows/WslcSDK/wslcsdk.h，并通过 src/windows/WslcSDK/wslcsdk.def 导出为 SDK 公开符号：

STDAPI WslcStopContainer(_In_ WslcContainer container, _In_ WslcSignal signal, _In_ uint32_t timeoutSeconds, _Outptr_opt_result_z_ PWSTR* errorMessage);

参数明细

参数	类型	方向	说明
`container`	`WslcContainer`	in	要停止的容器的句柄。该句柄由`WslcCreateContainer`或`WslcOpenContainer`创建，停止操作完成后仍需调用`WslcReleaseContainer`释放
`signal`	`WslcSignal`	in	发送给容器 init 进程的信号，决定停止方式（优雅退出或强制终止），详见下文枚举说明
`timeoutSeconds`	`uint32_t`	in	等待容器停止的超时秒数；`0`表示立即超时，`WSLC_STOP_TIMEOUT_NONE`表示无限等待
`errorMessage`	`PWSTR*`	out, optional	返回失败时的详细错误消息（UTF-16 字符串），可传`NULL`忽略；返回的字符串由调用方负责通过`CoTaskMemFree`释放

返回值类型为HRESULT：成功返回S_OK，失败返回相应的错误码（如WSLC_E_CONTAINER_NOT_RUNNING或E_INVALIDARG）。

从源码结构看：WslcContainer是一个不透明句柄（在 wslcsdk.h 中通过DECLARE_HANDLE(WslcContainer)声明），调用方不应直接解引用它，所有对容器的操作都应经由 SDK API 完成。

原文档示例

原文档给出了最基本的调用形式：向容器发送SIGTERM，超时 30 秒，不接收错误消息：

HRESULT hr = WslcStopContainer( container, WSLC_SIGNAL_SIGTERM, (uint32_t)30, NULL);

二、信号枚举 WslcSignal：优雅停止与强制终止的选择

WslcSignal枚举完整定义于 src/windows/WslcSDK/wslcsdk.h，其取值与标准 POSIX 信号编号一一对应：

枚举值	数值	语义
`WSLC_SIGNAL_NONE`	0	不发信号，仅触发停止流程（与超时配合使用，见下文超时语义）
`WSLC_SIGNAL_SIGHUP`	1	SIGHUP：挂断 / 重载配置
`WSLC_SIGNAL_SIGINT`	2	SIGINT：中断（等效于 Ctrl-C）
`WSLC_SIGNAL_SIGQUIT`	3	SIGQUIT：退出并产生 core dump
`WSLC_SIGNAL_SIGKILL`	9	SIGKILL：立即强制终止，不可被捕获或忽略
`WSLC_SIGNAL_SIGTERM`	15	SIGTERM：优雅关闭（进程默认行为是退出，但可自行处理善后）

选择策略

首选WSLC_SIGNAL_SIGTERM（15）：给予容器内 init 进程优雅退出的机会，让其完成资源清理、刷盘、通知子进程等善后工作。这与原文档示例的默认选择一致。
兜底WSLC_SIGNAL_SIGKILL（9）：当容器内的进程无响应、无法优雅退出时，SIGKILL 可确保立即终止。注意 SIGKILL 无法被进程捕获，容器内的数据可能来不及落盘。
WSLC_SIGNAL_NONE（0）配合超时使用：发送任何信号，仅等待容器按自身配置的停止超时（StopTimeout）自行退出。仓库测试 test/windows/WSLCTests.cpp 展示了WslcSignalNone, 0这一组合用于验证“以 0 秒超时覆盖容器默认停止超时”的语义。

三、超时参数 timeoutSeconds 的深层语义

timeoutSeconds是uint32_t类型，其取值在仓库测试与 WinRT 封装中表现出三种语义：

0（立即超时）：不等待容器退出，立即返回。注意测试中有一条关键验证：即使容器配置了非零的默认停止超时，传入0也会覆盖默认值（见 test/windows/WSLCTests.cpp 的注释 "Validate that passing '0' as the stop timeout overrides the default"）。
WSLC_STOP_TIMEOUT_NONE（无限等待）：表示不设置超时上限，一直等待容器停止完成。测试 test/windows/WSLCTests.cpp 中通过container.Get().Stop(WSLCSignalSIGTERM, WSLC_STOP_TIMEOUT_NONE)验证了这一模式。
任意正整数（秒）：等待指定秒数后若容器仍未停止，则超时返回。

从源码结构推断：WSLC_STOP_TIMEOUT_NONE的定义可在测试文件 test/windows/WSLCTests.cpp 及 Launcher 相关实现中找到，用于区分“0 秒立即超时”与“无限等待”两种截然不同的语义——这是调用此 API 时最容易踩坑的地方，务必区分清楚。

WinRT 层的超时校验

在 WinRT 封装层 src/windows/WslcSDK/winrt/Container.cpp 中，Container::Stop先将Windows.Foundation.TimeSpan转换为秒，再进行两项前置校验：

void Container::Stop(winrt::Microsoft::WSL::Containers::Signal const& signal, TimeSpan timeout) { wil::unique_cotaskmem_string errorMessage; auto timeoutSeconds = std::chrono::duration_cast<std::chrono::seconds>(timeout).count(); if (timeoutSeconds > std::numeric_limits<uint32_t>::max()) { throw winrt::hresult_invalid_argument(L"Timeout is too large"); } if (timeoutSeconds < 0) { throw winrt::hresult_invalid_argument(L"Timeout must be non-negative"); } auto hr = WslcStopContainer(ToHandle(), static_cast<WslcSignal>(signal), static_cast<uint32_t>(timeoutSeconds), errorMessage.put()); THROW_MSG_IF_FAILED(hr, errorMessage); }

这提示我们在直接使用 C API 时也应注意：timeoutSeconds不应为负（虽然uint32_t类型本身杜绝了负值），且需保证在合理的范围内。超时语义与容器的StopTimeout 配置（容器 inspect 输出中的Config.StopTimeout字段）相互关联，测试 test/windows/WSLCTests.cpp 通过inspect.Config.StopTimeout断言了配置的生效情况。

四、源码级实现：WslcStopContainer 的内部调用链

WslcStopContainer的实现在 src/windows/WslcSDK/wslcsdk.cpp：

STDAPI WslcStopContainer(_In_ WslcContainer container, _In_ WslcSignal signal, _In_ uint32_t timeoutSeconds, _Outptr_opt_result_z_ PWSTR* errorMessage) try { ErrorInfoWrapper errorInfoWrapper{errorMessage}; auto internalType = CheckAndGetInternalType(container); RETURN_HR_IF_NULL(HRESULT_FROM_WIN32(ERROR_INVALID_STATE), internalType->container); return errorInfoWrapper.CaptureResult(internalType->container->Stop(Convert(signal), timeoutSeconds)); } CATCH_RETURN();

调用链分析

错误信息封装：ErrorInfoWrapper errorInfoWrapper{errorMessage}负责将底层失败转换为调用方可读取的 UTF-16 错误消息；若调用方传入NULL，则静默忽略错误详情。
句柄合法性校验：CheckAndGetInternalType(container)将不透明的WslcContainer句柄转换为内部对象；RETURN_HR_IF_NULL(HRESULT_FROM_WIN32(ERROR_INVALID_STATE), internalType->container)表明，当内部容器对象为空（即容器句柄无效或已释放）时，返回HRESULT_FROM_WIN32(ERROR_INVALID_STATE)，即0x800713D9。
信号转换与底层调用：Convert(signal)将 C SDK 层的WslcSignal转换为运行时内部表示，随后调用internalType->container->Stop(...)完成真正的停止动作。真正的停止逻辑（包括向 init 进程发送信号、等待退出、超时控制）封装在 WinRT 运行时的Container::Stop中，C API 是这一能力的薄封装。

与 WinRT 层的对应关系

在 WinRT 层 src/windows/WslcSDK/winrt/Container.cpp 中，Stop方法先完成超时参数的秒级转换与合法性校验（拒绝负数与超出uint32_t范围的值），再以static_cast<WslcSignal>(signal)将 WinRT 的Signal枚举（定义于 src/windows/WslcSDK/winrt/wslcsdk.idl）强制转换为 C 层枚举后调用WslcStopContainer。两套 API 使用相同的枚举数值，保证了语义一致：

enum Signal { None = 0, // No signal; reserved for future use SIGHUP = 1, // SIGHUP: reload / hangup SIGINT = 2, // SIGINT: interrupt (Ctrl-C) SIGQUIT = 3, // SIGQUIT: quit with core dump SIGKILL = 9, // SIGKILL: immediate termination SIGTERM = 15, // SIGTERM: graceful shutdown };

五、返回值与错误处理

WslcStopContainer返回HRESULT，常见返回值包括：

返回值	含义
`S_OK`	停止请求已成功处理，容器已停止（或按超时语义返回）
`WSLC_E_CONTAINER_NOT_RUNNING`	容器当前不在运行状态，无法执行停止操作
`HRESULT_FROM_WIN32(ERROR_INVALID_STATE)`	容器句柄无效或内部对象已释放（如重复释放、句柄过期）
`E_INVALIDARG`	参数非法（WinRT 层在超时值非法时会抛出`hresult_invalid_argument`）

错误消息的使用

当errorMessage非空时，失败时 SDK 会通过ErrorInfoWrapper填充一条便于诊断的 UTF-16 错误字符串（例如测试 test/windows/WSLCTests.cpp 中验证的"Container 'xxx' is not running."）。调用方使用完毕后应通过CoTaskMemFree释放该字符串。

六、仓库测试用例：行为边界的实证

测试文件 test/windows/WSLCTests.cpp 中包含大量针对Stop的用例，可直接作为该 API 行为边界的权威参考：

未运行容器不可停止（test/windows/WSLCTests.cpp）：创建后尚未启动的容器调用Stop(WSLCSignalSIGKILL, 0)返回WSLC_E_CONTAINER_NOT_RUNNING，并输出错误消息"Container 'test-container-2' is not running."。
SIGTERM 优雅停止（test/windows/WSLCTests.cpp）：对{"sleep", "99999"}这类长驻进程容器发送 SIGTERM，容器进入WslcContainerStateExited状态，且停止后可正常删除。
停止超时覆盖（test/windows/WSLCTests.cpp）：容器配置WSLC_STOP_TIMEOUT_NONE时，传入0秒超时仍可覆盖默认行为并成功停止。
超时边界组合：包括 SIGTERM 配合WSLC_STOP_TIMEOUT_NONE（test/windows/WSLCTests.cpp）、SIGKILL 配合 0 秒超时（test/windows/WSLCTests.cpp）等组合，覆盖了优雅退出、强制终止与超时三者交叉的典型场景。
对已退出容器再次 Stop 是 no-op（test/windows/WSLCTests.cpp）：已处于 Exited 状态的容器再次调用 Stop 返回成功但状态不变。

此外，test/windows/PluginTests.cpp 中的container.Get().Stop(WSLCSignalSIGKILL, 0)说明该 API 也被 WSL 插件体系（WslPluginApi.h）中的容器封装复用，进一步佐证了WslcStopContainer是停止容器的统一底层入口。

七、完整的容器生命周期示例

将WslcStopContainer放入完整的生命周期流程中，典型调用序列为：

WslcContainer container = NULL; HRESULT hr = WslcOpenContainer(session, "my-container", &container, NULL); if (FAILED(hr)) { /* 打开失败 */ } // 优雅停止：先给 SIGTERM，等待最多 30 秒 hr = WslcStopContainer(container, WSLC_SIGNAL_SIGTERM, (uint32_t)30, NULL); if (FAILED(hr)) { // 超时或失败后可升级为 SIGKILL 强制终止 hr = WslcStopContainer(container, WSLC_SIGNAL_SIGKILL, (uint32_t)10, NULL); } // 停止后查询状态确认 WslcContainerState state; if (SUCCEEDED(WslcGetContainerState(container, &state))) { // WSLC_CONTAINER_STATE_EXITED } // 释放句柄 WslcReleaseContainer(container);