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:

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:;
  • 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.