Cross-platform child process with async I/O and state notification. 更多...

#include <process.h>

vlink::Process 的协作图:

Public 类型
enum	State : uint8_t { kNotRunningState = 0 , kStartingState = 1 , kRunningState = 2 }
	Lifecycle state of the child process. 更多...
enum	ExitStatus : uint8_t { kNormalExitStatus = 0 , kCrashExitStatus = 1 }
	How the child process exited. 更多...
enum	Error : uint8_t { kNoError = 0 , kUnknownError = 1 , kStartError = 2 , kCrashedError = 3 , kTimedOutError = 4 , kWriteError = 5 , kReadError = 6 , kBufferOverflowError = 7 }
	Error codes set on failure. 更多...
enum	Mode : uint8_t { kSeparateMode = 0 , kMergedMode = 1 , kForwardedMode = 2 , kForwardedOutputMode = 3 , kForwardedErrorMode = 4 }
	I/O channel routing mode. 更多...
using	EnvironmentMap = std::unordered_map<std::string, std::string>
	Environment variable map type for `set_environment()`.
using	ErrorCallback = std::function<void(Error)>
	Callback type invoked when an error occurs.
using	FinishedCallback = std::function<void(int, ExitStatus)>
	Callback type invoked when the process exits.
using	ReadyReadCallback = std::function<void()>
	Callback type invoked when new data is available on a pipe.
using	StateChangedCallback = std::function<void(State)>
	Callback type invoked when the process state changes.

Public 成员函数
	Process ()
	Constructs a `Process` object. No child is started yet.
	~Process ()
	Destructor. Closes the process and waits up to `kDestructorWaitTimeoutMs`.
	Process (Process &&other) noexcept=delete
Process &	operator= (Process &&other) noexcept=delete
State	get_state () const
	Returns the current state of the child process.
Error	get_error () const
	Returns the last error code.
int	get_exit_code () const
	Returns the exit code of the child process.
ExitStatus	get_exit_status () const
	Returns how the child process exited.
bool	is_running () const
	Returns `true` if the child process is currently running.
int64_t	get_process_id () const
	Returns the operating-system process ID of the child.
void	set_max_buffer_size (size_t size)
	Sets the maximum buffer size for stdout and stderr capture.
size_t	get_max_buffer_size () const
	Returns the configured maximum buffer size.
void	set_environment (const EnvironmentMap &env_map)
	Sets the environment variables for the child process.
EnvironmentMap	get_environment () const
	Returns the configured environment map.
void	set_process_mode (Mode mode)
	Sets the I/O channel routing mode.
Mode	get_process_mode () const
	Returns the configured I/O channel mode.
void	set_inherit_environment (bool inherit)
	Controls whether the child inherits the parent's environment.
bool	get_inherit_environment () const
	Returns whether the child inherits the parent environment.
void	set_working_directory (const std::string &dir)
	Sets the working directory for the child process.
std::string	get_working_directory () const
	Returns the configured working directory.
void	register_error_callback (ErrorCallback &&callback)
	Registers a callback for error events.
void	register_finished_callback (FinishedCallback &&callback)
	Registers a callback invoked when the child exits.
void	register_ready_read_stdout_callback (ReadyReadCallback &&callback)
	Registers a callback invoked when new stdout data is available.
void	register_ready_read_stderr_callback (ReadyReadCallback &&callback)
	Registers a callback invoked when new stderr data is available.
void	register_state_changed_callback (StateChangedCallback &&callback)
	Registers a callback invoked when the process state changes.
void	start (const std::string &program, const std::vector< std::string > &arguments={})
	Launches the child process.
void	start_command (const std::string &command)
	Parses and launches a shell command string.
bool	wait_for_started (int msecs=kDefaultWaitTimeoutMs)
	Blocks until the child process enters `kRunningState`.
bool	wait_for_finished (int msecs=kDefaultWaitTimeoutMs)
	Blocks until the child process exits.
bool	wait_for_ready_read (int msecs=kDefaultWaitTimeoutMs)
	Blocks until new data is available on any pipe.
void	terminate ()
	Requests child termination.
void	kill ()
	Forcefully kills the child process (SIGKILL / TerminateProcess).
void	close (bool force_kill_on_timeout=false)
	Calls `terminate()` and optionally force-kills after a timeout.
size_t	bytes_available_stdout () const
	Returns the number of bytes available to read from stdout.
size_t	bytes_available_stderr () const
	Returns the number of bytes available to read from stderr.
bool	can_read_line_stdout () const
	Returns `true` if a complete newline-terminated line is available on stdout.
bool	can_read_line_stderr () const
	Returns `true` if a complete newline-terminated line is available on stderr.
bool	read_line_stdout (std::string &line)
	Reads one line from stdout into `line`.
bool	read_line_stderr (std::string &line)
	Reads one line from stderr into `line`.
size_t	read_stdout (std::vector< uint8_t > &buffer, size_t max_size)
	Reads up to `max_size` bytes from stdout into `buffer`.
size_t	read_stderr (std::vector< uint8_t > &buffer, size_t max_size)
	Reads up to `max_size` bytes from stderr into `buffer`.
bool	read_all_output (std::vector< uint8_t > &buffer)
	Reads all available stdout data into `buffer` (byte vector overload).
bool	read_all_error (std::vector< uint8_t > &buffer)
	Reads all available stderr data into `buffer` (byte vector overload).
bool	read_all (std::vector< uint8_t > &buffer)
	Reads all available stdout and stderr data into `buffer` (byte vector overload).
bool	read_all_output (std::string &str)
	Reads all available stdout data into `str`.
bool	read_all_error (std::string &str)
	Reads all available stderr data into `str`.
bool	read_all (std::string &str)
	Reads all available stdout and stderr data into `str`.
size_t	write (const std::vector< uint8_t > &buffer, int timeout_ms=kDefaultWriteTimeoutMs)
	Writes `buffer` to the child's stdin.
size_t	write (const std::string &str, int timeout_ms=kDefaultWriteTimeoutMs)
	Writes a string to the child's stdin.
void	close_write_channel ()
	Closes the write channel (stdin pipe), signalling EOF to the child.

静态 Public 成员函数
static int	execute (const std::string &program, const std::vector< std::string > &arguments={}, int timeout_ms=kDefaultExecuteTimeoutMs)
	Synchronously executes a program and waits for it to finish.
static bool	start_detached (const std::string &program, const std::vector< std::string > &arguments={})
	Starts a program in the background and returns immediately.

静态 Public 属性
static constexpr int	kInfinite {-1}
	Sentinel wait timeout meaning wait indefinitely.
static constexpr int	kDefaultWaitTimeoutMs {3000}
	Default timeout for `wait_for_started()` and `wait_for_finished()` in milliseconds.
static constexpr int	kDefaultWriteTimeoutMs {5000}
	Default timeout for `write()` in milliseconds.
static constexpr int	kDefaultExecuteTimeoutMs {30000}
	Default timeout for the synchronous `execute()` helper in milliseconds.
static constexpr int	kDestructorWaitTimeoutMs {5000}
	Time the destructor waits for the child to exit before force-killing in milliseconds.

详细描述

Cross-platform child process with async I/O and state notification.

A single Process object manages one child process at a time. It is non-copyable and non-moveable.

成员类型定义说明

◆ EnvironmentMap

using vlink::Process::EnvironmentMap = std::unordered_map<std::string, std::string>

Environment variable map type for set_environment().

◆ ErrorCallback

using vlink::Process::ErrorCallback = std::function<void(Error)>

Callback type invoked when an error occurs.

◆ FinishedCallback

using vlink::Process::FinishedCallback = std::function<void(int, ExitStatus)>

Callback type invoked when the process exits.

First argument is the exit code; second is kNormalExitStatus or kCrashExitStatus.

◆ ReadyReadCallback

using vlink::Process::ReadyReadCallback = std::function<void()>

Callback type invoked when new data is available on a pipe.

◆ StateChangedCallback

using vlink::Process::StateChangedCallback = std::function<void(State)>

Callback type invoked when the process state changes.

成员枚举类型说明

◆ Error

enum vlink::Process::Error : uint8_t

Error codes set on failure.

枚举值
kNoError	No error
kUnknownError	Unknown error
kStartError	Failed to start the process (e.g., file not found)
kCrashedError	Process crashed
kTimedOutError	A wait operation timed out
kWriteError	Write to stdin failed
kReadError	Read from stdout/stderr failed
kBufferOverflowError	Output exceeded `max_buffer_size`

◆ ExitStatus

enum vlink::Process::ExitStatus : uint8_t

How the child process exited.

枚举值
kNormalExitStatus	Exited normally (via exit() or return from main)
kCrashExitStatus	Killed by a signal or crashed

◆ Mode

enum vlink::Process::Mode : uint8_t

I/O channel routing mode.

枚举值
kSeparateMode	stdout and stderr buffered as separate pipes
kMergedMode	stderr merged into stdout pipe
kForwardedMode	Both stdout and stderr forwarded to the parent process
kForwardedOutputMode	stdout forwarded; stderr buffered separately
kForwardedErrorMode	stderr forwarded; stdout buffered separately

◆ State

enum vlink::Process::State : uint8_t

Lifecycle state of the child process.

枚举值
kNotRunningState	Not started or has exited
kStartingState	`start()` called; waiting for exec to complete
kRunningState	Successfully running

构造及析构函数说明

◆ Process() [1/2]

vlink::Process::Process ( )

Constructs a Process object. No child is started yet.

这是这个函数的调用关系图:

◆ ~Process()

vlink::Process::~Process ( )

Destructor. Closes the process and waits up to kDestructorWaitTimeoutMs.

◆ Process() [2/2]

vlink::Process::Process ( Process && other )

deletenoexcept

函数调用图:

成员函数说明

◆ bytes_available_stderr()

size_t vlink::Process::bytes_available_stderr ( ) const

nodiscard

Returns the number of bytes available to read from stderr.

返回: Bytes available in the stderr buffer.

◆ bytes_available_stdout()

size_t vlink::Process::bytes_available_stdout ( ) const

nodiscard

Returns the number of bytes available to read from stdout.

返回: Bytes available in the stdout buffer.

◆ can_read_line_stderr()

bool vlink::Process::can_read_line_stderr ( ) const

nodiscard

Returns true if a complete newline-terminated line is available on stderr.

返回: true if at least one line can be read.

◆ can_read_line_stdout()

bool vlink::Process::can_read_line_stdout ( ) const

nodiscard

Returns true if a complete newline-terminated line is available on stdout.

返回: true if at least one line can be read.

◆ close()

void vlink::Process::close ( bool force_kill_on_timeout = false )

Calls terminate() and optionally force-kills after a timeout.

参数

force_kill_on_timeout If true, calls kill() if the process has not exited after kDestructorWaitTimeoutMs. If false and the child does not exit in time, the process remains running. On Windows, terminate() is already forceful. Default: false.

◆ close_write_channel()

void vlink::Process::close_write_channel ( )

Closes the write channel (stdin pipe), signalling EOF to the child.

◆ execute()

int vlink::Process::execute	(	const std::string &	program,
		const std::vector< std::string > &	arguments = {},
		int	timeout_ms = kDefaultExecuteTimeoutMs )

static

Synchronously executes a program and waits for it to finish.

Blocks until the program exits or timeout_ms elapses. Returns the exit code. Stdout and stderr are discarded.

参数

program	Path to the executable.
arguments	Command-line arguments. Default: empty.
timeout_ms	Maximum wait time. Default: `kDefaultExecuteTimeoutMs` (30 s).

返回: Exit code, or -1 on timeout or start failure.

◆ get_environment()

EnvironmentMap vlink::Process::get_environment ( ) const

nodiscard

Returns the configured environment map.

返回: Environment variable map.

◆ get_error()

Error vlink::Process::get_error ( ) const

nodiscard

Returns the last error code.

返回: kNoError if no error has occurred.

◆ get_exit_code()

int vlink::Process::get_exit_code ( ) const

nodiscard

Returns the exit code of the child process.

Valid only after get_state() returns kNotRunningState.

返回: Exit code.

◆ get_exit_status()

ExitStatus vlink::Process::get_exit_status ( ) const

nodiscard

Returns how the child process exited.

返回: kNormalExitStatus or kCrashExitStatus.

◆ get_inherit_environment()

bool vlink::Process::get_inherit_environment ( ) const

nodiscard

Returns whether the child inherits the parent environment.

返回: true if inheriting.

◆ get_max_buffer_size()

size_t vlink::Process::get_max_buffer_size ( ) const

nodiscard

Returns the configured maximum buffer size.

返回: Buffer size in bytes. Default is 16 MB (16 * 1024 * 1024).

◆ get_process_id()

int64_t vlink::Process::get_process_id ( ) const

nodiscard

Returns the operating-system process ID of the child.

返回: PID, or -1 if not running.

◆ get_process_mode()

Mode vlink::Process::get_process_mode ( ) const

nodiscard

Returns the configured I/O channel mode.

返回: Current mode.

◆ get_state()

State vlink::Process::get_state ( ) const

nodiscard

Returns the current state of the child process.

返回: Current State value.

◆ get_working_directory()

std::string vlink::Process::get_working_directory ( ) const

nodiscard

Returns the configured working directory.

返回: Working directory path.

◆ is_running()

bool vlink::Process::is_running ( ) const

nodiscard

Returns true if the child process is currently running.

返回: true if state is kRunningState.

◆ kill()

void vlink::Process::kill ( )

Forcefully kills the child process (SIGKILL / TerminateProcess).

◆ operator=()

Process & vlink::Process::operator= ( Process && other )

deletenoexcept

函数调用图:

◆ read_all() [1/2]

bool vlink::Process::read_all ( std::string & str )

Reads all available stdout and stderr data into str.

参数

str	Destination string.

返回: true if any data was available.

◆ read_all() [2/2]

bool vlink::Process::read_all ( std::vector< uint8_t > & buffer )

Reads all available stdout and stderr data into buffer (byte vector overload).

参数

buffer Destination vector; existing content is replaced.

返回: true if any data was available.

◆ read_all_error() [1/2]

bool vlink::Process::read_all_error ( std::string & str )

Reads all available stderr data into str.

参数

str	Destination string.

返回: true if any data was available.

◆ read_all_error() [2/2]

bool vlink::Process::read_all_error ( std::vector< uint8_t > & buffer )

Reads all available stderr data into buffer (byte vector overload).

参数

buffer Destination vector; existing content is replaced.

返回: true if any data was available.

◆ read_all_output() [1/2]

bool vlink::Process::read_all_output ( std::string & str )

Reads all available stdout data into str.

参数

str	Destination string.

返回: true if any data was available.

◆ read_all_output() [2/2]

bool vlink::Process::read_all_output ( std::vector< uint8_t > & buffer )

Reads all available stdout data into buffer (byte vector overload).

参数

buffer Destination vector; existing content is replaced.

返回: true if any data was available.

◆ read_line_stderr()

bool vlink::Process::read_line_stderr ( std::string & line )

Reads one line from stderr into line.

参数

line	Output string. Includes the trailing newline when one is buffered.

返回: true if a line was read.

◆ read_line_stdout()

bool vlink::Process::read_line_stdout ( std::string & line )

Reads one line from stdout into line.

参数

line	Output string. Includes the trailing newline when one is buffered.

返回: true if a line was read.

◆ read_stderr()

size_t vlink::Process::read_stderr	(	std::vector< uint8_t > &	buffer,
		size_t	max_size )

Reads up to max_size bytes from stderr into buffer.

参数

buffer	Destination vector.
max_size	Maximum bytes to read.

返回: Number of bytes actually read.

◆ read_stdout()

size_t vlink::Process::read_stdout	(	std::vector< uint8_t > &	buffer,
		size_t	max_size )

Reads up to max_size bytes from stdout into buffer.

参数

buffer	Destination vector.
max_size	Maximum bytes to read.

返回: Number of bytes actually read.

◆ register_error_callback()

void vlink::Process::register_error_callback ( ErrorCallback && callback )

Registers a callback for error events.

参数

callback Invoked with the Error code when an error occurs.

◆ register_finished_callback()

void vlink::Process::register_finished_callback ( FinishedCallback && callback )

Registers a callback invoked when the child exits.

参数

callback Invoked with (exit_code, exit_status).

◆ register_ready_read_stderr_callback()

void vlink::Process::register_ready_read_stderr_callback ( ReadyReadCallback && callback )

Registers a callback invoked when new stderr data is available.

参数

callback Invoked from the monitor thread when stderr has data.

◆ register_ready_read_stdout_callback()

void vlink::Process::register_ready_read_stdout_callback ( ReadyReadCallback && callback )

Registers a callback invoked when new stdout data is available.

参数

callback Invoked from the monitor thread when stdout has data.

◆ register_state_changed_callback()

void vlink::Process::register_state_changed_callback ( StateChangedCallback && callback )

Registers a callback invoked when the process state changes.

参数

callback Invoked with the new State value.

◆ set_environment()

void vlink::Process::set_environment ( const EnvironmentMap & env_map )

Sets the environment variables for the child process.

Replaces (or supplements, depending on set_inherit_environment) the child's environment with env_map.

参数

env_map Map of variable name to value.

◆ set_inherit_environment()

void vlink::Process::set_inherit_environment ( bool inherit )

Controls whether the child inherits the parent's environment.

参数

inherit If true, the child inherits all parent environment variables. If false, only the variables in the EnvironmentMap are set.

◆ set_max_buffer_size()

void vlink::Process::set_max_buffer_size ( size_t size )

Sets the maximum buffer size for stdout and stderr capture.

If the child produces more output than size bytes, kBufferOverflowError is set. Passing 0 resets the limit to the default (16 MB).

参数

size	Maximum buffer size in bytes.

◆ set_process_mode()

void vlink::Process::set_process_mode ( Mode mode )

Sets the I/O channel routing mode.

参数

mode	Channel mode. Must be set before `start()`.

◆ set_working_directory()

void vlink::Process::set_working_directory ( const std::string & dir )

Sets the working directory for the child process.

参数

dir	Absolute path to the working directory.

◆ start()

void vlink::Process::start	(	const std::string &	program,
		const std::vector< std::string > &	arguments = {} )

Launches the child process.

The child is started asynchronously. Call wait_for_started() to block until the child is in kRunningState.

参数

program	Path to the executable.
arguments	Command-line arguments. Default: empty.

◆ start_command()

void vlink::Process::start_command ( const std::string & command )

Parses and launches a shell command string.

Splits command by whitespace into a program and argument list, then calls start().

参数

command Shell command string.

◆ start_detached()

bool vlink::Process::start_detached	(	const std::string &	program,
		const std::vector< std::string > &	arguments = {} )

static

Starts a program in the background and returns immediately.

The started process is completely detached from the calling process. No handle is returned; the process runs until it exits on its own.

参数

program	Path to the executable.
arguments	Command-line arguments. Default: empty.

返回: true if the process was successfully started.

◆ terminate()

void vlink::Process::terminate ( )

Requests child termination.

On POSIX this sends SIGTERM, which the child may handle or ignore. On Windows this uses TerminateProcess, so termination is immediate. Use kill() for an explicit forceful stop.

◆ wait_for_finished()

bool vlink::Process::wait_for_finished ( int msecs = kDefaultWaitTimeoutMs )

Blocks until the child process exits.

参数

msecs Timeout in milliseconds. Default: kDefaultWaitTimeoutMs (3000 ms).

返回: true if the process exited within the timeout.

◆ wait_for_ready_read()

bool vlink::Process::wait_for_ready_read ( int msecs = kDefaultWaitTimeoutMs )

Blocks until new data is available on any pipe.

参数

msecs Timeout in milliseconds. Default: kDefaultWaitTimeoutMs (3000 ms).

返回: true if data became available within the timeout.

◆ wait_for_started()

bool vlink::Process::wait_for_started ( int msecs = kDefaultWaitTimeoutMs )

Blocks until the child process enters kRunningState.

参数

msecs Timeout in milliseconds. Default: kDefaultWaitTimeoutMs (3000 ms).

返回: true if the process is running within the timeout.

◆ write() [1/2]

size_t vlink::Process::write	(	const std::string &	str,
		int	timeout_ms = kDefaultWriteTimeoutMs )

Writes a string to the child's stdin.

参数

str	String to write.
timeout_ms	Maximum time to wait. Default: `kDefaultWriteTimeoutMs`.

返回: Number of bytes actually written.

◆ write() [2/2]

size_t vlink::Process::write	(	const std::vector< uint8_t > &	buffer,
		int	timeout_ms = kDefaultWriteTimeoutMs )

Writes buffer to the child's stdin.

参数

buffer	Data to write.
timeout_ms	Maximum time to wait for the write to complete. Default: `kDefaultWriteTimeoutMs`.

返回: Number of bytes actually written.

类成员变量说明

◆ kDefaultExecuteTimeoutMs

int vlink::Process::kDefaultExecuteTimeoutMs {30000}

staticconstexpr

Default timeout for the synchronous execute() helper in milliseconds.

◆ kDefaultWaitTimeoutMs

int vlink::Process::kDefaultWaitTimeoutMs {3000}

staticconstexpr

Default timeout for wait_for_started() and wait_for_finished() in milliseconds.

◆ kDefaultWriteTimeoutMs

int vlink::Process::kDefaultWriteTimeoutMs {5000}

staticconstexpr

Default timeout for write() in milliseconds.

◆ kDestructorWaitTimeoutMs

int vlink::Process::kDestructorWaitTimeoutMs {5000}

staticconstexpr

Time the destructor waits for the child to exit before force-killing in milliseconds.

◆ kInfinite

int vlink::Process::kInfinite {-1}

staticconstexpr

Sentinel wait timeout meaning wait indefinitely.

该类的文档由以下文件生成:

include/vlink/base/process.h

Public 类型

Public 成员函数

静态 Public 成员函数

静态 Public 属性

详细描述

成员类型定义说明

◆ EnvironmentMap

◆ ErrorCallback

◆ FinishedCallback

◆ ReadyReadCallback

◆ StateChangedCallback

成员枚举类型说明

◆ Error

◆ ExitStatus

◆ Mode

◆ State

构造及析构函数说明

◆ Process() [1/2]

◆ ~Process()

◆ Process() [2/2]

成员函数说明

◆ bytes_available_stderr()

◆ bytes_available_stdout()

◆ can_read_line_stderr()

◆ can_read_line_stdout()

◆ close()

◆ close_write_channel()

◆ execute()

◆ get_environment()

◆ get_error()

◆ get_exit_code()

◆ get_exit_status()

◆ get_inherit_environment()

◆ get_max_buffer_size()

◆ get_process_id()

◆ get_process_mode()

◆ get_state()

◆ get_working_directory()

◆ is_running()

◆ kill()

◆ operator=()

◆ read_all() [1/2]

◆ read_all() [2/2]

◆ read_all_error() [1/2]

◆ read_all_error() [2/2]

◆ read_all_output() [1/2]

◆ read_all_output() [2/2]

◆ read_line_stderr()

◆ read_line_stdout()

◆ read_stderr()

◆ read_stdout()

◆ register_error_callback()

◆ register_finished_callback()

◆ register_ready_read_stderr_callback()

◆ register_ready_read_stdout_callback()

◆ register_state_changed_callback()

◆ set_environment()

◆ set_inherit_environment()

◆ set_max_buffer_size()

◆ set_process_mode()

◆ set_working_directory()

◆ start()

◆ start_command()

◆ start_detached()

◆ terminate()

◆ wait_for_finished()

◆ wait_for_ready_read()

◆ wait_for_started()

◆ write() [1/2]

◆ write() [2/2]

类成员变量说明

◆ kDefaultExecuteTimeoutMs

◆ kDefaultWaitTimeoutMs

◆ kDefaultWriteTimeoutMs

◆ kDestructorWaitTimeoutMs

◆ kInfinite