Intel(R) Threading Building Blocks Doxygen Documentation  version 4.2.3
tbb::thread_bound_filter Class Reference

A stage in a pipeline served by a user thread. More...

#include <pipeline.h>

Inheritance diagram for tbb::thread_bound_filter:
Collaboration diagram for tbb::thread_bound_filter:

Public Types

enum  result_type { success, item_not_available, end_of_stream }
 
- Public Types inherited from tbb::filter
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

result_type __TBB_EXPORTED_METHOD try_process_item ()
 If a data item is available, invoke operator() on that item. More...
 
result_type __TBB_EXPORTED_METHOD process_item ()
 Wait until a data item becomes available, and invoke operator() on that item. More...
 
- Public Member Functions inherited from tbb::filter
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

 thread_bound_filter (mode filter_mode)
 
- Protected Member Functions inherited from tbb::filter
 filter (bool is_serial_)
 
 filter (mode filter_mode)
 
void __TBB_EXPORTED_METHOD set_end_of_input ()
 

Private Member Functions

result_type internal_process_item (bool is_blocking)
 Internal routine for item processing. More...
 

Additional Inherited Members

- Static Protected Attributes inherited from tbb::filter
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
 

Detailed Description

A stage in a pipeline served by a user thread.

Definition at line 197 of file pipeline.h.

Member Enumeration Documentation

◆ result_type

Enumerator
success 
item_not_available 
end_of_stream 

Definition at line 199 of file pipeline.h.

199  {
200  // item was processed
201  success,
202  // item is currently not available
204  // there are no more items to process
206  };

Constructor & Destructor Documentation

◆ thread_bound_filter()

tbb::thread_bound_filter::thread_bound_filter ( mode  filter_mode)
inlineexplicitprotected

Definition at line 208 of file pipeline.h.

208  :
209  filter(static_cast<mode>(filter_mode | filter::filter_is_bound))
210  {
211  __TBB_ASSERT(filter_mode & filter::filter_is_serial, "thread-bound filters must be serial");
212  }
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:169
static const unsigned char filter_is_bound
5th bit distinguishes thread-bound and regular filters.
Definition: pipeline.h:79
static const unsigned char filter_is_serial
The lowest bit 0 is for parallel vs. serial.
Definition: pipeline.h:71
filter(bool is_serial_)
Definition: pipeline.h:106

References __TBB_ASSERT, and tbb::filter::filter_is_serial.

Member Function Documentation

◆ internal_process_item()

thread_bound_filter::result_type tbb::thread_bound_filter::internal_process_item ( bool  is_blocking)
private

Internal routine for item processing.

Definition at line 731 of file pipeline.cpp.

731  {
732  __TBB_ASSERT(my_pipeline != NULL,"It's not supposed that process_item is called for a filter that is not in a pipeline.");
733  internal::task_info info;
734  info.reset();
735 
737  return end_of_stream;
738 
739  if( !prev_filter_in_pipeline ) {
741  return end_of_stream;
742  while( my_pipeline->input_tokens == 0 ) {
743  if( !is_blocking )
744  return item_not_available;
745  my_input_buffer->sema_P();
746  }
747  info.my_object = (*this)(info.my_object);
748  if( info.my_object ) {
749  __TBB_ASSERT(my_pipeline->input_tokens > 0, "Token failed in thread-bound filter");
751  if( is_ordered() ) {
752  info.my_token = my_pipeline->token_counter;
753  info.my_token_ready = true;
754  }
755  my_pipeline->token_counter++; // ideally, with relaxed semantics
756  } else {
757  my_pipeline->end_of_input = true;
758  return end_of_stream;
759  }
760  } else { /* this is not an input filter */
761  while( !my_input_buffer->has_item() ) {
762  if( !is_blocking ) {
763  return item_not_available;
764  }
765  my_input_buffer->sema_P();
766  if( my_pipeline->end_of_input && !has_more_work() ) {
767  return end_of_stream;
768  }
769  }
770  if( !my_input_buffer->return_item(info, /*advance*/true) ) {
771  __TBB_ASSERT(false,"return_item failed");
772  }
773  info.my_object = (*this)(info.my_object);
774  }
776  if ( !next_filter_in_pipeline->my_input_buffer->put_token(info,/*force_put=*/true) ) {
777  __TBB_ASSERT(false, "Couldn't put token after thread-bound buffer");
778  }
779  } else {
780  size_t ntokens_avail = ++(my_pipeline->input_tokens);
781  if( my_pipeline->filter_list->is_bound() ) {
782  if( ntokens_avail == 1 ) {
784  }
785  }
786  }
787 
788  return success;
789 }
bool has_more_work()
has the filter not yet processed all the tokens it will ever see?
Definition: pipeline.cpp:695
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:169
filter * next_filter_in_pipeline
Pointer to next filter in the pipeline.
Definition: pipeline.h:160
filter * filter_list
Pointer to first filter in the pipeline.
Definition: pipeline.h:268
bool is_ordered() const
True if filter must receive stream in order.
Definition: pipeline.h:134
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
atomic< internal::Token > input_tokens
Number of idle tokens waiting for input stage.
Definition: pipeline.h:277
atomic< internal::Token > token_counter
Global counter of tokens.
Definition: pipeline.h:280
bool is_bound() const
True if filter is thread-bound.
Definition: pipeline.h:139
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, end_of_stream, tbb::pipeline::filter_list, tbb::filter::has_more_work(), tbb::pipeline::input_tokens, tbb::filter::is_bound(), tbb::filter::is_ordered(), item_not_available, tbb::filter::my_input_buffer, tbb::filter::my_pipeline, tbb::filter::next_filter_in_pipeline, tbb::filter::prev_filter_in_pipeline, success, and tbb::pipeline::token_counter.

Referenced by process_item(), and try_process_item().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ process_item()

thread_bound_filter::result_type tbb::thread_bound_filter::process_item ( )

Wait until a data item becomes available, and invoke operator() on that item.

This interface is blocking. Returns 'success' if an item was processed. Returns 'end_of_stream' if there are no more items to process. Never returns 'item_not_available', as it blocks until another return condition applies.

Definition at line 723 of file pipeline.cpp.

723  {
724  return internal_process_item(true);
725 }
result_type internal_process_item(bool is_blocking)
Internal routine for item processing.
Definition: pipeline.cpp:731

References internal_process_item().

Here is the call graph for this function:

◆ try_process_item()

thread_bound_filter::result_type tbb::thread_bound_filter::try_process_item ( )

If a data item is available, invoke operator() on that item.

This interface is non-blocking. Returns 'success' if an item was processed. Returns 'item_not_available' if no item can be processed now but more may arrive in the future, or if token limit is reached. Returns 'end_of_stream' if there are no more items to process.

Definition at line 727 of file pipeline.cpp.

727  {
728  return internal_process_item(false);
729 }
result_type internal_process_item(bool is_blocking)
Internal routine for item processing.
Definition: pipeline.cpp:731

References internal_process_item().

Here is the call graph for this function:

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.