# composite_node

[flow_graph.composite_node]

A node that encapsulates a collection of other nodes as a first class graph node.

    // Defined in header <oneapi/tbb/flow_graph.h>

    namespace oneapi {
    namespace tbb {
    namespace flow {

        template< typename InputTuple, typename OutputTuple > class composite_node;

        // composite_node with both input ports and output ports
        template< typename... InputTypes, typename... OutputTypes>
        class composite_node <std::tuple<InputTypes...>, std::tuple<OutputTypes...> > : public graph_node {
        public:
            typedef std::tuple< receiver<InputTypes>&... > input_ports_type;
            typedef std::tuple< sender<OutputTypes>&... > output_ports_type;

            composite_node( graph &g );
            virtual ~composite_node();

            void set_external_ports(input_ports_type&& input_ports_tuple, output_ports_type&& output_ports_tuple);
            input_ports_type& input_ports();
            output_ports_type& output_ports();
        };

        // composite_node with only input ports
        template< typename... InputTypes>
        class composite_node <std::tuple<InputTypes...>, std::tuple<> > : public graph_node{
        public:
            typedef std::tuple< receiver<InputTypes>&... > input_ports_type;

            composite_node( graph &g );
            virtual ~composite_node();

            void set_external_ports(input_ports_type&& input_ports_tuple);
            input_ports_type& input_ports();
        };

        // composite_nodes with only output_ports
        template<typename... OutputTypes>
        class composite_node <std::tuple<>, std::tuple<OutputTypes...> > : public graph_node{
        public:
            typedef std::tuple< sender<OutputTypes>&... > output_ports_type;

            composite_node( graph &g );
            virtual ~composite_node();

            void set_external_ports(output_ports_type&& output_ports_tuple);
            output_ports_type& output_ports();
        };

    } // namespace flow
    } // namespace tbb
    } // namespace oneapi

- The `InputTuple` and `OutputTuple` must be instantiations of `std::tuple`.

`composite_node` is a `graph_node`, `receiver<T>`, and `sender<T>`.

The `composite_node` can package any number of other nodes. It maintains input and output port references to nodes in the package that border the `composite_node`. This allows the references to be used to make edges to other nodes outside of the `composite_node`. The `InputTuple` is a tuple of input types. The `composite_node` has an input port for each type in `InputTuple`. Likewise, the `OutputTuple` is a tuple of output types. The `composite_node` has an output port for each type in `OutputTuple`.

The composite_node is a multi-port node with three specializations.

- A multi-port node with multi-input ports and multi-output ports: This specialization has a tuple of input ports, each of which is a `receiver` of a type in `InputTuple`. Each input port is a reference to a port of a node that the `composite_node` encapsulates. Similarly, this specialization also has a tuple of output ports, each of which is a `sender` of a type in `OutputTuple`. Each output port is a reference to a port of a node that the `composite_node` encapsulates.

- A multi-port node with only input ports and no output ports: This specialization only has a tuple of input ports.

- A multi-port node with only output ports and no input_ports: This specialization only has a tuple of output ports.

The function template input_port can be used to get a reference to a specific input port and the function template output_port can be used to get a reference to a specific output port.

Construction of a `composite_node` is done in two stages:

- Defining the `composite_node` with specification of `InputTuple` and `OutputTuple`.

- Making aliases from the encapsulated nodes that border the `composite_node` to the input and output ports of the `composite_node`. This step is mandatory as without it the `composite_node` input and output ports are not bound to any actual nodes. Making the aliases is achieved by calling the method `set_external_ports`.

The composite_node does not meet the CopyConstructible requirements from [copyconstructible] ISO C++ Standard section.

## Member functions

composite_node(graph &g)

  Constructs a `composite_node` that belongs to the graph `g`.

void set_external_ports(input_ports_type &&input_ports_tuple, output_ports_type &&output_ports_tuple)

  Creates input and output ports of the `composite_node` as aliases to the ports referenced by `input_ports_tuple` and `output_ports_tuple`, respectively. That is, a port referenced at position `N` in `input_ports_tuple` is mapped as the `Nth` input port of the `composite_node`, similarly for output ports.

input_ports_type &input_ports()

  > Returns: A `std::tuple` of `receivers`. Each element is a reference to the actual node or input port that was aliased to that position in `set_external_ports()`.

  Caution

  Calling `input_ports()` without a prior call to `set_external_ports()` results in undefined behavior.

output_ports_type &output_ports()

  Returns: A `std::tuple` of `senders`. Each element is a reference to the actual node or output port that was aliased to that position in `set_external_ports()`.

  Caution

  Calling `output_ports()` without a prior call to `set_external_ports()` results in undefined behavior.

See also:

- input_port function template

- output_port function template