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

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.

                                                  :
         filter(static_cast<mode>(filter_mode | filter::filter_is_bound))
    {
        __TBB_ASSERT(filter_mode & filter::filter_is_serial, "thread-bound filters must be serial");
    }

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

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);
}

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