95 #include <unordered_map>
118 kNotRunningState = 0,
128 kNormalExitStatus = 0,
129 kCrashExitStatus = 1,
149 kBufferOverflowError = 7,
160 kForwardedOutputMode = 3,
161 kForwardedErrorMode = 4,
200 static constexpr
int kInfinite{-1};
205 static constexpr
int kDefaultWaitTimeoutMs{3000};
210 static constexpr
int kDefaultWriteTimeoutMs{5000};
215 static constexpr
int kDefaultExecuteTimeoutMs{30000};
220 static constexpr
int kDestructorWaitTimeoutMs{5000};
408 void start(
const std::string& program,
const std::vector<std::string>& arguments = {});
470 void close(
bool force_kill_on_timeout =
false);
525 size_t read_stdout(std::vector<uint8_t>& buffer,
size_t max_size);
534 size_t read_stderr(std::vector<uint8_t>& buffer,
size_t max_size);
591 size_t write(
const std::vector<uint8_t>& buffer,
int timeout_ms = kDefaultWriteTimeoutMs);
600 size_t write(
const std::string& str,
int timeout_ms = kDefaultWriteTimeoutMs);
626 static int execute(
const std::string& program,
const std::vector<std::string>& arguments = {},
627 int timeout_ms = kDefaultExecuteTimeoutMs);
636 static bool start_detached(
const std::string& program,
const std::vector<std::string>& arguments = {});
639 struct ReadResult final {
640 bool has_stdout_data{
false};
641 bool has_stderr_data{
false};
642 bool truncated{
false};
643 bool read_error{
false};
646 void set_state(State state);
648 void set_error(Error error);
652 ReadResult read_from_pipes();
654 void report_read_result(
const ReadResult& result,
bool notify_data =
true);
656 void read_from_pipes_with_lock();
660 bool start_program(
const std::string& program,
const std::vector<std::string>& arguments);
662 void monitor_thread();
664 void start_monitor_thread();
666 void stop_monitor_thread();
668 void handle_process_exit(
int exit_code, ExitStatus status);
670 void invoke_callbacks_outside_lock(Error error_to_report,
bool has_finished,
int exit_code_to_report,
671 ExitStatus exit_status_to_report, State state_to_report,
bool has_state_changed,
672 bool has_stdout_data,
bool has_stderr_data);
675 std::unique_ptr<Impl> impl_;
Copyable type-erased callable analogue of std::function with a tunable SBO and pool spill.
Definition: functional.h:132
Owns and drives a single child process with asynchronous I/O reporting.
Definition: process.h:111
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 wait_for_ready_read(int msecs=kDefaultWaitTimeoutMs)
Blocks until new pipe data becomes available or the timeout elapses.
size_t write(const std::vector< uint8_t > &buffer, int timeout_ms=kDefaultWriteTimeoutMs)
Writes a byte buffer to the child's stdin.
Mode get_process_mode() const
Returns the currently configured I/O routing mode.
std::unordered_map< std::string, std::string > EnvironmentMap
Map type used to pass environment overrides to set_environment().
Definition: process.h:167
~Process()
Destructor. Terminates the child if still alive then frees driver resources.
Error get_error() const
Returns the most recently latched error code.
bool can_read_line_stdout() const
Reports whether a newline-terminated line is fully buffered on stdout.
void register_ready_read_stderr_callback(ReadyReadCallback &&callback)
Installs a callback fired when stderr has new data buffered.
Process & operator=(Process &&other) noexcept=delete
void set_max_buffer_size(size_t size)
Limits the in-memory capture buffer used for stdout/stderr.
EnvironmentMap get_environment() const
Returns the currently configured environment override.
ExitStatus get_exit_status() const
Returns how the most recent child terminated.
void register_error_callback(ErrorCallback &&callback)
Installs a callback fired when the Error state changes.
void set_inherit_environment(bool inherit)
Controls whether the child inherits the parent environment in addition to the override map.
int64_t get_process_id() const
Returns the OS-level identifier of the child process.
Mode
Routing of the child's stdout/stderr file descriptors.
Definition: process.h:156
void start_command(const std::string &command)
Parses a shell-style command line and launches it.
void close_write_channel()
Closes the stdin pipe, signalling EOF to the child.
size_t get_max_buffer_size() const
Returns the configured capture-buffer limit.
bool wait_for_finished(int msecs=kDefaultWaitTimeoutMs)
Blocks until the child terminates or the timeout elapses.
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.
bool read_line_stderr(std::string &line)
Reads one buffered line from stderr.
bool get_inherit_environment() const
Reports whether the child currently inherits the parent environment.
Process(Process &&other) noexcept=delete
Process()
Constructs an idle process driver with no child attached.
ExitStatus
How the most recent child exited.
Definition: process.h:127
bool read_line_stdout(std::string &line)
Reads one buffered line from stdout.
bool read_all_output(std::string &str)
Drains all buffered stdout into str.
size_t bytes_available_stderr() const
Returns the number of buffered bytes available to read from stderr.
void set_process_mode(Mode mode)
Sets the I/O channel routing that will be applied at the next start() call.
bool read_all_error(std::string &str)
Drains all buffered stderr into str.
void register_ready_read_stdout_callback(ReadyReadCallback &&callback)
Installs a callback fired when stdout has new data buffered.
void register_state_changed_callback(StateChangedCallback &&callback)
Installs a callback fired on every State transition.
bool is_running() const
Reports whether the attached child is currently running.
size_t read_stdout(std::vector< uint8_t > &buffer, size_t max_size)
Reads up to max_size bytes of buffered stdout into buffer.
bool read_all(std::vector< uint8_t > &buffer)
Drains all buffered stdout and stderr into buffer.
size_t bytes_available_stdout() const
Returns the number of buffered bytes available to read from stdout.
void close(bool force_kill_on_timeout=false)
Sends SIGTERM and optionally escalates to kill() after the wait timeout.
std::string get_working_directory() const
Returns the currently configured working directory.
bool read_all_error(std::vector< uint8_t > &buffer)
Drains all buffered stderr into buffer.
State get_state() const
Returns the lifecycle state of the currently attached child.
void set_environment(const EnvironmentMap &env_map)
Defines the environment that will be applied at the next start() call.
int get_exit_code() const
Returns the exit code of the most recent child process.
void set_working_directory(const std::string &dir)
Sets the working directory used at the next start() call.
bool read_all_output(std::vector< uint8_t > &buffer)
Drains all buffered stdout into buffer.
void start(const std::string &program, const std::vector< std::string > &arguments={})
Launches program with the given argument vector.
size_t write(const std::string &str, int timeout_ms=kDefaultWriteTimeoutMs)
Writes a string to the child's stdin.
void kill()
Forces immediate termination of the child via SIGKILL / TerminateProcess.
State
Coarse lifecycle stage of the child process.
Definition: process.h:117
void register_finished_callback(FinishedCallback &&callback)
Installs a callback fired when the child exits.
bool read_all(std::string &str)
Drains all buffered stdout and stderr into str.
void terminate()
Requests cooperative termination of the child.
Error
Last error recorded by a failing operation.
Definition: process.h:141
bool wait_for_started(int msecs=kDefaultWaitTimeoutMs)
Blocks until the child leaves kStartingState or the timeout elapses.
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.
bool can_read_line_stderr() const
Reports whether a newline-terminated line is fully buffered on stderr.
Pool-backed type-erased callables: copyable vlink::Function and move-only vlink::MoveFunction.
Cross-platform macros for visibility, branch hints, copy prevention, singletons and string helpers.
#define VLINK_EXPORT
Definition: macros.h:81
#define VLINK_DISALLOW_COPY_AND_ASSIGN(classname)
Deletes the copy constructor and copy-assignment operator of classname.
Definition: macros.h:174