filter Class


Abstract base class that represents a filter in a pipeline.


#include "tbb/pipeline.h"


class filter;


A filter represents a filter in a pipeline.There are three modes of filters:

  • A parallel filter can process multiple items in parallel and in no particular order.
  • A serial_out_of_order filter processes items one at a time, and in no particular order.
  • A serial_in_order filter processes items one at a time. The order in which items are processed is implicitly set by the first serial_in_order filter and respected by all other such filters in the pipeline.

The mode of filter is specified by an argument to the constructor. Parallel filters are preferred when practical because they permit parallel speedup. If a filter must be serial, the out of order variant is preferred when practical because it puts less constraints on processing order.

Class filter should only be used in conjunction with class pipeline.


Use a serial_in_order input filter if there are any subsequent serial_in_order stages that should process items in their input order.


Intel® Threading Building Blocks (Intel® TBB) 2.0 and prior treated parallel input stages as serial. Later versions of Intel TBB can execute a parallel input stage in parallel, so if you specify such a stage, ensure that its operator() is thread safe.


namespace tbb {
    class filter {
        enum mode {
            parallel = implementation-defined,
            serial_in_order = implementation-defined,
            serial_out_of_order = implementation-defined
        bool is_serial() const;
        bool is_ordered() const;
        virtual void* operator()( void* item ) = 0;
        virtual void finalize( void* item ) {}
        virtual ~filter();
        explicit filter( mode );
The following table provides additional information on the members of this template class.
Member Description
explicit filter( mode filter_mode )

Constructs a filter of the specified mode.


Intel TBB 2.1 and prior had a similar constructor with a bool argument is_serial. That constructor exists but is deprecated (see Compatibility Features in the Appendices).


Destroys the filter. If the filter is in a pipeline, it is automatically removed from that pipeline.

bool is_serial() const

Returns: False if filter mode is parallel; true otherwise.

bool is_ordered() const

Returns: True if filter mode is serial_in_order, false otherwise.

virtual void* operator()( void * item )

The derived filter should override this method to process an item and return a pointer to an 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.

virtual void finalize( void * item )

A pipeline can be cancelled by user demand or because of an exception. When a pipeline is cancelled, there may be items returned by a filter's operator() that have not yet been processed by the next filter. When a pipeline is cancelled, the next filter invokes finalize() on each item instead of operator(). In contrast to operator(), method finalize() does not return an item for further processing. A derived filter should override finalize() to perform proper cleanup for an item. A pipeline will not invoke any further methods on the item.

Returns: The default definition has no effect.

For more complete information about compiler optimizations, see our Optimization Notice.