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

- Start the pipeline on another thread.
- Service the`thread_bound_filter` until it reaches `end_of_stream`.
- Wait for the other thread to finish.

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.
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. ### Caution The current implementation spin waits until it can process an item or reaches the end of the stream.

Parent topic: pipeline Class