|
VLink
2.3.0
A high-performance communication middleware
|
Owns and drives a single child process with asynchronous I/O reporting. 更多...
#include <process.h>
Public 类型 | |
| enum | State : uint8_t { kNotRunningState = 0 , kStartingState = 1 , kRunningState = 2 } |
| Coarse lifecycle stage of the child process. 更多... | |
| enum | ExitStatus : uint8_t { kNormalExitStatus = 0 , kCrashExitStatus = 1 } |
| How the most recent child exited. 更多... | |
| enum | Error : uint8_t { kNoError = 0 , kUnknownError = 1 , kStartError = 2 , kCrashedError = 3 , kTimedOutError = 4 , kWriteError = 5 , kReadError = 6 , kBufferOverflowError = 7 } |
| Last error recorded by a failing operation. 更多... | |
| enum | Mode : uint8_t { kSeparateMode = 0 , kMergedMode = 1 , kForwardedMode = 2 , kForwardedOutputMode = 3 , kForwardedErrorMode = 4 } |
| Routing of the child's stdout/stderr file descriptors. 更多... | |
| using | EnvironmentMap = std::unordered_map< std::string, std::string > |
Map type used to pass environment overrides to set_environment(). 更多... | |
| using | ErrorCallback = Function< void(Error)> |
| Callback signature invoked on the first error of a run. 更多... | |
| using | FinishedCallback = Function< void(int, ExitStatus)> |
| Callback signature invoked when the child exits. 更多... | |
| using | ReadyReadCallback = Function< void()> |
| Callback signature invoked whenever new data is available on a pipe. 更多... | |
| using | StateChangedCallback = Function< void(State)> |
Callback signature invoked when the process State transitions. 更多... | |
Public 成员函数 | |
| Process () | |
| Constructs an idle process driver with no child attached. 更多... | |
| ~Process () | |
| Destructor. Terminates the child if still alive then frees driver resources. 更多... | |
| Process (Process &&other) noexcept=delete | |
| Process & | operator= (Process &&other) noexcept=delete |
| State | get_state () const |
| Returns the lifecycle state of the currently attached child. 更多... | |
| Error | get_error () const |
| Returns the most recently latched error code. 更多... | |
| int | get_exit_code () const |
| Returns the exit code of the most recent child process. 更多... | |
| ExitStatus | get_exit_status () const |
| Returns how the most recent child terminated. 更多... | |
| bool | is_running () const |
| Reports whether the attached child is currently running. 更多... | |
| int64_t | get_process_id () const |
| Returns the OS-level identifier of the child process. 更多... | |
| void | set_max_buffer_size (size_t size) |
| Limits the in-memory capture buffer used for stdout/stderr. 更多... | |
| size_t | get_max_buffer_size () const |
| Returns the configured capture-buffer limit. 更多... | |
| void | set_environment (const EnvironmentMap &env_map) |
Defines the environment that will be applied at the next start() call. 更多... | |
| EnvironmentMap | get_environment () const |
| Returns the currently configured environment override. 更多... | |
| void | set_process_mode (Mode mode) |
Sets the I/O channel routing that will be applied at the next start() call. 更多... | |
| Mode | get_process_mode () const |
| Returns the currently configured I/O routing mode. 更多... | |
| void | set_inherit_environment (bool inherit) |
| Controls whether the child inherits the parent environment in addition to the override map. 更多... | |
| bool | get_inherit_environment () const |
| Reports whether the child currently inherits the parent environment. 更多... | |
| void | set_working_directory (const std::string &dir) |
Sets the working directory used at the next start() call. 更多... | |
| std::string | get_working_directory () const |
| Returns the currently configured working directory. 更多... | |
| void | register_error_callback (ErrorCallback &&callback) |
Installs a callback fired when the Error state changes. 更多... | |
| void | register_finished_callback (FinishedCallback &&callback) |
| Installs a callback fired when the child exits. 更多... | |
| void | register_ready_read_stdout_callback (ReadyReadCallback &&callback) |
| Installs a callback fired when stdout has new data buffered. 更多... | |
| void | register_ready_read_stderr_callback (ReadyReadCallback &&callback) |
| Installs a callback fired when stderr has new data buffered. 更多... | |
| void | register_state_changed_callback (StateChangedCallback &&callback) |
Installs a callback fired on every State transition. 更多... | |
| void | start (const std::string &program, const std::vector< std::string > &arguments={}) |
Launches program with the given argument vector. 更多... | |
| void | start_command (const std::string &command) |
| Parses a shell-style command line and launches it. 更多... | |
| bool | wait_for_started (int msecs=kDefaultWaitTimeoutMs) |
Blocks until the child leaves kStartingState or the timeout elapses. 更多... | |
| bool | wait_for_finished (int msecs=kDefaultWaitTimeoutMs) |
| Blocks until the child terminates or the timeout elapses. 更多... | |
| bool | wait_for_ready_read (int msecs=kDefaultWaitTimeoutMs) |
| Blocks until new pipe data becomes available or the timeout elapses. 更多... | |
| void | terminate () |
| Requests cooperative termination of the child. 更多... | |
| void | kill () |
Forces immediate termination of the child via SIGKILL / TerminateProcess. 更多... | |
| void | close (bool force_kill_on_timeout=false) |
Sends SIGTERM and optionally escalates to kill() after the wait timeout. 更多... | |
| size_t | bytes_available_stdout () const |
| Returns the number of buffered bytes available to read from stdout. 更多... | |
| size_t | bytes_available_stderr () const |
| Returns the number of buffered bytes available to read from stderr. 更多... | |
| bool | can_read_line_stdout () const |
| Reports whether a newline-terminated line is fully buffered on stdout. 更多... | |
| bool | can_read_line_stderr () const |
| Reports whether a newline-terminated line is fully buffered on stderr. 更多... | |
| bool | read_line_stdout (std::string &line) |
| Reads one buffered line from stdout. 更多... | |
| bool | read_line_stderr (std::string &line) |
| Reads one buffered line from stderr. 更多... | |
| size_t | read_stdout (std::vector< uint8_t > &buffer, size_t max_size) |
Reads up to max_size bytes of buffered stdout into buffer. 更多... | |
| size_t | read_stderr (std::vector< uint8_t > &buffer, size_t max_size) |
Reads up to max_size bytes of buffered stderr into buffer. 更多... | |
| bool | read_all_output (std::vector< uint8_t > &buffer) |
Drains all buffered stdout into buffer. 更多... | |
| bool | read_all_error (std::vector< uint8_t > &buffer) |
Drains all buffered stderr into buffer. 更多... | |
| bool | read_all (std::vector< uint8_t > &buffer) |
Drains all buffered stdout and stderr into buffer. 更多... | |
| bool | read_all_output (std::string &str) |
Drains all buffered stdout into str. 更多... | |
| bool | read_all_error (std::string &str) |
Drains all buffered stderr into str. 更多... | |
| bool | read_all (std::string &str) |
Drains all buffered stdout and stderr into str. 更多... | |
| size_t | write (const std::vector< uint8_t > &buffer, int timeout_ms=kDefaultWriteTimeoutMs) |
| Writes a byte 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 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 returns its exit code. 更多... | |
| static bool | start_detached (const std::string &program, const std::vector< std::string > &arguments={}) |
| Launches a program detached from the calling process and returns immediately. 更多... | |
静态 Public 属性 | |
| static constexpr int | kInfinite {-1} |
| Sentinel value used to request an unbounded wait. 更多... | |
| static constexpr int | kDefaultWaitTimeoutMs {3000} |
Default deadline for wait_for_started / wait_for_finished (3000 ms). 更多... | |
| static constexpr int | kDefaultWriteTimeoutMs {5000} |
| Default deadline for blocking writes to the child's stdin (5000 ms). 更多... | |
| static constexpr int | kDefaultExecuteTimeoutMs {30000} |
Default deadline for the synchronous execute() helper (30000 ms). 更多... | |
| static constexpr int | kDestructorWaitTimeoutMs {5000} |
Grace period the destructor allows after sending SIGTERM before escalating. 更多... | |
Owns and drives a single child process with asynchronous I/O reporting.
The instance is non-copyable and non-movable. A new child may only be launched after any previous one has terminated and the internal state has been cleaned up.
| using vlink::Process::EnvironmentMap = std::unordered_map<std::string, std::string> |
Map type used to pass environment overrides to set_environment().
| using vlink::Process::ErrorCallback = Function<void(Error)> |
Callback signature invoked on the first error of a run.
Fires at most once per run; start() and close() re-arm it. Later errors in the same run still update get_error() but do not re-notify.
| using vlink::Process::FinishedCallback = Function<void(int, ExitStatus)> |
Callback signature invoked when the child exits.
The first parameter is the exit code; the second is kNormalExitStatus or kCrashExitStatus.
| using vlink::Process::ReadyReadCallback = Function<void()> |
Callback signature invoked whenever new data is available on a pipe.
| using vlink::Process::StateChangedCallback = Function<void(State)> |
Callback signature invoked when the process State transitions.
| enum vlink::Process::Error : uint8_t |
Last error recorded by a failing operation.
Each failure overwrites the previous value; the code is not sticky. It is reset to kNoError by start(). kCrashedError and kUnknownError are never produced by this class – a crash is reported through get_exit_status() instead.
| enum vlink::Process::ExitStatus : uint8_t |
| enum vlink::Process::Mode : uint8_t |
Routing of the child's stdout/stderr file descriptors.
| enum vlink::Process::State : uint8_t |
Coarse lifecycle stage of the child process.
| 枚举值 | |
|---|---|
| kNotRunningState | No child is currently active. |
| kStartingState |
|
| kRunningState | Child has been successfully launched and is executing. |
| vlink::Process::Process | ( | ) |
Constructs an idle process driver with no child attached.
| vlink::Process::~Process | ( | ) |
Destructor. Terminates the child if still alive then frees driver resources.
The sequence sends SIGTERM via terminate(), drains any pending pipe data, waits up to kDestructorWaitTimeoutMs for a graceful exit, then escalates to SIGKILL via kill() and waits up to a further 1000 ms before releasing the I/O thread, pipes and child handles.
|
deletenoexcept |
| size_t vlink::Process::bytes_available_stderr | ( | ) | const |
Returns the number of buffered bytes available to read from stderr.
| size_t vlink::Process::bytes_available_stdout | ( | ) | const |
Returns the number of buffered bytes available to read from stdout.
| bool vlink::Process::can_read_line_stderr | ( | ) | const |
Reports whether a newline-terminated line is fully buffered on stderr.
true when read_line_stderr() will deliver a complete line. | bool vlink::Process::can_read_line_stdout | ( | ) | const |
Reports whether a newline-terminated line is fully buffered on stdout.
true when read_line_stdout() will deliver a complete line. | void vlink::Process::close | ( | bool | force_kill_on_timeout = false | ) |
Sends SIGTERM and optionally escalates to kill() after the wait timeout.
| force_kill_on_timeout | When true and the child has not exited within kDefaultWaitTimeoutMs, kill() is invoked. On Windows terminate() is already forceful so the flag is effectively ignored. Default: false. |
| void vlink::Process::close_write_channel | ( | ) |
Closes the stdin pipe, signalling EOF to the child.
|
static |
Synchronously executes a program and returns its exit code.
The child's output is not forwarded anywhere, but it is still drained into the internal stdout and stderr buffers, each capped at the default 16 MiB, so a very chatty command holds that much memory for the duration of the call. Returns -1 when the launch fails or the timeout elapses.
| program | Path to the executable. |
| arguments | Argument vector. Default: empty. |
| timeout_ms | Maximum wait in milliseconds. Default: kDefaultExecuteTimeoutMs. |
-1 on failure. | EnvironmentMap vlink::Process::get_environment | ( | ) | const |
Returns the currently configured environment override.
| Error vlink::Process::get_error | ( | ) | const |
Returns the most recently latched error code.
Error value; kNoError if no error has occurred. | int vlink::Process::get_exit_code | ( | ) | const |
Returns the exit code of the most recent child process.
Only meaningful once get_state() reports kNotRunningState.
exit() or implied by signal termination. | ExitStatus vlink::Process::get_exit_status | ( | ) | const |
Returns how the most recent child terminated.
kNormalExitStatus on graceful exit, kCrashExitStatus on signal/crash. | bool vlink::Process::get_inherit_environment | ( | ) | const |
Reports whether the child currently inherits the parent environment.
true when the parent environment is merged. | size_t vlink::Process::get_max_buffer_size | ( | ) | const |
Returns the configured capture-buffer limit.
| int64_t vlink::Process::get_process_id | ( | ) | const |
Returns the OS-level identifier of the child process.
-1 when no child is attached. | Mode vlink::Process::get_process_mode | ( | ) | const |
Returns the currently configured I/O routing mode.
Mode. | State vlink::Process::get_state | ( | ) | const |
Returns the lifecycle state of the currently attached child.
State value. | std::string vlink::Process::get_working_directory | ( | ) | const |
Returns the currently configured working directory.
| bool vlink::Process::is_running | ( | ) | const |
Reports whether the attached child is currently running.
true when get_state() equals kRunningState. | void vlink::Process::kill | ( | ) |
Forces immediate termination of the child via SIGKILL / TerminateProcess.
| bool vlink::Process::read_all | ( | std::string & | str | ) |
Drains all buffered stdout and stderr into str.
| str | Destination string; replaced. |
true when any data was copied. | bool vlink::Process::read_all | ( | std::vector< uint8_t > & | buffer | ) |
Drains all buffered stdout and stderr into buffer.
| buffer | Destination byte vector; replaced. |
true when any data was copied. | bool vlink::Process::read_all_error | ( | std::string & | str | ) |
Drains all buffered stderr into str.
| str | Destination string; replaced. |
true when any data was copied. | bool vlink::Process::read_all_error | ( | std::vector< uint8_t > & | buffer | ) |
Drains all buffered stderr into buffer.
| buffer | Destination byte vector; replaced. |
true when any data was copied. | bool vlink::Process::read_all_output | ( | std::string & | str | ) |
Drains all buffered stdout into str.
| str | Destination string; replaced. |
true when any data was copied. | bool vlink::Process::read_all_output | ( | std::vector< uint8_t > & | buffer | ) |
Drains all buffered stdout into buffer.
| buffer | Destination byte vector; replaced. |
true when any data was copied. | bool vlink::Process::read_line_stderr | ( | std::string & | line | ) |
Reads one buffered line from stderr.
| line | Destination string; receives buffered data including a trailing newline when one was buffered. |
true when at least one byte was copied into line. | bool vlink::Process::read_line_stdout | ( | std::string & | line | ) |
Reads one buffered line from stdout.
| line | Destination string; receives buffered data including a trailing newline when one was buffered. |
true when at least one byte was copied into line. | size_t vlink::Process::read_stderr | ( | std::vector< uint8_t > & | buffer, |
| size_t | max_size | ||
| ) |
Reads up to max_size bytes of buffered stderr into buffer.
| buffer | Destination byte vector. |
| max_size | Upper bound on bytes to copy. |
| size_t vlink::Process::read_stdout | ( | std::vector< uint8_t > & | buffer, |
| size_t | max_size | ||
| ) |
Reads up to max_size bytes of buffered stdout into buffer.
| buffer | Destination byte vector. |
| max_size | Upper bound on bytes to copy. |
| void vlink::Process::register_error_callback | ( | ErrorCallback && | callback | ) |
Installs a callback fired when the Error state changes.
| callback | Callback invoked on the monitor thread or by the calling operation. |
| void vlink::Process::register_finished_callback | ( | FinishedCallback && | callback | ) |
Installs a callback fired when the child exits.
| callback | Callback invoked with exit code and exit status. |
| void vlink::Process::register_ready_read_stderr_callback | ( | ReadyReadCallback && | callback | ) |
Installs a callback fired when stderr has new data buffered.
| callback | Callback invoked on the monitor thread or by the calling operation. |
| void vlink::Process::register_ready_read_stdout_callback | ( | ReadyReadCallback && | callback | ) |
Installs a callback fired when stdout has new data buffered.
| callback | Callback invoked on the monitor thread or by the calling operation. |
| void vlink::Process::register_state_changed_callback | ( | StateChangedCallback && | callback | ) |
Installs a callback fired on every State transition.
| callback | Callback invoked on the monitor thread or by the calling operation with the new State. |
| void vlink::Process::set_environment | ( | const EnvironmentMap & | env_map | ) |
Defines the environment that will be applied at the next start() call.
| env_map | Variable map to merge into or replace the parent environment based on the set_inherit_environment() setting. |
| void vlink::Process::set_inherit_environment | ( | bool | inherit | ) |
Controls whether the child inherits the parent environment in addition to the override map.
| inherit | true to merge with the parent environment, false to use only the override map. |
| void vlink::Process::set_max_buffer_size | ( | size_t | size | ) |
Limits the in-memory capture buffer used for stdout/stderr.
When the captured output exceeds size bytes the kBufferOverflowError code is latched. Passing 0 restores the default of 16 MiB.
| size | New buffer limit in bytes. |
| void vlink::Process::set_process_mode | ( | Mode | mode | ) |
Sets the I/O channel routing that will be applied at the next start() call.
| mode | Routing mode for stdout/stderr. |
| void vlink::Process::set_working_directory | ( | const std::string & | dir | ) |
Sets the working directory used at the next start() call.
| dir | Absolute path the child should chdir to before executing the program. |
| void vlink::Process::start | ( | const std::string & | program, |
| const std::vector< std::string > & | arguments = {} |
||
| ) |
Launches program with the given argument vector.
Returns once the launch attempt has either succeeded (state becomes kRunningState) or failed (an Error is latched). I/O monitoring continues asynchronously on the internal monitor thread.
| program | Path to the executable. |
| arguments | Argument vector excluding argv[0]. |
| void vlink::Process::start_command | ( | const std::string & | command | ) |
Parses a shell-style command line and launches it.
Splits command on whitespace with quote and backslash handling, preserves quoted empty arguments, then delegates to start().
| command | Shell-style command string. |
|
static |
Launches a program detached from the calling process and returns immediately.
| program | Path to the executable. |
| arguments | Argument vector. Default: empty. |
true when the OS reports a successful launch. | void vlink::Process::terminate | ( | ) |
Requests cooperative termination of the child.
POSIX sends SIGTERM, which the child may catch. Windows uses TerminateProcess, which is unconditional. kill() must be used for a forced exit on POSIX.
| bool vlink::Process::wait_for_finished | ( | int | msecs = kDefaultWaitTimeoutMs | ) |
Blocks until the child terminates or the timeout elapses.
| msecs | Maximum wait in milliseconds. Default: kDefaultWaitTimeoutMs. |
true when the child has exited within the timeout. | bool vlink::Process::wait_for_ready_read | ( | int | msecs = kDefaultWaitTimeoutMs | ) |
Blocks until new pipe data becomes available or the timeout elapses.
| msecs | Maximum wait in milliseconds. Default: kDefaultWaitTimeoutMs. |
true when data is now available on stdout or stderr. | bool vlink::Process::wait_for_started | ( | int | msecs = kDefaultWaitTimeoutMs | ) |
Blocks until the child leaves kStartingState or the timeout elapses.
A child that already exited still counts as started.
| msecs | Maximum wait in milliseconds. Default: kDefaultWaitTimeoutMs. |
true if the child started (even if since exited); false on launch failure, timeout, or if never started. | 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 wait in milliseconds. Default: kDefaultWriteTimeoutMs. |
| size_t vlink::Process::write | ( | const std::vector< uint8_t > & | buffer, |
| int | timeout_ms = kDefaultWriteTimeoutMs |
||
| ) |
Writes a byte buffer to the child's stdin.
| buffer | Bytes to write. |
| timeout_ms | Maximum wait in milliseconds. Default: kDefaultWriteTimeoutMs. |
|
staticconstexpr |
Default deadline for the synchronous execute() helper (30000 ms).
|
staticconstexpr |
Default deadline for wait_for_started / wait_for_finished (3000 ms).
|
staticconstexpr |
Default deadline for blocking writes to the child's stdin (5000 ms).
|
staticconstexpr |
Grace period the destructor allows after sending SIGTERM before escalating.
|
staticconstexpr |
Sentinel value used to request an unbounded wait.