The process class manages an asynchronous process with redirected IO. More...

#include <process.hpp>

Public Types
enum class	io_redirection { redirect , none , closeall }
	IO redirection modes. More...

Public Member Functions
	process ()
	Creates instance for blocking I/O.

	process (thread_pool &pool, event_handler &handler)
	Creates instance with non-blocking event-based redirected communication. More...

	~process ()
	If process still running, calls process::kill()

	process (process const &)=delete

process &	operator= (process const &)=delete

bool	spawn (native_string const &cmd, std::vector< native_string > const &args=std::vector< native_string >(), io_redirection redirect_mode=io_redirection::redirect)
	Start the process. More...

bool	spawn (std::vector< native_string > const &command_with_args, io_redirection redirect_mode=io_redirection::redirect)

bool	spawn (impersonation_token const &it, native_string const &cmd, std::vector< native_string > const &args, io_redirection redirect_mode=io_redirection::redirect)
	Creates a process running under the user represented by the impersonation token.

void	kill ()

bool	stop (duration const &timeout={})
	Stops the spawned process. More...

rwresult	read (void *buffer, size_t len)
	Read data from process. More...

rwresult	write (void const *buffer, size_t len)
	Write data data process. More...

rwresult	write (std::string_view const &s)

void *	handle () const
	Returns the HANDLE of the process.

Detailed Description

The process class manages an asynchronous process with redirected IO.

No console window is being created.

To use, spawn the process and, since it's blocking, call read from a different thread.

Examples: nonblocking_process.cpp, and process.cpp.

Member Enumeration Documentation

◆ io_redirection

enum io_redirection

strong

IO redirection modes.

Enumerator

none

Redirect the child's stdin/out/err to pipes which will be interacted with through fz::process::read and fz::process::write.

closeall

Parent and child share the same stdin/out/err.

Redirects the child's stdin/out/err to pipes closed in the parent process

Constructor & Destructor Documentation

◆ process()

process	(	thread_pool &	pool,
		event_handler &	handler
	)

Creates instance with non-blocking event-based redirected communication.

Event semantic akin to

See also: fz::socket

Member Function Documentation

◆ kill()

void kill ( )

Forcefully kills the process.

SIGKILL on *nix, TerminateProcess on Windows.

◆ read()

rwresult read	(	void *	buffer,
		size_t	len
	)

Read data from process.

This function blocks

Returns: >0 Number of octets read, can be less than requested; 0 on EOF; -1 on error.

Examples: process.cpp.

◆ spawn()

bool spawn	(	native_string const &	cmd,
		std::vector< native_string > const &	args = `std::vector< native_string >()`,
		io_redirection	redirect_mode = `io_redirection::redirect`
	)

Start the process.

This function takes care of properly quoting and escaping the the program's path and its arguments. Fails if process has already been spawned.

Parameters

cmd	The path of the program to execute
args	The command-line arguments for the process.

Note: May return true even if the process cannot be started. In that case, trying to read from the process will fail with an error or EOF.

If the communication is non-blocking, a successful spawn doubles as process event with write flag

Examples: process.cpp.

◆ stop()

bool stop ( duration const & timeout = {} )

Stops the spawned process.

Waits until the process has quit, or the timeout has elapsed. Pass negative timeout to wait indefinately.

Returns whether the process has quit.

Sequence of events:

Closes write side of the communication pipe (after this, child will see EOF if reading from its stdin
On *nix, SIGTERM is also sent to the process
Function waits until the process has stopped or the timeout has expired.

◆ write()

rwresult write	(	void const *	buffer,
		size_t	len
	)

Write data data process.