# filter Class

## Summary

Abstract base class that represents a filter in a pipeline.

## Header

    #include "tbb/pipeline.h"

## Syntax

    class filter;

## Description

A `filter` represents a filter in a `pipeline`(0).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. All `serial_in_order` filters in a pipeline process items in the same order.

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 contraints on processing order.

Class `filter` should only be used in conjunction with class `pipeline`(0).

### Tip

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

### Caution

Intel(R) 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.

## Members

    namespace tbb {
        class filter {
        public:
            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();
        protected:
            filter( mode );
        };
    }

The following table provides additional information on the members of this template class.
Member | Description
--- | ---
filter( mode filter_mode ) | Constructs a filter of the specified mode. ### Note 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).
~filter() | 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.

Parent topic: pipeline Class

## See Also

Compatibility Features