Storage Class

Detailed Description

The Storage class template is responsible for dynamically creating and destructing objects of the custom StorageStruct type. The creation and destruction are managed by the running task tree. If a Storage object is placed inside a Group element, the running task tree creates the StorageStruct object when the group is started and before the group's setup handler is called. Later, whenever any handler inside this group is called, the task tree activates the previously created instance of the StorageStruct object. This includes all tasks' and groups' setup and done handlers inside the group where the Storage object was placed, also within the nested groups. When a copy of the Storage object is passed to the handler via the lambda capture, the handler may access the instance activated by the running task tree via the operator->(), operator*(), or activeStorage() method. If two handlers capture the same Storage object, one of them may store a custom data there, and the other may read it afterwards. When the group is finished, the previously created instance of the StorageStruct object is destroyed after the group's done handler is called.

An example of data exchange between tasks:

const Storage<QString> storage;

const auto onFirstDone = [storage](const Task &task) {
    // Assings QString, taken from the first task result, to the active QString instance
    // of the Storage object.
    *storage = task.getResultAsString();
};

const auto onSecondSetup = [storage](Task &task) {
    // Reads QString from the active QString instance of the Storage object and use it to
    // configure the second task before start.
    task.configureWithString(*storage);
};

const Group root {
    // The running task tree creates QString instance when root in entered
    storage,
    // The done handler of the first task stores the QString in the storage
    TaskItem(..., onFirstDone),
    // The setup handler of the second task reads the QString from the storage
    TaskItem(onSecondSetup, ...)
};

Since the root group executes its tasks sequentially, the onFirstDone handler is always called before the onSecondSetup handler. This means that the QString data, read from the storage inside the onSecondSetup handler's body, has already been set by the onFirstDone handler. You can always rely on it in sequential execution mode.

The Storage internals are shared between all of its copies. That is why the copies of the Storage object inside the handlers' lambda captures still refer to the same Storage instance. You may place multiple Storage objects inside one Group element, provided that they do not include copies of the same Storage object. Otherwise, an assert is triggered at runtime that includes an error message. However, you can place copies of the same Storage object in different Group elements of the same recipe. In this case, the running task tree will create multiple instances of the StorageStruct objects (one for each copy) and storage shadowing will take place. Storage shadowing works in a similar way to C++ variable shadowing inside the nested blocks of code:

Storage<QString> storage;

const Group root {
    storage,                             // Top copy, 1st instance of StorageStruct
    onGroupSetup([storage] { ... }),     // Top copy is active
    Group {
        storage,                         // Nested copy, 2nd instance of StorageStruct,
                                         // shadows Top copy
        onGroupSetup([storage] { ... }), // Nested copy is active
    },
    Group {
        onGroupSetup([storage] { ... }), // Top copy is active
    }
};

The Storage objects may also be used for passing the initial data to the executed task tree, and for reading the final data out of the task tree before it finishes. To do this, use onStorageSetup() or onStorageDone(), respectively.