process

快速开始

直接执行不会经过 Shell。只有命令明确需要管道、重定向、变量展开或 Shell 内建语法时，才使用 xrtProcessShellConfigInit()。

使用默认程序打开

启用 process_open 后，xrtProcessOpen() 请求操作系统使用默认关联程序打开文件路径或 URI：

Windows 使用 Shell 关联处理器，macOS 使用 /usr/bin/open，其他 POSIX 平台直接执行 xdg-open。目标始终作为独立参数传递，不经过命令解释器，因此不需要也不允许调用方自行拼接 shell 转义。

返回 true 只表示系统已经接受打开请求。关联程序可能复用已有进程，POSIX 桌面启动器也可能稍后失败，所以该入口不会伪造可等待的 xprocess 或“界面已经显示”的结果。空目标、非法 UTF-8、缺少桌面启动器和系统关联失败都进入 xrt.process 域的 XPROCESS_ERROR_OPEN。

配置

xrtProcessConfigInit() 设置以下默认值：

• Target = XPROCESS_EXEC
• 继承当前环境
• 创建独立进程组
• 三个标准流都继承
• Terminal 默认尺寸为 120 x 30

Args 不包含 argv[0]，每项都是独立零结尾 UTF-8 字符串。Arg0 为空时使用 Program。全部配置数据只需存活到 xrtProcessSpawn() 返回。

环境使用 xprocessenv 的 Name/Value 表达。Value 为空指针表示删除变量，指向空字符串表示保留变量但设置空值；重复名称采用最后一项。

标准流

PIPE stdin 使用 xrtProcessWrite()，写完后必须用 xrtProcessClose(..., XPROCESS_STDIN) 发送 EOF。stdout 和 stderr 使用 xrtProcessRead()；返回零表示 EOF，负数表示结构化错误。

启用 process_file 后，xrtProcessFile() 把借用的 xfile 映射为 HANDLE 配置。Spawn 在返回前复制底层句柄，不接管原文件；因此 Spawn 成功后调用方可以立即关闭文件，子进程仍持有自己的副本。

没有原生句柄的 VFS backend 返回无效 HANDLE，并保留 File 的原始错误 （例如 Unsupported 或构造错误时的 Memory），不覆盖成进程参数错误。 NULL 文件仍返回 XPROCESS_ERROR_ARGUMENT。该函数只取得借用能力，不复制 句柄、不延长文件寿命；配置到 Spawn 之前文件必须保持有效。

Process 核心不缓存输出。需要并发排空和有界结果时选择 process_run，不要在子进程可能同时大量写 stdout/stderr 时顺序读两个流。

Terminal

启用 process_terminal 后，把 Terminal 设为 true 即可使用 Windows ConPTY 或 POSIX PTY。Columns 与 Rows 的有效范围都是 1 到 32767；运行中使用 xrtProcessResize() 修改尺寸。启动前可用 xrtProcessTerminalSupported() 探测当前系统运行时能力。

Terminal 会取代三项标准流配置：父端通过 stdin 写入，通过 stdout 读取终端的统一字节流；子进程 stderr 也进入该字节流，因此 xrtProcessStreamNative(..., XPROCESS_STDERR) 返回 -1。终端输出可能包含输入回显、平台换行和程序产生的控制序列，调用方应按终端流而不是普通 stdout 文本处理。

POSIX PTY 的读端和写端共享同一个 master。普通 xrtProcessClose() 只关闭父端写描述符， 不等于向规范模式终端发送 EOF；手动交互程序应写入 EOT、发送退出命令或明确停止进程。 xrtProcessRun() 是有限输入的一次性路径，会在输入末尾补充平台规范终端 EOF 序列； Windows 的 Ctrl-Z 必须位于新行起点，因此未以换行结束的输入会先补一个终端换行。 原始/非 processed 输入模式可能把控制字符作为普通输入，程序此时应使用退出命令或 普通管道。使用 Terminal 时 stderr 合并进 Result.Stdout，Result.Stderr 为空。

一次性运行

xrtProcessRun() 同时写入可选 stdin、并发排空 stdout/stderr、等待退出并返回有界结果。默认每个输出流最多保留 16 MiB；达到上限时可选择失败、保留开头或保留结尾。

xprocessresult.InputWritten 表示 stdin 在子进程提前关闭前实际写入的字节数。基础设施成功与退出码为零是两个概念：xrtProcessRun() 的 true 只表示运行与收口成功，使用 xrtProcessResultSuccess() 判断正常零退出。

xrtProcessWaitForCancel() 在进程退出、绝对 Deadline 或取消令牌中等待第一个事件；进程退出与取消同时可见时，退出优先。超时与取消不会由该等待函数隐式停止进程。

Pipeline

xrtProcessPipeline() 先创建 N - 1 条真实 OS pipe，再启动全部阶段。中间数据不经过父进程完整缓存，天然保留流式传输和内核背压；只捕获末段 stdout。

每个 xprocessstageresult 独立拥有对应阶段的 stderr 与退出状态，不会把多个工具的诊断文本混成无法定位的一块。xprocesspipelineoutputproc 同时收到阶段索引和流标识；回调可能由多个输出线程并发调用。

xprocesspipelineoptions 的 Input 只写入首段，Deadline 与 Cancel 对全部阶段共享。捕获上限分别应用于末段 stdout 和每一段 stderr。调用结束后使用 xrtProcessPipelineResultUnit() 释放全部结果。

Pipeline 是同步捕获器：返回前收口输入/输出泵以及各阶段的私有 waiter， 不会留下尚在释放进程引用和线程上下文的退役尾部。基础 xrtProcessWait() 仍只等待终态发布，不具备该额外保证。部分启动、分配 失败和停止清理保留首个基础设施错误，不复制并覆盖该错误；失败的 setup 不获取或关闭无关父进程描述符。所有返回路径仍需调用结果 Unit。

等待与状态

• xrtProcessWait()：无限等待。
• xrtProcessWaitFor()：相对毫秒数。
• xrtProcessWaitFor()：绝对单调 Deadline。
• xrtProcessStatus()：成功等待后复制不可变状态。

超时不会自动杀死进程。调用方可以继续等待，或依次调用 Interrupt、Terminate、KillTree。发送请求和观察退出是两个独立步骤。

xprocessstatus 的 Kind 区分退出码、POSIX 信号和平台等待失败。Stop 保存 XRT 成功发出的最高停止强度。

xrtProcessWaitAsync() 返回每个 Process 唯一的共享 Future。Future 成功值是由 Future 自身拥有的只读 xprocessstatus 快照，因此调用方可以先释放 Process，再等待或读取结果。平台等待失败时 Future 进入失败终态并保留同一结构化错误。

对该共享 Future 请求取消不会隐式停止进程，也不会替其他观察者伪造取消终态；需要停止子进程时应明确调用 Process 停止 API。启用 future_coroutine 后，同一个 Future 可以直接由 xrtFutureAwait() 等待。

生命周期

Process 使用引用计数。xrtProcessDestroy() 可以在进程运行时调用；最后一个调用方引用会关闭父端管道，内部等待引用继续回收进程。此操作不会隐式杀死子进程。

多个线程可以等待同一对象。每个输出流只允许一个并发读取者，stdin 只允许一个并发写入者；不要在 I/O 进行时从其他线程关闭同一管道。

公共类型索引

状态与策略常量

xprocessstate：

xprocessexitkind：

xprocessstop：

xprocessoverflow：

XPROCESS_CAPTURE_LIMIT_DEFAULT 为 stdout 和 stderr 分别设置 16 MiB 默认捕获上限。XPROCESS_STDOUT 是 stdout 流标识；另外两项流标识 XPROCESS_STDIN 与 XPROCESS_STDERR 的读写限制见“标准流”。

辅助函数索引