#include "tbb/pipeline.h"
class filter;
A filter represents a filter in a pipeline(0).There are three modes of filters:
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).
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 { 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 ); }; }
Member | Description |
---|---|
filter( mode filter_mode ) |
Constructs a filter of the specified mode. NoteIntel® 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. |