ExternalProcess Class Reference

A wrapper around QProcess to conveniently start an external program and forward its outputs. More...

#include <OpenMS/SYSTEM/ExternalProcess.h>

Inheritance diagram for ExternalProcess:

Collaboration diagram for ExternalProcess:

Public Types
enum class	RETURNSTATE { SUCCESS , NONZERO_EXIT , CRASH , FAILED_TO_START }
	result of calling an external executable More...
enum class	IO_MODE { NO_IO , READ_ONLY , WRITE_ONLY , READ_WRITE }
	Open mode for the process. More...

Public Member Functions
	ExternalProcess ()
	default Ctor; callbacks for stdout/stderr are empty More...
	ExternalProcess (std::function< void(const String &)> callbackStdOut, std::function< void(const String &)> callbackStdErr)
	set the callback functions to process stdout and stderr output when the external process generates it More...
	~ExternalProcess ()
	D'tor. More...
void	setCallbacks (std::function< void(const String &)> callbackStdOut, std::function< void(const String &)> callbackStdErr)
	re-wire the callbacks used during run() More...
RETURNSTATE	run (const QString &exe, const QStringList &args, const QString &working_dir, const bool verbose, String &error_msg, IO_MODE io_mode=IO_MODE::READ_WRITE)
	Runs a program and calls the callback functions from time to time if output from the external program is available. More...
ExternalProcess::RETURNSTATE	run (const QString &exe, const QStringList &args, const QString &working_dir, const bool verbose, IO_MODE io_mode=IO_MODE::READ_WRITE)
	Same as other overload, just without a returned error message. More...

Private Slots
void	processStdOut_ ()
void	processStdErr_ ()

Private Attributes
QProcess *	qp_
	pointer to avoid including the QProcess header here (it's huge) More...
std::function< void(const String &)>	callbackStdOut_
std::function< void(const String &)>	callbackStdErr_

Detailed Description

A wrapper around QProcess to conveniently start an external program and forward its outputs.

Use the custom Ctor to provide callback functions for stdout/stderr output or set them via setCallbacks().

Running an external program blocks the caller, so do not use this in a main GUI thread (unless you have some other means to tell the user that no interaction is possible at the moment).

@Note If you want QMessageBoxes to be shown if something went wrong, use ExternalProcessMBox as a convenient wrapper instead.

Member Enumeration Documentation

IO_MODE

enum IO_MODE

strong

Open mode for the process.

Enumerator
NO_IO	No read nor write access.
READ_ONLY
WRITE_ONLY
READ_WRITE

RETURNSTATE

enum RETURNSTATE

strong

result of calling an external executable

Enumerator
SUCCESS	everything went smoothly (exit-code = 0)
NONZERO_EXIT
CRASH	finished, but returned with an exit-code other than 0 ran, but crashed (segfault etc)
FAILED_TO_START	executable not found or not enough access rights for user

Constructor & Destructor Documentation

ExternalProcess() [1/2]

ExternalProcess

(

)

default Ctor; callbacks for stdout/stderr are empty

ExternalProcess() [2/2]

ExternalProcess	(	std::function< void(const String &)>	callbackStdOut,
		std::function< void(const String &)>	callbackStdErr
	)

set the callback functions to process stdout and stderr output when the external process generates it

~ExternalProcess()

~ExternalProcess

(

)

D'tor.

Member Function Documentation

processStdErr_

void processStdErr_ ( )

privateslot

processStdOut_

void processStdOut_ ( )

privateslot

run() [1/2]

ExternalProcess::RETURNSTATE run	(	const QString &	exe,
		const QStringList &	args,
		const QString &	working_dir,
		const bool	verbose,
		IO_MODE	io_mode = IO_MODE::READ_WRITE
	)

Same as other overload, just without a returned error message.

run() [2/2]

RETURNSTATE run	(	const QString &	exe,
		const QStringList &	args,
		const QString &	working_dir,
		const bool	verbose,
		String &	error_msg,
		IO_MODE	io_mode = IO_MODE::READ_WRITE
	)

Runs a program and calls the callback functions from time to time if output from the external program is available.

Parameters

	exe	The program to call (can contain spaces in path, no problem)
	args	A list of extra arguments (can be empty)
	verbose	Report the call command and errors via the callbacks (default: false)
	working_dir	Execute the external process in the given directory (relevant when relative input/output paths are given). Leave empty to use the current working directory.
[out]	error_string	Message to display to the user if something went wrong (if return != SUCCESS)
	io_mode	Open mode for the process (read access, write access, ...)

Returns

Did the external program succeed (SUCCESS) or did something go wrong?

setCallbacks()

void setCallbacks	(	std::function< void(const String &)>	callbackStdOut,
		std::function< void(const String &)>	callbackStdErr
	)

re-wire the callbacks used during run()

Member Data Documentation

callbackStdErr_

std::function<void(const String&)> callbackStdErr_

private

callbackStdOut_

std::function<void(const String&)> callbackStdOut_

private

qp_

QProcess* qp_

private

pointer to avoid including the QProcess header here (it's huge)