parallel_pipeline

[algorithms.parallel_pipeline]

Strongly-typed interface for pipelined execution.

// Defined in header <oneapi/tbb/parallel_pipeline.h>

namespace oneapi {
    namespace tbb {

        void parallel_pipeline( size_t max_number_of_live_tokens, const filter<void,void>& filter_chain );
        void parallel_pipeline( size_t max_number_of_live_tokens, const filter<void,void>& filter_chain, task_group_context& context );

    } // namespace tbb
} // namespace oneapi

A parallel_pipeline algorithm represents pipelined application of a series of filters to a stream of items. Each filter operates in a particular mode: parallel, serial in-order, or serial out-of-order.

To build and run a pipeline from functors g₀, g₁, g₂, …, g_n, write:

parallel_pipeline( max_number_of_live_tokens,
                   make_filter<void,I1>(mode0,g0) &
                   make_filter<I1,I2>(mode1,g1) &
                   make_filter<I2,I3>(mode2,g2) &
                   ...
                   make_filter<In,void>(moden,gn) );

In general, the g_i functor should define its operator() to map objects of type I_i to objects of type I_i+1. Functor g₀ is a special case, because it notifies the pipeline when the end of an input stream is reached. Functor g₀ must be defined such that for a flow_control object fc, the expression g₀ (fc ) either returns the next value in the input stream, or invokes fc.stop() if the end of the input stream is reached and returns a dummy value.

Each filter should be specified by two template arguments. These arguments define filters input and output types. The first and last filters are special cases. Input type of the first filter must be void, output type of the last filter must be void too.

Before passing to parallel_pipeline, concatenate all filters to one(filter<void, void>) with filter::operator&(). The operator requires that the second template argument of its left operand matches the first template argument of its second operand.

The number of items processed in parallel depends on the structure of the pipeline and number of available threads. max_number_of_live_tokens sets the threshold for concurrently processed items.

If the context argument is specified, pipeline’s tasks are executed in this context. By default, the algorithm is executed in a bound context of its own.

Example

The following example uses parallel_pipeline to compute the root-mean-square of a sequence defined by [ first , last ).

float RootMeanSquare( float* first, float* last ) {
    float sum=0;
    parallel_pipeline( /*max_number_of_live_token=*/16,
        make_filter<void,float*>(
            filter::serial,
            [&](flow_control& fc)-> float*{
                if( first<last ) {
                    return first++;
                } else {
                    fc.stop();
                    return nullptr;
                }
            }
        ) &
        make_filter<float*,float>(
            filter::parallel,
            [](float* p){return (*p)*(*p);}
        ) &
        make_filter<float,void>(
            filter::serial,
            [&](float x) {sum+=x;}
        )
    );
    return sqrt(sum);
}

filter Class Template

• filter
  • filter_mode

flow_control Class

• flow_control

See also:

• task_group_context