tbb::filter Class Referenceabstract
Algorithms

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
};
tbb::filter::filter_is_out_of_order
static const unsigned char filter_is_out_of_order
4th bit distinguishes ordered vs unordered filters.
Definition: pipeline.h:75
tbb::filter::current_version
static const unsigned char current_version
Definition: pipeline.h:91
tbb::filter::parallel
@ parallel
processes multiple items in parallel and in no particular order
Definition: pipeline.h:96
tbb::filter::serial
@ serial
Definition: pipeline.h:102
tbb::filter::serial_in_order
@ serial_in_order
processes items one at a time; all such filters process items in the same order
Definition: pipeline.h:98
tbb::filter::serial_out_of_order
@ serial_out_of_order
processes items one at a time and in no particular order
Definition: pipeline.h:100
tbb::filter::filter_is_serial
static const unsigned char filter_is_serial
The lowest bit 0 is for parallel vs. serial.
Definition: pipeline.h:70

## Constructor & Destructor Documentation

## filter() [1/2]

tbb::filter::filter | ( | bool | is_serial_ | ) |

inline explicit protected

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)
{}
tbb::filter::my_input_buffer
internal::input_buffer * my_input_buffer
Buffer for incoming tokens, or NULL if not required.
Definition: pipeline.h:173
tbb::filter::next_filter_in_pipeline
filter * next_filter_in_pipeline
Pointer to next filter in the pipeline.
Definition: pipeline.h:164
tbb::filter::not_in_pipeline
static filter * not_in_pipeline()
Value used to mark "not in pipeline".
Definition: pipeline.h:67
tbb::filter::exact_exception_propagation
static const unsigned char exact_exception_propagation
7th bit defines exception propagation mode expected by the application.
Definition: pipeline.h:84
tbb::filter::next_segment
filter * next_segment
Pointer to the next "segment" of filters, or NULL if not required.
Definition: pipeline.h:191
tbb::filter::my_filter_mode
const unsigned char my_filter_mode
Storage for filter mode and dynamically checked implementation version.
Definition: pipeline.h:181
tbb::filter::prev_filter_in_pipeline
filter * prev_filter_in_pipeline
Pointer to previous filter in the pipeline.
Definition: pipeline.h:184
tbb::filter::my_pipeline
pipeline * my_pipeline
Pointer to the pipeline.
Definition: pipeline.h:187

## filter() [2/2]

tbb::filter::filter | ( | mode | filter_mode | ) |

inline explicit protected

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" );
}
}
__TBB_PIPELINE_VERSION
#define __TBB_PIPELINE_VERSION(x)
Definition: pipeline.h:41
__TBB_ASSERT
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:165
tbb::filter::version_mask
static const unsigned char version_mask
Definition: pipeline.h:92

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 * |  | ) |

inline virtual

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;
}
tbb::internal::tokendiff_t
long tokendiff_t
Definition: pipeline.h:44
tbb::internal::input_buffer::low_token
Token low_token
Lowest token that can start executing.
Definition: pipeline.cpp:69

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;
}
tbb::filter::filter_is_bound
static const unsigned char filter_is_bound
5th bit distinguishes thread-bound and regular filters.
Definition: pipeline.h:78

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 | ( |  | ) |

inline static private

Value used to mark "not in pipeline".

Definition at line 67 of file pipeline.h.

{ return reinterpret_cast<filter*>(intptr_t(-1)); }
tbb::filter::filter
filter(bool is_serial_)
Definition: pipeline.h:105

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;
}
tbb::filter::filter_may_emit_null
static const unsigned char filter_may_emit_null
6th bit marks input filters emitting small objects
Definition: pipeline.h:81

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< T, void, Body >, tbb::interface6::internal::concrete_filter< T, U, Body >, tbb::interface6::internal::concrete_filter< void, void, Body >, and tbb::interface6::internal::concrete_filter< void, 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();
}
}
tbb::filter::object_may_be_null
bool object_may_be_null()
true if an input filter can emit null
Definition: pipeline.h:143
tbb::filter::is_serial
bool is_serial() const
True if filter is serial.
Definition: pipeline.h:128
tbb::internal::input_buffer::end_of_input_tls_allocated
bool end_of_input_tls_allocated
Definition: pipeline.cpp:94
tbb::internal::input_buffer::set_my_tls_end_of_input
void set_my_tls_end_of_input()
Definition: pipeline.cpp:228

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)

static protected

Definition at line 91 of file pipeline.h.

## exact_exception_propagation

const unsigned char tbb::filter::exact_exception_propagation

static protected

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

static protected

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

static protected

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

static protected

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

static protected

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

static protected

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

Copyright © 2005-2020 Intel Corporation. All Rights Reserved.

Intel, Pentium, Intel Xeon, Itanium, Intel XScale and VTune are registered trademarks or trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

* Other names and brands may be claimed as the property of others.