Intel(R) Threading Building Blocks Doxygen Documentation  version 4.2.3
tbb::filter Class Referenceabstract

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 voidoperator() (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 ()
 Allow default construction. More...
 

Static Private Member Functions

static filternot_in_pipeline ()
 Value used to mark "not in pipeline". More...
 

Private Attributes

filternext_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...
 
filterprev_filter_in_pipeline
 Pointer to previous filter in the pipeline. More...
 
pipelinemy_pipeline
 Pointer to the pipeline. More...
 
filternext_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 61 of file pipeline.h.

Member Enumeration Documentation

◆ 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 91 of file pipeline.h.

91  {
100  };
static const unsigned char filter_is_serial
The lowest bit 0 is for parallel vs. serial.
Definition: pipeline.h:67
processes items one at a time and in no particular order
Definition: pipeline.h:97
processes multiple items in parallel and in no particular order
Definition: pipeline.h:93
static const unsigned char current_version
Definition: pipeline.h:88
processes items one at a time; all such filters process items in the same order
Definition: pipeline.h:95
static const unsigned char filter_is_out_of_order
4th bit distinguishes ordered vs unordered filters.
Definition: pipeline.h:72

Constructor & Destructor Documentation

◆ filter() [1/2]

tbb::filter::filter ( bool  is_serial_)
inlineexplicitprotected

Definition at line 102 of file pipeline.h.

102  :
104  my_input_buffer(NULL),
105  my_filter_mode(static_cast<unsigned char>((is_serial_ ? serial : parallel) | exact_exception_propagation)),
107  my_pipeline(NULL),
108  next_segment(NULL)
109  {}
pipeline * my_pipeline
Pointer to the pipeline.
Definition: pipeline.h:184
filter * prev_filter_in_pipeline
Pointer to previous filter in the pipeline.
Definition: pipeline.h:181
filter * next_segment
Pointer to the next "segment" of filters, or NULL if not required.
Definition: pipeline.h:188
internal::input_buffer * my_input_buffer
Buffer for incoming tokens, or NULL if not required.
Definition: pipeline.h:170
static filter * not_in_pipeline()
Value used to mark "not in pipeline".
Definition: pipeline.h:64
const unsigned char my_filter_mode
Storage for filter mode and dynamically checked implementation version.
Definition: pipeline.h:178
processes multiple items in parallel and in no particular order
Definition: pipeline.h:93
filter * next_filter_in_pipeline
Pointer to next filter in the pipeline.
Definition: pipeline.h:156
static const unsigned char exact_exception_propagation
7th bit defines exception propagation mode expected by the application.
Definition: pipeline.h:81

◆ filter() [2/2]

tbb::filter::filter ( mode  filter_mode)
inlineexplicitprotected

Definition at line 111 of file pipeline.h.

111  :
113  my_input_buffer(NULL),
114  my_filter_mode(static_cast<unsigned char>(filter_mode | exact_exception_propagation)),
116  my_pipeline(NULL),
117  next_segment(NULL)
118  {}
pipeline * my_pipeline
Pointer to the pipeline.
Definition: pipeline.h:184
filter * prev_filter_in_pipeline
Pointer to previous filter in the pipeline.
Definition: pipeline.h:181
filter * next_segment
Pointer to the next "segment" of filters, or NULL if not required.
Definition: pipeline.h:188
internal::input_buffer * my_input_buffer
Buffer for incoming tokens, or NULL if not required.
Definition: pipeline.h:170
static filter * not_in_pipeline()
Value used to mark "not in pipeline".
Definition: pipeline.h:64
const unsigned char my_filter_mode
Storage for filter mode and dynamically checked implementation version.
Definition: pipeline.h:178
filter * next_filter_in_pipeline
Pointer to next filter in the pipeline.
Definition: pipeline.h:156
static const unsigned char exact_exception_propagation
7th bit defines exception propagation mode expected by the application.
Definition: pipeline.h:81

◆ ~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.

697  {
700  my_pipeline->remove_filter(*this);
701  else
702  __TBB_ASSERT( prev_filter_in_pipeline == filter::not_in_pipeline(), "probably filter list is broken" );
703  } else {
704  __TBB_ASSERT( next_filter_in_pipeline==filter::not_in_pipeline(), "cannot destroy filter that is part of pipeline" );
705  }
706 }
pipeline * my_pipeline
Pointer to the pipeline.
Definition: pipeline.h:184
#define __TBB_PIPELINE_VERSION(x)
Definition: pipeline.h:38
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:165
filter * prev_filter_in_pipeline
Pointer to previous filter in the pipeline.
Definition: pipeline.h:181
static const unsigned char version_mask
Definition: pipeline.h:89
static filter * not_in_pipeline()
Value used to mark "not in pipeline".
Definition: pipeline.h:64
const unsigned char my_filter_mode
Storage for filter mode and dynamically checked implementation version.
Definition: pipeline.h:178
filter * next_filter_in_pipeline
Pointer to next filter in the pipeline.
Definition: pipeline.h:156
void remove_filter(filter &filter_)
Remove filter from pipeline.
Definition: pipeline.cpp:616

References __TBB_ASSERT, __TBB_PIPELINE_VERSION, my_filter_mode, my_pipeline, next_filter_in_pipeline, not_in_pipeline(), prev_filter_in_pipeline, tbb::pipeline::remove_filter(), and version_mask.

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 156 of file pipeline.h.

156 {};

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

691  {
692  __TBB_ASSERT(my_pipeline, NULL);
693  __TBB_ASSERT(my_input_buffer, "has_more_work() called for filter with no input buffer");
694  return (internal::tokendiff_t)(my_pipeline->token_counter - my_input_buffer->low_token) != 0;
695 }
pipeline * my_pipeline
Pointer to the pipeline.
Definition: pipeline.h:184
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:165
long tokendiff_t
Definition: pipeline.h:41
internal::input_buffer * my_input_buffer
Buffer for incoming tokens, or NULL if not required.
Definition: pipeline.h:170
atomic< internal::Token > token_counter
Global counter of tokens.
Definition: pipeline.h:276

References __TBB_ASSERT, my_input_buffer, my_pipeline, and tbb::pipeline::token_counter.

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

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 135 of file pipeline.h.

135  {
137  }
const unsigned char my_filter_mode
Storage for filter mode and dynamically checked implementation version.
Definition: pipeline.h:178
static const unsigned char filter_is_bound
5th bit distinguishes thread-bound and regular filters.
Definition: pipeline.h:75

References filter_is_bound, and my_filter_mode.

Referenced by tbb::pipeline::add_filter(), tbb::internal::stage_task::execute(), tbb::internal::pipeline_root_task::execute(), tbb::thread_bound_filter::internal_process_item(), and tbb::pipeline::run().

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 130 of file pipeline.h.

130  {
132  }
static const unsigned char filter_is_serial
The lowest bit 0 is for parallel vs. serial.
Definition: pipeline.h:67
const unsigned char my_filter_mode
Storage for filter mode and dynamically checked implementation version.
Definition: pipeline.h:178
static const unsigned char filter_is_out_of_order
4th bit distinguishes ordered vs unordered filters.
Definition: pipeline.h:72

References filter_is_out_of_order, filter_is_serial, and my_filter_mode.

Referenced by tbb::pipeline::add_filter(), tbb::internal::stage_task::execute(), and tbb::thread_bound_filter::internal_process_item().

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 125 of file pipeline.h.

125  {
126  return bool( my_filter_mode & filter_is_serial );
127  }
static const unsigned char filter_is_serial
The lowest bit 0 is for parallel vs. serial.
Definition: pipeline.h:67
const unsigned char my_filter_mode
Storage for filter mode and dynamically checked implementation version.
Definition: pipeline.h:178

References filter_is_serial, and my_filter_mode.

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

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 64 of file pipeline.h.

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

Referenced by tbb::pipeline::add_filter(), tbb::pipeline::clear(), tbb::pipeline::remove_filter(), and ~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 140 of file pipeline.h.

140  {
142  }
const unsigned char my_filter_mode
Storage for filter mode and dynamically checked implementation version.
Definition: pipeline.h:178
static const unsigned char filter_may_emit_null
6th bit marks input filters emitting small objects
Definition: pipeline.h:78

References filter_may_emit_null, and my_filter_mode.

Referenced by tbb::pipeline::add_filter(), tbb::internal::stage_task::execute(), and set_end_of_input().

Here is the caller graph for this function:

◆ operator()()

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

◆ set_end_of_input()

void tbb::filter::set_end_of_input ( )
protected

Definition at line 708 of file pipeline.cpp.

708  {
711  if(is_serial()) {
712  my_pipeline->end_of_input = true;
713  } else {
714  __TBB_ASSERT(my_input_buffer->end_of_input_tls_allocated, NULL);
715  my_input_buffer->set_my_tls_end_of_input();
716  }
717 }
pipeline * my_pipeline
Pointer to the pipeline.
Definition: pipeline.h:184
bool object_may_be_null()
true if an input filter can emit null
Definition: pipeline.h:140
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:165
bool is_serial() const
True if filter is serial.
Definition: pipeline.h:125
internal::input_buffer * my_input_buffer
Buffer for incoming tokens, or NULL if not required.
Definition: pipeline.h:170
bool end_of_input
False until fetch_input returns NULL.
Definition: pipeline.h:279

References __TBB_ASSERT, tbb::pipeline::end_of_input, is_serial(), my_input_buffer, my_pipeline, and object_may_be_null().

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

Here is the call graph for this function:
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 173 of file pipeline.h.

◆ internal::stage_task

friend class internal::stage_task
friend

Definition at line 172 of file pipeline.h.

◆ pipeline

friend class pipeline
friend

Definition at line 174 of file pipeline.h.

◆ thread_bound_filter

friend class thread_bound_filter
friend

Definition at line 175 of file pipeline.h.

Member Data Documentation

◆ current_version

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

Definition at line 88 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 81 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 75 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 72 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 67 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 78 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 178 of file pipeline.h.

Referenced by tbb::pipeline::add_filter(), tbb::internal::stage_task::execute(), is_bound(), is_ordered(), is_serial(), object_may_be_null(), tbb::pipeline::remove_filter(), and ~filter().

◆ 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 170 of file pipeline.h.

Referenced by tbb::pipeline::add_filter(), tbb::pipeline::clear(), tbb::internal::stage_task::execute(), tbb::internal::pipeline_root_task::execute(), has_more_work(), tbb::thread_bound_filter::internal_process_item(), tbb::pipeline::remove_filter(), tbb::pipeline::run(), and set_end_of_input().

◆ my_pipeline

pipeline* tbb::filter::my_pipeline
private

◆ next_filter_in_pipeline

filter* tbb::filter::next_filter_in_pipeline
private

◆ 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 188 of file pipeline.h.

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

◆ prev_filter_in_pipeline

filter* tbb::filter::prev_filter_in_pipeline
private

◆ version_mask

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

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

Copyright © 2005-2019 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.