[For complete, up-to-date TBB information visit: http://www.ThreadingBuildingBlocks.org]
Summary
Abstract base class that performs pipelined execution.
Syntax
class pipeline;
Header
#include "tbb/pipeline.h"
Description
A pipeline represents pipelined application of a series of filters to a stream of items. Each filter is parallel or serial. See class filter ( 3.8.6) for details.
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 classes fi from filter. The constructor for fi specifies whether it is serial or not via the boolean parameter to the constructor for base class filter ( 3.8.6.1).
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.
Given sufficient processors and tokens, the throughput of the pipeline is limited to the throughput of the slowest serial filter.
A filter must be removed from the pipeline before destroying it. You can accomplish this by destroying the pipeline first, or calling pipeline::clear().
Members
namespace tbb {
class pipeline {
public:
pipeline();
virtual ~pipeline();
void add_filter( filter& f );
void run( size_t max_number_of_live_tokens );
void clear();
};
}
Effects
Constructs pipeline with no filters.
Effects
Remove all filters from the pipeline and destroy the pipeline
Effects
Append filter f to sequence of filters in the pipeline. The filter f must not already be in a pipeline.
Effects
Run 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.
Effects
Remove all filters from the pipeline.
Summary
Abstract base class that represents a filter in a pipeline.
Syntax
class filter;
Header
#include "tbb/pipeline.h"
Description
A filter represents a filter in a pipeline ( 3.8 ). A filter is parallel or serial. A parallel filter can process multiple items in parallel and possibly out of order. A serial filter processes items one at a time in the original stream order. Parallel filters are preferred when practical because they permit parallel speedup. Whether the filter is serial or parallel is specified by an argument to the constructor.
Class filter should only be used in conjunction with class pipeline ( 3.8).
Members
namespace tbb {
class filter {
protected:
filter( bool is_serial );
public:
bool is_serial() const;
virtual void* operator()( void* item ) = 0;
virtual ~filter();
};
}
Example
See the example filters MyInputFilter, MyTransformFilter, and MyOutputFilter in the tutorial (doc/Tutorial.pdf).
3.8.6.1 filter( bool is_serial )
Effects
Constructs a serial filter if is_serial is true, or a parallel filter if is_serial is false.
3.8.6.2 ~filter()
Effects
Destroys the filter. The filter must not be in a pipeline, otherwise memory might be corrupted. The debug version of the library raises an assertion failure if the filter is in a pipeline. Always clear or destroy the containing pipeline first. A way to remember this is that a pipeline acts like a container of Filters, and a C++ container usually does not allow destroying an item while it is in the container.
3.8.6.3 bool is_serial() const
Returns
True if filter is serial; false if filter is parallel.
3.8.6.4 virtual void* operator()( void * item )
Effects
The derived filter should override this method to process an item and return pointer to item to be processed by the next filter. The item parameter is NULL for the first filter in the pipeline.
Returns
The first filter in a pipeline should return NULL if there are no more items to process. The result of the last filter in a pipeline is ignored.
[For complete, up-to-date TBB information visit: http://www.ThreadingBuildingBlocks.org]