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

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

Constructor & Destructor Documentation

◆ filter() [1/2]

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

Definition at line 106 of file pipeline.h.

106  :
108  my_input_buffer(NULL),
109  my_filter_mode(static_cast<unsigned char>((is_serial_ ? serial : parallel) | exact_exception_propagation)),
111  my_pipeline(NULL),
112  next_segment(NULL)
113  {}
static filter * not_in_pipeline()
Value used to mark "not in pipeline".
Definition: pipeline.h:68
const unsigned char my_filter_mode
Storage for filter mode and dynamically checked implementation version.
Definition: pipeline.h:182
filter * next_filter_in_pipeline
Pointer to next filter in the pipeline.
Definition: pipeline.h:160
filter * next_segment
Pointer to the next "segment" of filters, or NULL if not required.
Definition: pipeline.h:192
processes multiple items in parallel and in no particular order
Definition: pipeline.h:97
filter * prev_filter_in_pipeline
Pointer to previous filter in the pipeline.
Definition: pipeline.h:185
pipeline * my_pipeline
Pointer to the pipeline.
Definition: pipeline.h:188
static const unsigned char exact_exception_propagation
7th bit defines exception propagation mode expected by the application.
Definition: pipeline.h:85
internal::input_buffer * my_input_buffer
Buffer for incoming tokens, or NULL if not required.
Definition: pipeline.h:174

◆ filter() [2/2]

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

Definition at line 115 of file pipeline.h.

115  :
117  my_input_buffer(NULL),
118  my_filter_mode(static_cast<unsigned char>(filter_mode | exact_exception_propagation)),
120  my_pipeline(NULL),
121  next_segment(NULL)
122  {}
static filter * not_in_pipeline()
Value used to mark "not in pipeline".
Definition: pipeline.h:68
const unsigned char my_filter_mode
Storage for filter mode and dynamically checked implementation version.
Definition: pipeline.h:182
filter * next_filter_in_pipeline
Pointer to next filter in the pipeline.
Definition: pipeline.h:160
filter * next_segment
Pointer to the next "segment" of filters, or NULL if not required.
Definition: pipeline.h:192
filter * prev_filter_in_pipeline
Pointer to previous filter in the pipeline.
Definition: pipeline.h:185
pipeline * my_pipeline
Pointer to the pipeline.
Definition: pipeline.h:188
static const unsigned char exact_exception_propagation
7th bit defines exception propagation mode expected by the application.
Definition: pipeline.h:85
internal::input_buffer * my_input_buffer
Buffer for incoming tokens, or NULL if not required.
Definition: pipeline.h:174

◆ ~filter()

tbb::filter::~filter ( )
virtual

Destroy filter.

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

Definition at line 701 of file pipeline.cpp.

701  {
704  my_pipeline->remove_filter(*this);
705  else
706  __TBB_ASSERT( prev_filter_in_pipeline == filter::not_in_pipeline(), "probably filter list is broken" );
707  } else {
708  __TBB_ASSERT( next_filter_in_pipeline==filter::not_in_pipeline(), "cannot destroy filter that is part of pipeline" );
709  }
710 }
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:169
static filter * not_in_pipeline()
Value used to mark "not in pipeline".
Definition: pipeline.h:68
const unsigned char my_filter_mode
Storage for filter mode and dynamically checked implementation version.
Definition: pipeline.h:182
filter * next_filter_in_pipeline
Pointer to next filter in the pipeline.
Definition: pipeline.h:160
void remove_filter(filter &filter_)
Remove filter from pipeline.
Definition: pipeline.cpp:620
filter * prev_filter_in_pipeline
Pointer to previous filter in the pipeline.
Definition: pipeline.h:185
pipeline * my_pipeline
Pointer to the pipeline.
Definition: pipeline.h:188
#define __TBB_PIPELINE_VERSION(x)
Definition: pipeline.h:42
static const unsigned char version_mask
Definition: pipeline.h:93

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

160 {};

◆ 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 695 of file pipeline.cpp.

695  {
696  __TBB_ASSERT(my_pipeline, NULL);
697  __TBB_ASSERT(my_input_buffer, "has_more_work() called for filter with no input buffer");
698  return (internal::tokendiff_t)(my_pipeline->token_counter - my_input_buffer->low_token) != 0;
699 }
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:169
pipeline * my_pipeline
Pointer to the pipeline.
Definition: pipeline.h:188
atomic< internal::Token > token_counter
Global counter of tokens.
Definition: pipeline.h:280
long tokendiff_t
Definition: pipeline.h:45
internal::input_buffer * my_input_buffer
Buffer for incoming tokens, or NULL if not required.
Definition: pipeline.h:174

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

139  {
141  }
const unsigned char my_filter_mode
Storage for filter mode and dynamically checked implementation version.
Definition: pipeline.h:182
static const unsigned char filter_is_bound
5th bit distinguishes thread-bound and regular filters.
Definition: pipeline.h:79

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

134  {
136  }
const unsigned char my_filter_mode
Storage for filter mode and dynamically checked implementation version.
Definition: pipeline.h:182
static const unsigned char filter_is_out_of_order
4th bit distinguishes ordered vs unordered filters.
Definition: pipeline.h:76
static const unsigned char filter_is_serial
The lowest bit 0 is for parallel vs. serial.
Definition: pipeline.h:71

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

129  {
130  return bool( my_filter_mode & filter_is_serial );
131  }
const unsigned char my_filter_mode
Storage for filter mode and dynamically checked implementation version.
Definition: pipeline.h:182
static const unsigned char filter_is_serial
The lowest bit 0 is for parallel vs. serial.
Definition: pipeline.h:71

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

68 {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 144 of file pipeline.h.

144  {
146  }
static const unsigned char filter_may_emit_null
6th bit marks input filters emitting small objects
Definition: pipeline.h:82
const unsigned char my_filter_mode
Storage for filter mode and dynamically checked implementation version.
Definition: pipeline.h:182

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 712 of file pipeline.cpp.

712  {
715  if(is_serial()) {
716  my_pipeline->end_of_input = true;
717  } else {
718  __TBB_ASSERT(my_input_buffer->end_of_input_tls_allocated, NULL);
719  my_input_buffer->set_my_tls_end_of_input();
720  }
721 }
bool is_serial() const
True if filter is serial.
Definition: pipeline.h:129
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:169
bool object_may_be_null()
true if an input filter can emit null
Definition: pipeline.h:144
pipeline * my_pipeline
Pointer to the pipeline.
Definition: pipeline.h:188
internal::input_buffer * my_input_buffer
Buffer for incoming tokens, or NULL if not required.
Definition: pipeline.h:174
bool end_of_input
False until fetch_input returns NULL.
Definition: pipeline.h:283

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

◆ internal::stage_task

friend class internal::stage_task
friend

Definition at line 176 of file pipeline.h.

◆ pipeline

friend class pipeline
friend

Definition at line 178 of file pipeline.h.

◆ thread_bound_filter

friend class thread_bound_filter
friend

Definition at line 179 of file pipeline.h.

Member Data Documentation

◆ current_version

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

Definition at line 92 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 85 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 79 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 76 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 71 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 82 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 182 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 174 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 192 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.