- Extending Qt Creator Manual
- TaskingSolution
- Group
- Extending Qt Creator Manual 11.0.1

# Group Class

class Tasking::Group

Group represents the basic element for composing declarative recipes describing how to execute and handle a nested tree of asynchronous tasks. More...

Header: | #include <solutions/tasking/tasktree.h>
Inherits: | Tasking::GroupItem

- List of all members, including inherited members

## Public Functions

| Group(std::initializer_list<GroupItem> children)
| Group(const QList<Tasking::GroupItem> &children)
Tasking::GroupItem | withTimeout(std::chrono::milliseconds timeout, const Tasking::GroupItem::GroupEndHandler &handler = {}) const

## Detailed Description

Group is a container for other group items. It encloses child tasks into one unit, which is seen by the group's parent as a single, asynchronous task. Since Group is of the GroupItem type, it may also be a child of Group.

Insert child tasks into the group by using aliased custom task names, such as, `ConcurrentCallTask<ResultType>` or `NetworkQueryTask`:

     const Group group {
         NetworkQueryTask(...),
         ConcurrentCallTask<int>(...)
     };

The group's behavior may be customized by inserting the items returned by parallelLimit() or workflowPolicy() functions:

     const Group group {
         parallel,
         continueOnError,
         NetworkQueryTask(...),
         NetworkQueryTask(...)
     };

The group may contain nested groups:

     const Group group {
         finishAllAndDone,
         NetworkQueryTask(...),
         Group {
             NetworkQueryTask(...),
             Group {
                 parallel,
                 NetworkQueryTask(...),
                 NetworkQueryTask(...),
             }
             ConcurrentCallTask<QString>(...)
         }
     };

The group may dynamically instantiate a custom storage structure, which may be used for inter-task data exchange:

     struct MyCustomStruct { QByteArray data; };

     TreeStorage<MyCustomStruct> storage;

     const auto onFirstSetup = [](NetworkQuery &task) { ... };
     const auto onFirstDone = [storage](const NetworkQuery &task) {
         // storage-> gives a pointer to MyCustomStruct instance,
         // created dynamically by the running task tree.
         storage->data = task.reply()->readAll();
     };
     const auto onSecondSetup = [storage](ConcurrentCall<QImage> &task) {
         // storage-> gives a pointer to MyCustomStruct. Since the group is sequential,
         // the stored MyCustomStruct was already updated inside the onFirstDone handler.
         const QByteArray storedData = storage->data;
     };

     const Group group {
         // When the group is entered by a running task tree, it creates MyCustomStruct
         // instance dynamically. It is later accessible from all handlers via
         // the *storage or storage-> operators.
         sequential,
         Storage(storage),
         NetworkQueryTask(onFirstSetup, onFirstDone),
         ConcurrentCallTask<QImage>(onSecondSetup)
     };

## Member Function Documentation

### Group::Group(std::initializer_list<GroupItem> children)

Constructs a group from std::initializer_list given by children.

This constructor is useful when all child items of the group are known at compile time:

     const Group group {
         finishAllAndDone,
         NetworkQueryTask(...),
         Group {
             NetworkQueryTask(...),
             Group {
                 parallel,
                 NetworkQueryTask(...),
                 NetworkQueryTask(...),
             }
             ConcurrentCallTask<QString>(...)
         }
     };

### Group::Group(const QList<Tasking::GroupItem> &children)

Constructs a group with a given list of children.

This constructor is useful when the child items of the group are not known at compile time, but later, at runtime:

     const QStringList sourceList = ...;

     QList<GroupItem> groupItems { parallel };

     for (const QString &source : sourceList) {
         const NetworkQueryTask task(...); // use source for setup handler
         groupItems << task;
     }

     const Group group(groupItems);

### Tasking::GroupItem Group::withTimeout(std::chrono::milliseconds timeout, const Tasking::GroupItem::GroupEndHandler &handler = {}) const

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

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