tbb::filter Class Reference

A stage in a pipeline. More...

#include <pipeline.h>

Inheritance diagram for tbb::filter:

Collaboration diagram for tbb::filter:

Public Types
enum	mode { parallel = current_version | filter_is_out_of_order, serial_in_order = current_version | filter_is_serial, serial_out_of_order = current_version | filter_is_serial | filter_is_out_of_order, serial = serial_in_order }

Public Member Functions
bool	is_serial () const
	True if filter is serial. More...
bool	is_ordered () const
	True if filter must receive stream in order. More...
bool	is_bound () const
	True if filter is thread-bound. More...
bool	object_may_be_null ()
	true if an input filter can emit null More...
virtual void *	operator() (void *item)=0
	Operate on an item from the input stream, and return item for output stream. More...
virtual __TBB_EXPORTED_METHOD	~filter ()
	Destroy filter. More...
virtual void	finalize (void *)
	Destroys item if pipeline was cancelled. More...

Protected Member Functions
	filter (bool is_serial_)
	filter (mode filter_mode)
void __TBB_EXPORTED_METHOD	set_end_of_input ()

Static Protected Attributes
static const unsigned char	filter_is_serial = 0x1
	The lowest bit 0 is for parallel vs. serial. More...
static const unsigned char	filter_is_out_of_order = 0x1<<4
	4th bit distinguishes ordered vs unordered filters. More...
static const unsigned char	filter_is_bound = 0x1<<5
	5th bit distinguishes thread-bound and regular filters. More...
static const unsigned char	filter_may_emit_null = 0x1<<6
	6th bit marks input filters emitting small objects More...
static const unsigned char	exact_exception_propagation
	7th bit defines exception propagation mode expected by the application. More...
static const unsigned char	current_version = __TBB_PIPELINE_VERSION(5)
static const unsigned char	version_mask = 0x7<<1

Private Member Functions
bool	has_more_work ()
	has the filter not yet processed all the tokens it will ever see? More...
Private Member Functions inherited from tbb::internal::no_copy
	no_copy (const no_copy &)=delete
	no_copy ()=default

Static Private Member Functions
static filter *	not_in_pipeline ()
	Value used to mark "not in pipeline". More...

Private Attributes
filter *	next_filter_in_pipeline
	Pointer to next filter in the pipeline. More...
internal::input_buffer *	my_input_buffer
	Buffer for incoming tokens, or NULL if not required. More...
const unsigned char	my_filter_mode
	Storage for filter mode and dynamically checked implementation version. More...
filter *	prev_filter_in_pipeline
	Pointer to previous filter in the pipeline. More...
pipeline *	my_pipeline
	Pointer to the pipeline. More...
filter *	next_segment
	Pointer to the next "segment" of filters, or NULL if not required. More...

Friends
class	internal::stage_task
class	internal::pipeline_root_task
class	pipeline
class	thread_bound_filter

Detailed Description

A stage in a pipeline.

Definition at line 64 of file pipeline.h.

Member Enumeration Documentation

mode

enum tbb::filter::mode

Enumerator
parallel	processes multiple items in parallel and in no particular order
serial_in_order	processes items one at a time; all such filters process items in the same order
serial_out_of_order	processes items one at a time and in no particular order
serial	Deprecated: use serial_in_order instead

Definition at line 94 of file pipeline.h.

              {
        parallel = current_version | filter_is_out_of_order,
        serial_in_order = current_version | filter_is_serial,
        serial_out_of_order = current_version | filter_is_serial | filter_is_out_of_order,
        serial = serial_in_order
    };

Constructor & Destructor Documentation

filter() [1/2]

tbb::filter::filter ( bool  is_serial_ )

inlineexplicitprotected

Definition at line 105 of file pipeline.h.

                                       :
        next_filter_in_pipeline(not_in_pipeline()),
        my_input_buffer(NULL),
        my_filter_mode(static_cast<unsigned char>((is_serial_ ? serial : parallel) | exact_exception_propagation)),
        prev_filter_in_pipeline(not_in_pipeline()),
        my_pipeline(NULL),
        next_segment(NULL)
    {}

filter() [2/2]

tbb::filter::filter ( mode  filter_mode )

inlineexplicitprotected

Definition at line 114 of file pipeline.h.

                                        :
        next_filter_in_pipeline(not_in_pipeline()),
        my_input_buffer(NULL),
        my_filter_mode(static_cast<unsigned char>(filter_mode | exact_exception_propagation)),
        prev_filter_in_pipeline(not_in_pipeline()),
        my_pipeline(NULL),
        next_segment(NULL)
    {}

~filter()

tbb::filter::~filter ( )

virtual

Destroy filter.

If the filter was added to a pipeline, the pipeline must be destroyed first.

Definition at line 697 of file pipeline.cpp.

                {
    if ( (my_filter_mode & version_mask) >= __TBB_PIPELINE_VERSION(3) ) {
        if ( next_filter_in_pipeline != filter::not_in_pipeline() )
            my_pipeline->remove_filter(*this);
        else
            __TBB_ASSERT( prev_filter_in_pipeline == filter::not_in_pipeline(), "probably filter list is broken" );
    } else {
        __TBB_ASSERT( next_filter_in_pipeline==filter::not_in_pipeline(), "cannot destroy filter that is part of pipeline" );
    }
}

References __TBB_ASSERT, __TBB_PIPELINE_VERSION, and not_in_pipeline().

Here is the call graph for this function:

Member Function Documentation

finalize()

virtual void tbb::filter::finalize ( void *  )

inlinevirtual

Destroys item if pipeline was cancelled.

Required to prevent memory leaks. Note it can be called concurrently even for serial filters.

Reimplemented in tbb::interface6::internal::concrete_filter< T, void, Body >, and tbb::interface6::internal::concrete_filter< T, U, Body >.

Definition at line 159 of file pipeline.h.

{}

has_more_work()

bool tbb::filter::has_more_work ( )

private

has the filter not yet processed all the tokens it will ever see?

Definition at line 691 of file pipeline.cpp.

                           {
    __TBB_ASSERT(my_pipeline, NULL);
    __TBB_ASSERT(my_input_buffer, "has_more_work() called for filter with no input buffer");
    return (internal::tokendiff_t)(my_pipeline->token_counter - my_input_buffer->low_token) != 0;
}

References __TBB_ASSERT.

Referenced by tbb::internal::pipeline_root_task::execute().

Here is the caller graph for this function:

is_bound()

bool tbb::filter::is_bound ( ) const

inline

True if filter is thread-bound.

Definition at line 138 of file pipeline.h.

                          {
        return ( my_filter_mode & filter_is_bound )==filter_is_bound;
    }

References filter_is_bound, and my_filter_mode.

Referenced by tbb::internal::stage_task::execute(), and tbb::internal::pipeline_root_task::execute().

Here is the caller graph for this function:

is_ordered()

bool tbb::filter::is_ordered ( ) const

inline

True if filter must receive stream in order.

Definition at line 133 of file pipeline.h.

                            {
        return (my_filter_mode & (filter_is_out_of_order|filter_is_serial))==filter_is_serial;
    }

References filter_is_out_of_order, filter_is_serial, and my_filter_mode.

Referenced by tbb::internal::stage_task::execute().

Here is the caller graph for this function:

is_serial()

bool tbb::filter::is_serial ( ) const

inline

True if filter is serial.

Definition at line 128 of file pipeline.h.

                           {
        return bool( my_filter_mode & filter_is_serial );
    }

References filter_is_serial, and my_filter_mode.

Referenced by tbb::internal::stage_task::execute(), and tbb::internal::pipeline_root_task::execute().

Here is the caller graph for this function:

not_in_pipeline()

static filter* tbb::filter::not_in_pipeline ( )

inlinestaticprivate

Value used to mark "not in pipeline".

Definition at line 67 of file pipeline.h.

{ return reinterpret_cast<filter*>(intptr_t(-1)); }

Referenced by ~filter().

Here is the caller graph for this function:

object_may_be_null()

bool tbb::filter::object_may_be_null ( )

inline

true if an input filter can emit null

Definition at line 143 of file pipeline.h.

                              {
        return ( my_filter_mode & filter_may_emit_null ) == filter_may_emit_null;
    }

References filter_may_emit_null, and my_filter_mode.

Referenced by tbb::internal::stage_task::execute().

Here is the caller graph for this function:

operator()()

virtual void* tbb::filter::operator() ( void *  item )

pure virtual

Operate on an item from the input stream, and return item for output stream.

Returns NULL if filter is a sink.

Implemented in tbb::interface6::internal::concrete_filter< void, void, Body >, tbb::interface6::internal::concrete_filter< T, void, Body >, tbb::interface6::internal::concrete_filter< void, U, Body >, and tbb::interface6::internal::concrete_filter< T, U, Body >.

set_end_of_input()

void tbb::filter::set_end_of_input ( )

protected

Definition at line 708 of file pipeline.cpp.

                              {
    __TBB_ASSERT(my_input_buffer, NULL);
    __TBB_ASSERT(object_may_be_null(), NULL);
    if(is_serial()) {
        my_pipeline->end_of_input = true;
    } else {
        __TBB_ASSERT(my_input_buffer->end_of_input_tls_allocated, NULL);
        my_input_buffer->set_my_tls_end_of_input();
    }
}

References __TBB_ASSERT.

Referenced by tbb::interface6::internal::concrete_filter< void, U, Body >::operator()().

Here is the caller graph for this function:

Friends And Related Function Documentation

internal::pipeline_root_task

friend class internal::pipeline_root_task

friend

Definition at line 176 of file pipeline.h.

internal::stage_task

friend class internal::stage_task

friend

Definition at line 175 of file pipeline.h.

pipeline

friend class pipeline

friend

Definition at line 177 of file pipeline.h.

thread_bound_filter

friend class thread_bound_filter

friend

Definition at line 178 of file pipeline.h.

Member Data Documentation

current_version

const unsigned char tbb::filter::current_version = __TBB_PIPELINE_VERSION(5)

staticprotected

Definition at line 91 of file pipeline.h.

exact_exception_propagation

const unsigned char tbb::filter::exact_exception_propagation

staticprotected

Initial value:

=



            0x1<<7

7th bit defines exception propagation mode expected by the application.

Definition at line 84 of file pipeline.h.

filter_is_bound

const unsigned char tbb::filter::filter_is_bound = 0x1<<5

staticprotected

5th bit distinguishes thread-bound and regular filters.

Definition at line 78 of file pipeline.h.

Referenced by is_bound().

filter_is_out_of_order

const unsigned char tbb::filter::filter_is_out_of_order = 0x1<<4

staticprotected

4th bit distinguishes ordered vs unordered filters.

The bit was not set for parallel filters in TBB 2.1 and earlier, but is_ordered() function always treats parallel filters as out of order.

Definition at line 75 of file pipeline.h.

Referenced by is_ordered().

filter_is_serial

const unsigned char tbb::filter::filter_is_serial = 0x1

staticprotected

The lowest bit 0 is for parallel vs. serial.

Definition at line 70 of file pipeline.h.

Referenced by is_ordered(), is_serial(), and tbb::thread_bound_filter::thread_bound_filter().

filter_may_emit_null

const unsigned char tbb::filter::filter_may_emit_null = 0x1<<6

staticprotected

6th bit marks input filters emitting small objects

Definition at line 81 of file pipeline.h.

Referenced by object_may_be_null().

my_filter_mode

const unsigned char tbb::filter::my_filter_mode

private

Storage for filter mode and dynamically checked implementation version.

Definition at line 181 of file pipeline.h.

Referenced by tbb::internal::stage_task::execute(), is_bound(), is_ordered(), is_serial(), and object_may_be_null().

my_input_buffer

internal::input_buffer* tbb::filter::my_input_buffer

private

Buffer for incoming tokens, or NULL if not required.

The buffer is required if the filter is serial or follows a thread-bound one.

Definition at line 173 of file pipeline.h.

Referenced by tbb::internal::stage_task::execute(), and tbb::internal::pipeline_root_task::execute().

my_pipeline

pipeline* tbb::filter::my_pipeline

private

Pointer to the pipeline.

Definition at line 187 of file pipeline.h.

next_filter_in_pipeline

filter* tbb::filter::next_filter_in_pipeline

private

Pointer to next filter in the pipeline.

Definition at line 164 of file pipeline.h.

Referenced by tbb::internal::stage_task::execute().

next_segment

filter* tbb::filter::next_segment

private

Pointer to the next "segment" of filters, or NULL if not required.

In each segment, the first filter is not thread-bound but follows a thread-bound one.

Definition at line 191 of file pipeline.h.

Referenced by tbb::internal::pipeline_root_task::execute(), and tbb::internal::pipeline_root_task::pipeline_root_task().

prev_filter_in_pipeline

filter* tbb::filter::prev_filter_in_pipeline

private

Pointer to previous filter in the pipeline.

Definition at line 184 of file pipeline.h.

Referenced by tbb::internal::pipeline_root_task::execute().

version_mask

const unsigned char tbb::filter::version_mask = 0x7<<1

staticprotected

Definition at line 92 of file pipeline.h.

Referenced by tbb::internal::stage_task::execute().

---

The documentation for this class was generated from the following files:

• pipeline.h
• pipeline.cpp