- Extending Qt Creator Manual
- TaskTree
- ExecutableItem
- Extending Qt Creator Manual 19.0.0-beta1

# QtTaskTree::ExecutableItem Class

class QtTaskTree::ExecutableItem

Base class for executable task items. More...

Header: | `#include <qtasktree.h>`
Inherits: | QtTaskTree::GroupItem
Inherited By: | QCustomTask, QSyncTask, QtTaskTree::Forever, and QtTaskTree::Group

- List of all members, including inherited members

Note: All functions in this class are reentrant.

## Public Functions

QtTaskTree::Group | withAccept(SenderSignalPairGetter &&getter) const
QtTaskTree::Group | withCancel(SenderSignalPairGetter &&getter, std::initializer_list<QtTaskTree::GroupItem> postCancelRecipe = {}) const
QtTaskTree::Group | withLog(const QString &logName) const
QtTaskTree::Group | withTimeout(std::chrono::milliseconds timeout, const std::function<void ()> &handler = {}) const

## Related Non-Members

QtTaskTree::Group | operator!(const QtTaskTree::ExecutableItem &item)
QtTaskTree::Group | operator&&(const QtTaskTree::ExecutableItem &first, const QtTaskTree::ExecutableItem &second)
QtTaskTree::Group | operator&&(const QtTaskTree::ExecutableItem &item, QtTaskTree::DoneResult result)
QtTaskTree::Group | operator||(const QtTaskTree::ExecutableItem &first, const QtTaskTree::ExecutableItem &second)
QtTaskTree::Group | operator||(const QtTaskTree::ExecutableItem &item, QtTaskTree::DoneResult result)

## Detailed Description

ExecutableItem provides an additional interface for items containing executable tasks. Use withTimeout() to attach a timeout to a task. Use withLog() to include debugging information about the task startup and the execution result.

## Member Function Documentation

### template <typename SenderSignalPairGetter> QtTaskTree::Group ExecutableItem::withAccept(SenderSignalPairGetter &&getter) const

Returns a copy of `this` ExecutableItem coupled with a signal awaiter. The passed getter is a function returning a `std::pair<QObject` *, PointerToMemberFunction> that describes the emitter and its awaiting signal.

When `this` ExecutableItem finishes with an error, the returned Group finishes immediately with an error, without awaiting for the awaiter's signal.

When `this` ExecutableItem finishes with success, the returned Group doesn't finish immediately but waits for the awaiting signal to be sent. After the awaiting signal is sent, the returned Group finishes with success. If the awaiting signal is sent before `this` ExecutableItem finishes, the awaiting phase is skipped and the returned Group finishes synchronously.

The connection to the awaiter's signal is established when `this` ExecutableItem is about to be started. If the awaiting signal was triggered before, this won't be noticed after `this` ExecutableItem is started.

### template <typename SenderSignalPairGetter> QtTaskTree::Group ExecutableItem::withCancel(SenderSignalPairGetter &&getter, std::initializer_list<QtTaskTree::GroupItem> postCancelRecipe = {}) const

Makes a copy of `this` ExecutableItem cancelable. The passed getter is a function returning a `std::pair<QObject` *, PointerToMemberFunction> that describes the emitter and its cancellation signal. When the cancellation signal is emitted, `this` ExecutableItem is canceled, an optionally provided postCancelRecipe is executed, and returned Group finishes with an error.

When `this` ExecutableItem finishes before the cancellation signal is emitted, the returned Group finishes immediately with the same result that `this` ExecutableItem finished. In this case the optionally provided postCancelRecipe is skipped.

The connection to the cancellation signal is established when `this` ExecutableItem is about to be started. If the cancelation signal was triggered before, this won't be noticed after `this` ExecutableItem is started.

### QtTaskTree::Group ExecutableItem::withLog(const QString &logName) const

Attaches a custom debug printout to a copy of `this` ExecutableItem, issued on task startup and after the task is finished, and returns the coupled item.

The debug printout includes a timestamp of the event (start or finish) and logName to identify the specific task in the debug log.

The finish printout contains the additional information whether the execution was synchronous or asynchronous, its result (the value described by the DoneWith enum), and the total execution time in milliseconds.

### QtTaskTree::Group ExecutableItem::withTimeout(std::chrono::milliseconds timeout, const std::function<void ()> &handler = {}) const

Attaches QTimeoutTask to a copy of `this` ExecutableItem, elapsing after timeout in milliseconds, with an optionally provided timeout handler, and returns the coupled item.

When the ExecutableItem finishes before timeout passes, the returned item finishes immediately with the task's result. Otherwise, handler is invoked (if provided), the task is canceled, and the returned item finishes with an error.

## Related Non-Members

### QtTaskTree::Group operator!(const QtTaskTree::ExecutableItem &item)

Returns a Group with the DoneResult of item negated.

If item reports DoneResult::Success, the returned item reports DoneResult::Error. If item reports DoneResult::Error, the returned item reports DoneResult::Success.

The returned item is equivalent to:

     Group {
         item,
         onGroupDone([](DoneWith doneWith) { return toDoneResult(doneWith == DoneWith::Error); })
     }

See also operator&&() and operator||().

### QtTaskTree::Group operator&&(const QtTaskTree::ExecutableItem &first, const QtTaskTree::ExecutableItem &second)

Returns a Group with first and second tasks merged with conjunction.

Both first and second tasks execute in sequence. If both tasks report DoneResult::Success, the returned item reports DoneResult::Success. Otherwise, the returned item reports DoneResult::Error.

The returned item is short-circuiting: if the first task reports DoneResult::Error, the second task is skipped, and the returned item reports DoneResult::Error immediately.

The returned item is equivalent to:

     Group { stopOnError, first, second }

Note: Parallel execution of conjunction in a short-circuit manner can be achieved with the following code: `Group { parallel, stopOnError, first, second }`. In this case: if the first finished task reports DoneResult::Error, the other task is canceled, and the group reports DoneResult::Error immediately.

See also operator||() and operator!().

### QtTaskTree::Group operator&&(const QtTaskTree::ExecutableItem &item, QtTaskTree::DoneResult result)

Returns the item task if the result is DoneResult::Success; otherwise returns the item task with its done result tweaked to DoneResult::Error.

The `task && DoneResult::Error` is an eqivalent to tweaking the task's done result into DoneResult::Error unconditionally.

This function overloads ExecutableItem::operator&&().

### QtTaskTree::Group operator||(const QtTaskTree::ExecutableItem &first, const QtTaskTree::ExecutableItem &second)

Returns a Group with first and second tasks merged with disjunction.

Both first and second tasks execute in sequence. If both tasks report DoneResult::Error, the returned item reports DoneResult::Error. Otherwise, the returned item reports DoneResult::Success.

The returned item is short-circuiting: if the first task reports DoneResult::Success, the second task is skipped, and the returned item reports DoneResult::Success immediately.

The returned item is equivalent to:

     Group { stopOnSuccess, first, second }

Note: Parallel execution of disjunction in a short-circuit manner can be achieved with the following code: `Group { parallel, stopOnSuccess, first, second }`. In this case if the first finished task reports DoneResult::Success, the other task is canceled, and the group reports DoneResult::Success immediately.

See also operator&&() and operator!().

### QtTaskTree::Group operator||(const QtTaskTree::ExecutableItem &item, QtTaskTree::DoneResult result)

Returns the item task if the result is DoneResult::Error; otherwise returns the item task with its done result tweaked to DoneResult::Success.

The `task || DoneResult::Success` is an eqivalent to tweaking the task's done result into DoneResult::Success unconditionally.

This function overloads ExecutableItem::operator||().