Composite block works as a wrapper for a group of blocks or even another workflow and provides several special features.
Composite is a special block that can contain other blocks (nested blocks). In fact, every workflow in pSeven is a Composite block, and when you add blocks in Edit, you are editing contents of this block. This top-level Composite block is also called the workflow root.
Contents of Composite blocks inside the workflow are not shown by default — to view them, you will have to click the enter icon that appears on hover.
Expanded Composite block takes up the whole screen in Edit; to return back to the workflow after editing nested blocks, you can use the workflow breadcrumbs or click one of the exit icons that appear when you hover the input/output boundaries.
Composite blocks can be created in several ways:
- Add an empty Composite block from the Block Library, then expand it and edit its contents (add, configure, and link nested blocks).
- Add nested blocks first, select them and click on the edit toolbar to put selected blocks into a new Composite block (or select Group... from the edit toolbar context menu ). Note that the reverse operation, Ungroup is also available from the context menu.
- Import another workflow as a block (see section Workflow Import and Export).
While Composite blocks can be used just to organize the workflow (make complex workflows easier to read), their actual purpose is to provide such advanced functions as caching, parallelization, error handling, and re-using workflows (or their parts) as custom blocks. For this reason Composite blocks are better understood as sub-workflows that can have specific behavior. Note also that since a workflow is also a Composite block, certain settings (like parallelization or caching) can be applied to the entire workflow by configuring its root block.
Composite block can be configured to save values of its inputs and outputs, thus creating a cached region in the workflow. With cache enabled, nested blocks will start only when new input values received are not found in the cache. It means that if the cached Composite repeatedly receives the same input, actual calculation is performed only once, thus saving some processing time.
To enable caching, select Enable cache on the Configuration tab in block settings. The path to a cache file is optional:
- If a cache file is not specified, the block will use a memory cache which is cleared when the workflow finishes (so the cached data is not saved between workflow runs).
- If you specify a cache file, cached data is saved to disk and will be available in the next run. New run does not overwrite an existing cache but adds new entries and keeps old ones. A cache file is never cleared automatically — to delete the cached data, you have to clear the cache manually by the Clear cache button.
The path to the cache file can be absolute or relative to the project directory (as in the example above); a relative path starts with a dot (.). If you click and select a file in the project directory, pSeven converts the path to relative automatically.
Note that you can set the same cache file for two or more Composite blocks so they share the data. Shared cache works correctly only if all blocks have the same set of input and output ports. Otherwise each block will just store its cache data in the same file, but will never use the cache records added by other blocks.
- Caching tutorial
- Provides an example of cache usage in the Composite block.
Composite blocks support controlled parallelization: you can set the limit for parallel threads and select which input ports receive batches of values. When running, the block creates several parallel processes for its nested blocks and automatically distributes input data between them.
To enable parallelization, select Enable parallel execution and then use the drop-down list to select the parallel ports. These ports will accept only data batches (for example, a list of values). Each internal process created by the Composite block will work with one element of the batch at a time (data received to a parallel port is distributed between processes). If there are non-parallel ports, all processes will receive the same value from this port (data received to a non-parallel port is copied for each process). Non-parallel ports are useful for constants and other values that do not change between processes.
The limit for the nnumber of parallel processes is 4 by default, but you can set it to any value your system can handle. Note that this limit can actually be 1: in this case, the block will create only one process, but will accept data batches — which are in fact processed sequentially. This can serve as an alternative to creating a processing loop (see the Sampling Loop and Parallelization tutorials for more details).
- Parallelization tutorial
- Provides an example of configuring a parallel Composite block.
Composite blocks support the common error handling functions (see section Error Handling) with one notable exception: all errors from nested blocks are handled by the Composite block. It means that even if some block does not support error handling, you can work around it by placing this block inside a Composite and configuring error handling for the latter. If the nested block encounters an error, the workflow does not receive it directly: the error is resolved by the Composite block according to its behavior settings. Available behavior is the same as for other blocks that support the error handling feature.
- Error Handling
- More details on block error handling.
In pSeven, you can include an existing workflow as a block into the workflow you edit (import a workflow), or pick a block from your workflow and export it to a separate workflow. Both these functions rely on Composite blocks. The import and export commands are found in the toolbar menu in Edit.
Import Workflow... loads a workflow from file and includes it into the workflow you edit as a Composite block. If you select an existing Composite block, the workflow is imported into this block. If no block is selected, you are offered to create a new Composite block on import.
Export Workflow... is the opposite. If you select a Composite block in the workflow you edit, this block is exported to a new workflow. Export can also be used without selecting any block, if you are currently editing some Composite block — in this case it exports the block you edit.
For more details on workflow import and export, see section Workflow as a Block and the related tutorial.