# pipeline Class

## Summary

Class that performs pipelined execution.

## Header

    #include "tbb/pipeline.h"

## Syntax

    class pipeline;

## Description

A `pipeline` 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 (MacDonald 2004).

A `pipeline` contains one or more filters, denoted here as fi , where i denotes the position of the filter in the pipeline. The pipeline starts with filter f0, followed by f1, f2, etc. The following steps describe how to use class pipeline.

1. Derive each class fi from filter. The constructor for fi specifies its mode as a parameter to the constructor for base class filter
2. Override virtual method filter::operator() to perform the filter's action on the item, and return a pointer to the item to be processed by the next filter. The first filter f0 generates the stream. It should return NULL if there are no more items in the stream. The return value for the last filter is ignored.
3. Create an instance of class pipeline.
4. Create instances of the filters fi and add them to the pipeline, in order from first to last. An instance of a filter can be added at most once to a pipeline. A filter should never be a member of more than one pipeline at a time.
5. Call method pipeline::run . The parameter `max_number_of_live_tokens` puts an upper bound on the number of stages that will be run concurrently. Higher values may increase concurrency at the expense of more memory consumption from having more items in flight. See the Tutorial, in the section on class pipeline, for more about effective use of `max_number_of_live_tokens`.

### Tip

Given sufficient processors and tokens, the throughput of the pipeline is limited to the throughput of the slowest serial filter.

### Note

Function `parallel_pipeline` provides a strongly typed lambda-friendly way to build and run pipelines.

## Members

    namespace tbb {
        class pipeline {
         public:
            pipeline();
            ~pipeline();
            void add_filter( filter& f );
            void run( size_t max_number_of_live_tokens [, task_group_context& group ] );
            void clear();
        };
    }

### Note

Though the current implementation declares the destructor virtual, do not rely on this detail. The virtual nature is deprecated and may disappear in future versions of Intel® Threading Building Blocks (Intel® TBB).

The following table provides additional information on the members of this template class.
Member | Description
--- | ---
pipeline() | Constructs pipeline with no filters.
~pipeline() | Removes all filters from the pipeline and destroys the pipeline.
void add_filter( filter& f ) | Appends filter `f` to sequence of filters in the pipeline. The filter `f` must not already be in a pipeline.
void run( size_t max_number_of_live_tokens[, task_group_context& group] ) | Runs the pipeline until the first filter returns NULL and each subsequent filter has processed all items from its predecessor. The number of items processed in parallel depends upon the structure of the pipeline and number of available threads. At most `max_number_of_live_tokens` are in flight at any given time. A pipeline can be run multiple times. It is safe to add stages between runs. Concurrent invocations of run on the same instance of pipeline are prohibited. If the `group` argument is specified, pipeline’s tasks are executed in this group. By default the algorithm is executed in a bound group of its own.
void clear() | Removes all filters from the pipeline.

Parent topic: Algorithms

- filter Class
- thread_bound_filter Class

## See Also

task_scheduler_init class