Intel(R) Threading Building Blocks Doxygen Documentation version 4.2.3
Loading...
Searching...
No Matches
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.
 
result_type __TBB_EXPORTED_METHOD process_item ()
 Wait until a data item becomes available, and invoke operator() on that item.
 
- Public Member Functions inherited from tbb::filter
bool is_serial () const
 True if filter is serial.
 
bool is_ordered () const
 True if filter must receive stream in order.
 
bool is_bound () const
 True if filter is thread-bound.
 
bool object_may_be_null ()
 true if an input filter can emit null
 
virtual voidoperator() (void *item)=0
 Operate on an item from the input stream, and return item for output stream.
 
virtual __TBB_EXPORTED_METHOD ~filter ()
 Destroy filter.
 
virtual void finalize (void *)
 Destroys item if pipeline was cancelled.
 

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.
 

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.
 
static const unsigned char filter_is_out_of_order = 0x1<<4
 4th bit distinguishes ordered vs unordered filters.
 
static const unsigned char filter_is_bound = 0x1<<5
 5th bit distinguishes thread-bound and regular filters.
 
static const unsigned char filter_may_emit_null = 0x1<<6
 6th bit marks input filters emitting small objects
 
static const unsigned char exact_exception_propagation
 7th bit defines exception propagation mode expected by the application.
 
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 196 of file pipeline.h.

Member Enumeration Documentation

◆ result_type

Enumerator
success 
item_not_available 
end_of_stream 

Definition at line 198 of file pipeline.h.

198 {
199 // item was processed
200 success,
201 // item is currently not available
203 // there are no more items to process
205 };

Constructor & Destructor Documentation

◆ thread_bound_filter()

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

Definition at line 207 of file pipeline.h.

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

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

727 {
728 __TBB_ASSERT(my_pipeline != NULL,"It's not supposed that process_item is called for a filter that is not in a pipeline.");
729 internal::task_info info;
730 info.reset();
731
732 if( my_pipeline->end_of_input && !has_more_work() )
733 return end_of_stream;
734
736 if( my_pipeline->end_of_input )
737 return end_of_stream;
738 while( my_pipeline->input_tokens == 0 ) {
739 if( !is_blocking )
740 return item_not_available;
742 }
743 info.my_object = (*this)(info.my_object);
744 if( info.my_object ) {
745 __TBB_ASSERT(my_pipeline->input_tokens > 0, "Token failed in thread-bound filter");
746 my_pipeline->input_tokens--;
747 if( is_ordered() ) {
748 info.my_token = my_pipeline->token_counter;
749 info.my_token_ready = true;
750 }
751 my_pipeline->token_counter++; // ideally, with relaxed semantics
752 } else {
753 my_pipeline->end_of_input = true;
754 return end_of_stream;
755 }
756 } else { /* this is not an input filter */
757 while( !my_input_buffer->has_item() ) {
758 if( !is_blocking ) {
759 return item_not_available;
760 }
762 if( my_pipeline->end_of_input && !has_more_work() ) {
763 return end_of_stream;
764 }
765 }
766 if( !my_input_buffer->return_item(info, /*advance*/true) ) {
767 __TBB_ASSERT(false,"return_item failed");
768 }
769 info.my_object = (*this)(info.my_object);
770 }
772 if ( !next_filter_in_pipeline->my_input_buffer->put_token(info,/*force_put=*/true) ) {
773 __TBB_ASSERT(false, "Couldn't put token after thread-bound buffer");
774 }
775 } else {
776 size_t ntokens_avail = ++(my_pipeline->input_tokens);
777 if( my_pipeline->filter_list->is_bound() ) {
778 if( ntokens_avail == 1 ) {
779 my_pipeline->filter_list->my_input_buffer->sema_V();
780 }
781 }
782 }
783
784 return success;
785}
bool is_ordered() const
True if filter must receive stream in order.
Definition pipeline.h:133
internal::input_buffer * my_input_buffer
Buffer for incoming tokens, or NULL if not required.
Definition pipeline.h:173
bool has_more_work()
has the filter not yet processed all the tokens it will ever see?
Definition pipeline.cpp:691
filter * next_filter_in_pipeline
Pointer to next filter in the pipeline.
Definition pipeline.h:164
filter * prev_filter_in_pipeline
Pointer to previous filter in the pipeline.
Definition pipeline.h:184
pipeline * my_pipeline
Pointer to the pipeline.
Definition pipeline.h:187
bool put_token(task_info &info_, bool force_put=false)
Put a token into the buffer.
Definition pipeline.cpp:135
bool has_item()
true if the current low_token is valid.
Definition pipeline.cpp:222
bool return_item(task_info &info, bool advance)
return an item, invalidate the queued item, but only advance if the filter
Definition pipeline.cpp:208

References __TBB_ASSERT, tbb::internal::task_info::my_object, tbb::internal::task_info::my_token, tbb::internal::task_info::my_token_ready, and tbb::internal::task_info::reset().

Here is the call 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 719 of file pipeline.cpp.

719 {
720 return internal_process_item(true);
721}
result_type internal_process_item(bool is_blocking)
Internal routine for item processing.
Definition pipeline.cpp:727

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

723 {
724 return internal_process_item(false);
725}

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

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.