subprocess

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

提供 pkg/subprocess 的本地实现:os/exec 驱动 + 进程树终止 + 环境 scrub + spill。

平台相关实现(*nix):进程组设置、信号收集、进程组信号投递。

Package subprocess 提供子进程(Subprocess)接缝。

对齐上游:packages/subprocess/subprocess + subprocess-local

本文件对应任务 M36:Subprocess 接缝。

设计要点:

  • SubprocessSpawnSpec 完全显式、不自带默认(argv/cwd/stdio/grace/env 全部给全);
  • 托管 OMNIX_* 环境命名空间:spawn 时先 scrubbedParentEnv() 丢弃环境中的 OMNIX_* 名, 再把调用方显式 env 合并上去(缺失的普通环境项也可用 tombstone 移除);
  • CollectedOutput 报告每个流的截断与 spill 恢复状态:超过 maxBytes 保留 TAIL, 并可在 spill 开启时把完整流写入 spill 文件;
  • 结束只在进程树上生效:terminate() 是唯一终止动词,树作用域;Windows 用 taskkill /T,*nix 用 SIGTERM → grace → SIGKILL;子进程树全部清理无残留。

Index

Constants

View Source
const OmnixEnvPrefix = "OMNIX_"

OmnixEnvPrefix 是 omnix 托管环境变量前缀;实现会先丢弃环境中的该前缀名称。

Variables

This section is empty.

Functions

func ScrubParentEnv

func ScrubParentEnv() []string

ScrubParentEnv 丢弃环境中所有 OMNIX_* 名,返回 Scala 兼容的环境骨架(含原样其它项)。

Types

type CollectedOutput

type CollectedOutput struct {
	// Text 已收集文本——截断时为流的 TAIL。
	Text string `json:"text"`
	// Truncated 是否从 Text 中丢弃过字节。
	Truncated bool `json:"truncated"`
	// SpillPath 当截断且可用时,含完整流的文件路径。
	SpillPath string `json:"spillPath,omitempty"`
}

CollectedOutput 是一条已捕获流的文本 + 恢复信息。

type LocalRuntime

type LocalRuntime struct{}

LocalRuntime 是本地子进程运行时(os/exec)。

func NewLocal

func NewLocal() *LocalRuntime

NewLocal 创建本地运行时。

func (*LocalRuntime) Spawn

Spawn 按 spec 启动一个受管理子进程并立即返回句柄。

type SubprocessCollect

type SubprocessCollect struct {
	// MaxBytes 内存上限/字节;溢出保留 TAIL。
	MaxBytes int
	// SpillMaxBytes 完整流 spill 上限;<=0 表示不启用 spill(仅诊断尾)。
	SpillMaxBytes int
}

SubprocessCollect 是一条输出流的受限内存收集配置(可选完整流 spill 文件)。

type SubprocessHandle

type SubprocessHandle struct {
	// Pid 进程 id(树根)。
	Pid int
	// contains filtered or unexported fields
}

SubprocessHandle 是一个以自己进程树为根的活子进程。

func (*SubprocessHandle) Collected

func (h *SubprocessHandle) Collected() *collectedOutputs

Collected 返回收集模式输出读取器(也可在退出后可读)。

func (*SubprocessHandle) Done

func (h *SubprocessHandle) Done() <-chan SubprocessOutcome

Done 返回进程关闭时的退出事实。

func (*SubprocessHandle) Terminate

func (h *SubprocessHandle) Terminate()

Terminate 在进程树上开始 SIGTERM → grace → SIGKILL 升级(Windows 立即 force)。 幂等;树消失后为 no-op。

type SubprocessOutcome

type SubprocessOutcome struct {
	// ExitCode 退出码;进程被信号杀死时为 -1。
	ExitCode int
	// Signal 终止信号名(如 SIGTERM);正常退出为空。
	Signal string
}

SubprocessOutcome 是已关闭进程的退出事实(不含超时/取消分类,调用方读它自有信号)。

type SubprocessSpawnSpec

type SubprocessSpawnSpec struct {
	// Argv 可执行程序与参数;程序是 argv[0];此处绝不做 shell 解释。
	Argv []string
	// Cwd 子进程工作目录。
	Cwd string
	// StdoutMaxBytes / StderrMaxBytes 收集模式内存上限;<=0 表示缺省 64KB。
	StdoutMaxBytes int
	StderrMaxBytes int
	// SpillRoot 完整流 spill 根目录;空表示不启用 spill。
	SpillRoot string
	// GraceMs SIGTERM → SIGKILL 的宽限毫秒。
	GraceMs int
	// Env 合并到 scrubbedParentEnv 之上的显式环境条目。
	Env map[string]string
	// StdinData 给 stdin 的可选数据(非空时关闭 stdin)。
	StdinData string
}

SubprocessSpawnSpec 是完全独立决定的 spawn 请求(本接缝不自带默认)。

type SubprocessStdinMode

type SubprocessStdinMode string

SubprocessStdinMode 是 stdin 布局:ignore 把 fd0 指向 /dev/null,pipe 暴露 stdin 流。

const (
	StdinIgnore SubprocessStdinMode = "ignore"
	StdinPipe   SubprocessStdinMode = "pipe"
	// StdinData 写入字节后即关闭(批处理形态)。
	StdinData = "data"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL