thread_bound_filter Class

Summary

Abstract base class that represents a filter in a pipeline that a thread must service explicitly.

Header

#include "tbb/pipeline.h" 

Syntax

 class thread_bound_filter;

Description

A thread_bound_filter is a special kind of filter that is explicitly serviced by a particular thread. It is useful when a filter must be executed by a particular thread.

Caution

Use thread_bound_filter only if you need a filter to be executed on a particular thread. The thread_bound_filter cannot be safely used on multiple threads. The thread that services a thread_bound_filter must not be the thread that calls pipeline::run().

Members

namespace tbb {
    class thread_bound_filter: public filter {
    protected:
        thread_bound_filter(mode filter_mode);
    public:
        enum result_type {
            success,
            item_not_available,
            end_of_stream
        };
        result_type try_process_item();
        result_type process_item();
    };
} 

Example

The example below shows a pipeline with two filters where the second filter is a thread_bound_filter serviced by the main thread.

#include <iostream>
#include "tbb/pipeline.h"
#include "tbb/compat/thread"
#include "tbb/task_scheduler_init.h"

using namespace tbb;

char InputString[] = "abcdefg\n";

class InputFilter: public filter {
    char* my_ptr;
public:
    void* operator()(void*) {
        if (*my_ptr)
            return my_ptr++;
        else
            return NULL;
    }
    InputFilter() : 
        filter( serial_in_order ), my_ptr(InputString) 
    {}
};

class OutputFilter: public thread_bound_filter {
public:
    void* operator()(void* item) {
        std::cout << *(char*)item;
        return NULL;
    }
    OutputFilter() : thread_bound_filter(serial_in_order) {}
};

void RunPipeline(pipeline* p) {
    p->run(8);
}

int main() {
    // Construct the pipeline
    InputFilter f;
    OutputFilter g;
    pipeline p;
    p.add_filter(f);
    p.add_filter(g);

    // Another thread initiates execution of the pipeline
    std::thread t(RunPipeline,&p);

    // Process the thread_bound_filter with the current thread.
    while (g.process_item()!=thread_bound_filter::end_of_stream)
        continue;

    // Wait for pipeline to finish on the other thread.
    t.join();    
    return 0;
}

The main thread does the following after constructing the pipeline:

The pipeline is run on a separate thread because the main thread is responsible for servicing the thread_bound_filter g. The roles of the two threads can be reversed. A single thread cannot do both roles.

The following table provides additional information on the members of this template class.
Member Description
thread_bound_filter(mode filter_mode)()

Constructs a filter of the specified mode. The pipeline Class section describes the modes. The filter_mode parameter must be either serial_in_order or serial_out_of_order.

Caution

The behavior of a program is not defined if using a thread_bound_filter created as parallel.

result_type try_process_item()

If an item is available and it can be processed without exceeding the token limit, process the item with filter::operator(). The return values are detailed in the following table.

Return Value

Description

success

Applied filter::operator() to one item.

item_not_available

No item is currently available to process, or the token limit would be exceeded.

end_of_stream

No more items will ever arrive at this filter.

result_type process_item()

Like try_process_item, but waits until it can process an item or the end of the stream is reached.

Returns: Either success or end_of_stream. See the table above for details.

Note

The current implementation blocks on a semaphore until it can process an item or reaches the end of the stream.