OpenMS
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:
[legend]
Collaboration diagram for ExternalProcess:
[legend]

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 () override
 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

QProcessqp_
 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).

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]

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 ( )
override

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
exeThe program to call (can contain spaces in path, no problem)
argsA list of extra arguments (can be empty)
working_dirExecute the external process in the given directory (relevant when relative input/output paths are given). Leave empty to use the current working directory.
verboseReport the call command and errors via the callbacks (default: false)
[out]error_msgMessage to display to the user if something went wrong (if return != SUCCESS)
io_modeOpen 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)