tbb::thread_bound_filter Class Reference
Algorithms

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

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

## Member Enumeration Documentation

## result_type

enum tbb::thread_bound_filter::result_type

Enumerator
success |
item_not_available |
end_of_stream |

Definition at line 198 of file pipeline.h.

{
// item was processed
success,
// item is currently not available
item_not_available,
// there are no more items to process
end_of_stream
};
tbb::thread_bound_filter::success
@ success
Definition: pipeline.h:200
tbb::thread_bound_filter::end_of_stream
@ end_of_stream
Definition: pipeline.h:204
tbb::thread_bound_filter::item_not_available
@ item_not_available
Definition: pipeline.h:202

## Constructor & Destructor Documentation

## thread_bound_filter()

tbb::thread_bound_filter::thread_bound_filter | ( | mode | filter_mode | ) |

inline explicit protected

Definition at line 207 of file pipeline.h.

:
filter(static_cast<mode>(filter_mode | filter::filter_is_bound))
{
__TBB_ASSERT(filter_mode & filter::filter_is_serial, "thread-bound filters must be serial");
}
__TBB_ASSERT
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:165
tbb::filter::filter_is_bound
static const unsigned char filter_is_bound
5th bit distinguishes thread-bound and regular filters.
Definition: pipeline.h:78
tbb::filter::mode
mode
Definition: pipeline.h:94
tbb::filter::filter
filter(bool is_serial_)
Definition: pipeline.h:105
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

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.

{
__TBB_ASSERT(my_pipeline != NULL,"It's not supposed that process_item is called for a filter that is not in a pipeline.");
internal::task_info info;
info.reset();
if( my_pipeline->end_of_input && !has_more_work() )
return end_of_stream;
if( !prev_filter_in_pipeline ) {
if( my_pipeline->end_of_input )
return end_of_stream;
while( my_pipeline->input_tokens == 0 ) {
if( !is_blocking )
return item_not_available;
my_input_buffer->sema_P();
}
info.my_object = (*this)(info.my_object);
if( info.my_object ) {
__TBB_ASSERT(my_pipeline->input_tokens > 0, "Token failed in thread-bound filter");
my_pipeline->input_tokens--;
if( is_ordered() ) {
info.my_token = my_pipeline->token_counter;
info.my_token_ready = true;
}
my_pipeline->token_counter++; // ideally, with relaxed semantics
} else {
my_pipeline->end_of_input = true;
return end_of_stream;
}
} else { /* this is not an input filter */
while( !my_input_buffer->has_item() ) {
if( !is_blocking ) {
return item_not_available;
}
my_input_buffer->sema_P();
if( my_pipeline->end_of_input && !has_more_work() ) {
return end_of_stream;
}
}
if( !my_input_buffer->return_item(info, /*advance*/true) ) {
__TBB_ASSERT(false,"return_item failed");
}
info.my_object = (*this)(info.my_object);
}
if( next_filter_in_pipeline ) {
if ( !next_filter_in_pipeline->my_input_buffer->put_token(info,/*force_put=*/true) ) {
__TBB_ASSERT(false, "Couldn't put token after thread-bound buffer");
}
} else {
size_t ntokens_avail = ++(my_pipeline->input_tokens);
if( my_pipeline->filter_list->is_bound() ) {
if( ntokens_avail == 1 ) {
my_pipeline->filter_list->my_input_buffer->sema_V();
}
}
}
return success;
}
tbb::filter::is_ordered
bool is_ordered() const
True if filter must receive stream in order.
Definition: pipeline.h:133
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::has_more_work
bool has_more_work()
has the filter not yet processed all the tokens it will ever see?
Definition: pipeline.cpp:691
tbb::filter::next_filter_in_pipeline
filter * next_filter_in_pipeline
Pointer to next filter in the pipeline.
Definition: pipeline.h:164
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
tbb::internal::input_buffer::put_token
bool put_token(task_info &info_, bool force_put=false)
Put a token into the buffer.
Definition: pipeline.cpp:135
tbb::internal::input_buffer::sema_P
void sema_P()
Definition: pipeline.cpp:98
tbb::internal::input_buffer::has_item
bool has_item()
true if the current low_token is valid.
Definition: pipeline.cpp:222
tbb::internal::input_buffer::return_item
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.

{
return internal_process_item(true);
}
tbb::thread_bound_filter::internal_process_item
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.

{
return internal_process_item(false);
}

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.