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® 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.

Para obtener más información sobre las optimizaciones del compilador, consulte el aviso sobre la optimización.