Extending Qt Creator Manual | RunWorker

Extending Qt Creator Manual 4.4.0

# RunWorker Class

(ProjectExplorer::RunWorker)

The RunWorker class encapsulates a task that forms part, or the whole of the operation of a tool for a certain `RunConfiguration` according to some `RunMode`. More...

Header: | #include <RunWorker>

- List of all members, including inherited members

## Public Functions

| RunWorker(RunControl *runControl)
| ~RunWorker() override
void | addStartDependency(RunWorker *dependency)
void | addStopDependency(RunWorker *dependency)
void | appendMessage(const QString &msg, Utils::OutputFormat format)
IDevice::ConstPtr | device() const
void | initiateStart()
void | initiateStop()
bool | isEssential() const
void | recordData(const QString &channel, const QVariant &data)
QVariant | recordedData(const QString &channel) const
void | reportDone()
void | reportFailure(const QString &msg = QString())
void | reportStarted()
void | reportStopped()
RunControl * | runControl() const
Core::Id | runMode() const
const Runnable & | runnable() const
void | setDisplayName(const QString &id)
void | setEssential(bool essential)
void | setId(const QString &id)
void | setStartTimeout(int ms)
void | setStopTimeout(int ms)
void | setSupportsReRunning(bool reRunningSupported)
bool | supportsReRunning() const

## Signals

void | started()
void | stopped()

## Static Public Members

QString | userMessageForProcessError(QProcess::ProcessError, const QString &programName)

## Detailed Description

The RunWorker class encapsulates a task that forms part, or the whole of the operation of a tool for a certain `RunConfiguration` according to some `RunMode`.

A typical example for a `RunWorker` is a process, either the application process itself, or a helper process, such as a watchdog or a log parser.

A `RunWorker` has a simple state model covering the `Initialized`, `Starting`, `Running`, `Stopping`, and `Done` states.

In the course of the operation of tools several `RunWorkers` may co-operate and form a combined state that is presented to the user as `RunControl`, with direct interaction made possible through the buttons in the Application Output pane.

RunWorkers are typically created together with their RunControl. The startup order of RunWorkers under a RunControl can be specified by making a RunWorker dependent on others.

When a RunControl starts, it calls `initiateStart()` on RunWorkers with fulfilled dependencies until all workers are `Running`, or in case of short-lived helper tasks, `Done`.

A RunWorker can stop spontaneously, for example when the main application process ends. In this case, it typically calls `initiateStop()` on its RunControl, which in turn passes this to all sibling RunWorkers.

Pressing the stop button in the Application Output pane also calls `initiateStop` on the RunControl.

## Member Function Documentation

### RunWorker::RunWorker(RunControl *runControl)

Default constructs an instance of RunWorker.

### RunWorker::~RunWorker()

Destroys the instance of RunWorker.

### void RunWorker::addStartDependency(RunWorker *dependency)

### void RunWorker::addStopDependency(RunWorker *dependency)

### void RunWorker::appendMessage(const QString &msg, Utils::OutputFormat format)

### IDevice::ConstPtr RunWorker::device() const

### void RunWorker::initiateStart()

This function is called by the RunControl once all dependencies are fulfilled.

### void RunWorker::initiateStop()

This function is called by the RunControl in its own `initiateStop` implementation, which is triggered in response to pressing the stop button in the Application Output pane or on direct request of one of the sibling RunWorkers.

### bool RunWorker::isEssential() const

### void RunWorker::recordData(const QString &channel, const QVariant &data)

### QVariant RunWorker::recordedData(const QString &channel) const

### void RunWorker::reportDone()

This function can be called by a RunWorker implementation for short-lived tasks to notify its RunControl about this task being successful finished. Dependent startup tasks can proceed, in cases of spontaneous or scheduled stops, the effect is the same as `reportStopped()`.

### void RunWorker::reportFailure(const QString &msg = QString())

This function can be called by a RunWorker implementation to signal a problem in the operation in this worker. The RunControl will start to ramp down through initiateStop().

### void RunWorker::reportStarted()

This function has to be called by a RunWorker implementation to notify its RunControl about the successful start of this RunWorker.

The RunControl may start other RunWorkers in response.

### void RunWorker::reportStopped()

This function has to be called by a RunWorker implementation to notify its RunControl about this RunWorker having stopped.

The stop can be spontaneous, or in response to an initiateStop() or an initiateFinish() call.

The RunControl will adjust its global state in response.

### RunControl *RunWorker::runControl() const

### Core::Id RunWorker::runMode() const

### const Runnable &RunWorker::runnable() const

### void RunWorker::setDisplayName(const QString &id)

### void RunWorker::setEssential(bool essential)

See also isEssential().

### void RunWorker::setId(const QString &id)

### void RunWorker::setStartTimeout(int ms)

### void RunWorker::setStopTimeout(int ms)

### void RunWorker::setSupportsReRunning(bool reRunningSupported)

See also supportsReRunning().

### `[signal]` void RunWorker::started()

### `[signal]` void RunWorker::stopped()

### bool RunWorker::supportsReRunning() const

See also setSupportsReRunning().

### `[static]` QString RunWorker::userMessageForProcessError(QProcess::ProcessError, const QString &programName)