Using a Pipeline
Instantiating a Pipeline
A Pipeline can be instantiated using the
Pipeline::Pipeline(bool auto_detach = false) constructor:
Metavision::Pipeline p();
A boolean argument auto_detach can be passed to the Pipeline at construction.
By default this argument is false. Setting it to true will result in each stage running in a separate thread:
Metavision::Pipeline p(true);
Pipeline Stage
Each processing stage in the pipeline is based on the BaseStage class, and
it can produce and/or consume data. When data are produced by one stage, they are forwarded to the next
stages.
The consumption of data is handled by the consuming callback which can be set by
calling the BaseStage::set_consuming_callback function.
The production of data is handled by the BaseStage::produce function, which
will call the consuming callback of the next stages.
For more details on implementing a custom stage, see the Example of Building a Pipeline with a Custom Stage.
Connecting Stages
Stages (derived from BaseStage) can be added to the pipeline by calling the
Pipeline::add_stage(std::unique_ptr<Stage> &&stage)
function.
It is also possible to add to the pipeline a synchronous algorithm.
This can be done by calling the Pipeline::add_algorithm_stage(std::unique_ptr<Algorithm> &&algo)
function.
In this case, a custom stage will be created: the added algorithm will be wrapped in the consuming callback and an
instance of AlgorithmStage class will be created.
When calling these functions, a new stage will be added to the pipeline, but no data connection will be done. This stage-to-stage connection must be done manually:
either directly when adding a new stage to the pipeline, by using these overload functions and providing the previous stage as an argument:
or by setting explicitly the previous stage for the current stage via the
BaseStage::set_previous_stage(BaseStage &prev_stage)function. This function will take care of updating both the forwards and backwards links (to the next and the previous stages).
Running the Pipeline
When the pipeline is set up, it can be run:
either by calling
Pipeline::run()function which will keep running until completion or until the pipeline is cancelled:p.run();
or by calling the
Pipeline::step()function which executes a step of the pipeline:while (p.step()) { // do whatever on the main thread... }
In the second case, between two calls of Pipeline::step(),
independent threads managed by the pipeline will keep running.
However, the callbacks for non-detachable stages (that is, stages that run in the main thread) will run only in the
Pipeline::step() method.
We provide several examples of pipelines in the following sections. We suggest starting with Example of Building a Simple Pipeline and then going to more complex examples.