Subprocess execution with pipe-based I/O. More...

#include <process.h>

Inheritance diagram for Process:

Collaboration diagram for Process:

[legend]

Public Types
enum	State { NotRunning = 0 , Starting , Running }
	Process state. More...

Public Types inherited from ObjectBase
using	SlotVariantFunc = std::function< void(const VariantList &)>
	Function type for invoking a slot with a list of Variants.

Public Member Functions
	Process (const Process &)=delete
	Deleted copy constructor (non-copyable).

Process &	operator= (const Process &)=delete
	Deleted copy assignment operator (non-copyable).

	Process (ObjectBase *parent=nullptr)
	Default constructor.

	~Process ()
	Destructor. Kills the child process if still running.

const String &	program () const
	Returns the program path.

void	setProgram (const String &program)
	Sets the program to execute.

const List< String > &	arguments () const
	Returns the argument list.

void	setArguments (const List< String > &args)
	Sets the argument list for the subprocess.

const FilePath &	workingDirectory () const
	Returns the working directory for the subprocess.

void	setWorkingDirectory (const FilePath &dir)
	Sets the working directory for the subprocess.

const Map< String, String > &	environment () const
	Returns the environment variables for the subprocess.

void	setEnvironment (const Map< String, String > &env)
	Sets the environment variables for the subprocess.

Error	start ()
	Starts the subprocess using the previously set program and arguments.

Error	start (const String &program, const List< String > &args)
	Convenience: sets program and arguments, then starts.

Error	waitForStarted (unsigned int timeoutMs=0)
	Blocks until the subprocess has started or the timeout expires.

Error	waitForFinished (unsigned int timeoutMs=0)
	Blocks until the subprocess has finished or the timeout expires.

int	exitCode () const
	Returns the exit code of the finished process.

bool	isRunning () const
	Returns true if the subprocess is currently running.

State	state () const
	Returns the current process state.

pid_t	pid () const
	Returns the child process ID.

void	kill ()
	Sends SIGKILL to the child process.

void	terminate ()
	Sends SIGTERM to the child process.

ssize_t	writeToStdin (const void *buf, size_t bytes)
	Writes data to the child's stdin pipe.

Buffer	readAllStdout ()
	Reads all available data from the child's stdout.

Buffer	readAllStderr ()
	Reads all available data from the child's stderr.

void	closeWriteChannel ()
	Closes the write end of the stdin pipe.

	PROMEKI_SIGNAL (started)
	Emitted when the subprocess starts running.

	PROMEKI_SIGNAL (finished, int)
	Emitted when the subprocess finishes (carries the exit code).

	PROMEKI_SIGNAL (readyReadStdout)
	Emitted when data is available on the child's stdout.

	PROMEKI_SIGNAL (readyReadStderr)
	Emitted when data is available on the child's stderr.

	PROMEKI_SIGNAL (errorOccurred, Error)
	Emitted when an error occurs during subprocess execution.

Public Member Functions inherited from ObjectBase
	ObjectBase (ObjectBase *p=nullptr)
	Default ObjectBase constructor.

virtual	~ObjectBase ()
	Destructor. Emits aboutToDestroy, detaches from parent, and destroys children.

ObjectBase *	parent () const
	Returns the parent object, if one. nullptr if none.

void	setParent (ObjectBase *p)
	Sets the parent of this object. If the object already has a parent, it will be removed as a child from the old parent and added as a child to the new one.

const ObjectBaseList &	childList () const
	Returns a list of children of this object.

template<typename... Args>
int	registerSlot (Slot< Args... > *slot)
	Registers a slot with this object and assigns it an ID.

EventLoop *	eventLoop () const
	Returns the EventLoop this object is affiliated with.

void	moveToThread (EventLoop *loop)
	Changes the EventLoop affinity of this object.

int	startTimer (unsigned int intervalMs, bool singleShot=false)
	Starts a timer on this object's EventLoop.

void	stopTimer (int timerId)
	Stops a timer previously started with startTimer().

template<typename... Args>
PROMEKI_NAMESPACE_BEGIN void	connect (Signal< Args... > signal, Slot< Args... > slot)

Additional Inherited Members
Static Public Member Functions inherited from ObjectBase
static const MetaInfo &	metaInfo ()
	Returns the MetaInfo for the ObjectBase class.

template<typename... Args>
static void	connect (Signal< Args... > signal, Slot< Args... > slot)
	connects a signal and slot together. This function assumes both the signal and slot exist in a ObjectBase or derived object

Public Attributes inherited from ObjectBase
Signal< ObjectBase * >	aboutToDestroySignal = Signal< ObjectBase * >(this, aboutToDestroySignalName)

Static Public Attributes inherited from ObjectBase
static constexpr const char *	aboutToDestroySignalName = PROMEKI_STRINGIFY( aboutToDestroy ) "(" PROMEKI_STRINGIFY_ARGS( ObjectBase * ) ")"

static SignalMeta	aboutToDestroySignalMeta = SignalMeta(metaInfo(), aboutToDestroySignalName)

Protected Member Functions inherited from ObjectBase
ObjectBase *	signalSender ()
	Returns the ObjectBase that emitted the signal currently being handled.

virtual void	event (Event *e)
	Called by EventLoop to deliver events to this object.

virtual void	timerEvent (TimerEvent *e)
	Called when a timer fires for this object.

Detailed Description

Subprocess execution with pipe-based I/O.

Wraps subprocess creation and management using pipe() + fork() + exec() on POSIX platforms. Provides access to the child process's stdin, stdout, and stderr via pipe-based I/O methods.

On unsupported platforms (e.g. WASM/Emscripten), start() returns Error::NotSupported.

Process proc;
proc.setProgram("/usr/bin/echo");
proc.setArguments({"Hello", "world"});
Error err = proc.start();
if(err.isOk()) {
    proc.waitForFinished();
    Buffer output = proc.readAllStdout();
}

Member Enumeration Documentation

◆ State

enum Process::State

Process state.

Enumerator
NotRunning	Process is not running.
Starting	Process is being started.
Running	Process is running.

Constructor & Destructor Documentation

◆ Process()

Process::Process ( ObjectBase * parent = nullptr )

Default constructor.

Parameters

parent The parent object, or nullptr.

Member Function Documentation

◆ arguments()

const List< String > & Process::arguments ( ) const

inline

Returns the argument list.

Returns: A const reference to the argument list.

◆ closeWriteChannel()

void Process::closeWriteChannel ( )

Closes the write end of the stdin pipe.

Signals EOF to the child's stdin.

◆ environment()

const Map< String, String > & Process::environment ( ) const

inline

Returns the environment variables for the subprocess.

Returns: A const reference to the environment map.

◆ exitCode()

int Process::exitCode ( ) const

inline

Returns the exit code of the finished process.

Only valid after the process has finished.

Returns: The exit code, or -1 if the process has not finished.

◆ isRunning()

bool Process::isRunning ( ) const

inline

Returns true if the subprocess is currently running.

Returns: true if running.

◆ pid()

pid_t Process::pid ( ) const

inline

Returns the child process ID.

Only valid while the process is running or has recently finished.

Returns: The PID, or -1 if no process has been started.

◆ program()

const String & Process::program ( ) const

inline

Returns the program path.

Returns: A const reference to the program string.

◆ PROMEKI_SIGNAL() [1/5]

Process::PROMEKI_SIGNAL	(	errorOccurred	,
		Error
	)

Emitted when an error occurs during subprocess execution.

Signal:

◆ PROMEKI_SIGNAL() [2/5]

Process::PROMEKI_SIGNAL	(	finished	,
		int
	)

Emitted when the subprocess finishes (carries the exit code).

Signal:

◆ PROMEKI_SIGNAL() [3/5]

Process::PROMEKI_SIGNAL ( readyReadStderr )

Emitted when data is available on the child's stderr.

Signal:

◆ PROMEKI_SIGNAL() [4/5]

Process::PROMEKI_SIGNAL ( readyReadStdout )

Emitted when data is available on the child's stdout.

Signal:

◆ PROMEKI_SIGNAL() [5/5]

Process::PROMEKI_SIGNAL ( started )

Emitted when the subprocess starts running.

Signal:

◆ readAllStderr()

Buffer Process::readAllStderr ( )

Reads all available data from the child's stderr.

Returns: A Buffer containing the stderr data.

◆ readAllStdout()

Buffer Process::readAllStdout ( )

Reads all available data from the child's stdout.

Returns: A Buffer containing the stdout data.

◆ setArguments()

void Process::setArguments ( const List< String > & args )

inline

Sets the argument list for the subprocess.

Parameters

args	The arguments to pass to the program.

◆ setEnvironment()

void Process::setEnvironment ( const Map< String, String > & env )

inline

Sets the environment variables for the subprocess.

If empty, the child inherits the parent's environment.

Parameters

env	A map of environment variable names to values.

◆ setProgram()

void Process::setProgram ( const String & program )

inline

Sets the program to execute.

Parameters

program Path to the executable.

◆ setWorkingDirectory()

void Process::setWorkingDirectory ( const FilePath & dir )

inline

Sets the working directory for the subprocess.

If empty, the child inherits the parent's working directory.

Parameters

dir	The directory to run the subprocess in.

◆ start() [1/2]

Error Process::start ( )

Starts the subprocess using the previously set program and arguments.

Returns: Error::Ok on success, or an error if the process cannot be started.

◆ start() [2/2]

Error Process::start	(	const String &	program,
		const List< String > &	args
	)

Convenience: sets program and arguments, then starts.

Parameters

program	Path to the executable.
args	The arguments to pass to the program.

Returns: Error::Ok on success, or an error if the process cannot be started.

◆ state()

State Process::state ( ) const

inline

Returns the current process state.

Returns: The State enumeration value.

◆ waitForFinished()

Error Process::waitForFinished ( unsigned int timeoutMs = 0 )

Blocks until the subprocess has finished or the timeout expires.

Reads any remaining stdout/stderr data and collects the exit status.

Parameters

timeoutMs Maximum time to wait in milliseconds (0 = wait indefinitely).

Returns: Error::Ok if finished, Error::Timeout on expiry.

◆ waitForStarted()

Error Process::waitForStarted ( unsigned int timeoutMs = 0 )

Blocks until the subprocess has started or the timeout expires.

Parameters

timeoutMs Maximum time to wait in milliseconds (0 = wait indefinitely).

Returns: Error::Ok if started, Error::Timeout on expiry.

◆ workingDirectory()

const FilePath & Process::workingDirectory ( ) const

inline

Returns the working directory for the subprocess.

Returns: A const reference to the working directory path.

◆ writeToStdin()

ssize_t Process::writeToStdin	(	const void *	buf,
		size_t	bytes
	)

Writes data to the child's stdin pipe.

Parameters

buf	Pointer to the data to write.
bytes	Number of bytes to write.

Returns: The number of bytes written, or -1 on error.

The documentation for this class was generated from the following file:

include/promeki/core/process.h

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ State

Constructor & Destructor Documentation

◆ Process()

Member Function Documentation

◆ arguments()

◆ closeWriteChannel()

◆ environment()

◆ exitCode()

◆ isRunning()

◆ pid()

◆ program()

◆ PROMEKI_SIGNAL() [1/5]

◆ PROMEKI_SIGNAL() [2/5]

◆ PROMEKI_SIGNAL() [3/5]

◆ PROMEKI_SIGNAL() [4/5]

◆ PROMEKI_SIGNAL() [5/5]

◆ readAllStderr()

◆ readAllStdout()

◆ setArguments()

◆ setEnvironment()

◆ setProgram()

◆ setWorkingDirectory()

◆ start() [1/2]

◆ start() [2/2]

◆ state()

◆ waitForFinished()

◆ waitForStarted()

◆ workingDirectory()

◆ writeToStdin()