# graph Class

## Summary

Class that serves as a handle to a flow graph of nodes and edges.

## Syntax

    class graph;

## Header

    #include "tbb/flow_graph.h"

## Description

A graph object contains a root task that is the parent of all tasks created on behalf of the flow graph and its nodes. It provides methods that can be used to access the root task, to wait for the children of the root task to complete, to explicitly increment or decrement the root task's reference count, and to run a task as a child of the root task.

### Caution

Destruction of flow graph nodes before calling wait_for_all on their associated graph object has undefined behavior and can lead to program failure.

### Caution

If a graph is cancelled or if an exception is thrown during its execution, the graph objects may be in an inconsistent state after the wait_for_all(). If the user wishes to execute the graph again, the reset() method must be called.

The reset() method ensures the internals of the graph are reset to their initial state. The user-supplied bodies of function_nodes, continue_nodes, source_nodes and multifunction_nodes are not changed by a reset(); if the user wishes the body to be returned to its initial state the corresponding node must be replaced, or some other provision must be made.

## Members

    namespace tbb {
    namespace flow {

    class graph {
    public:

        graph();
        graph(task_group_context& context);
        ~graph();

        void increment_wait_count();
        void decrement_wait_count();

        template< typename Receiver, typename Body >
        void run( Receiver &r, Body body );
        template< typename Body >
        void run( Body body );
        void wait_for_all();
        task *root_task();

        bool is_cancelled();
        bool exception_thrown();
        void reset();
    };

    }
    }

The following table provides additional information on the members of this class.
Member | Description
--- | ---
graph([task_group_context& group] ) | Constructs a graph with no nodes. If group is specified the graph tasks are executed in this group. By default the graph is executed in a bound context of its own. Instantiates a root task of class empty_task to serve as a parent for all of the tasks generated during runs of the graph. Sets ref_count of the root task to 1.
~graph() | Calls wait_for_all on the graph, then destroys the root task.
void increment_wait_count() | Used to register that an external entity may still interact with the graph. Increments the ref_count of the root task.
void decrement_wait_count() | Used to unregister an external entity that may have interacted with the graph. Decrements the ref_count of the root task.
template< typename Receiver, typename Body > void run( Receiver &r, Body body ) | Use this method to enqueue a task that runs a body and puts its output to a specific receiver. The task is created as a child of the graph's root task and therefore wait_for_all will not return until this task completes. Enqueues a task that invokes r.try_put( body() ). It does not wait for the task to complete. The enqueued task is a child of the root task.
template< typename Body > void run( Body body ) | This method enqueues a task that runs as a child of the graph's root task. Calls to wait_for_all will not return until this enqueued task completes. Enqueues a task that invokes body(). It does not wait for the task to complete.
void wait_for_all() | Blocks until all tasks associated with the root task have completed and the number of decrement_wait_count calls equals the number of increment_wait_count calls. Because it calls wait_for_all on the root graph task, the calling thread may participate in work-stealing while it is blocked.
task *root_task() | Returns: a pointer to the root task of the flow graph.
bool is_cancelled() | Returns: `true` if the graph was cancelled during the last call to wait_for_all(), `false` otherwise. See `task_group_context` for a description of cancellation.
bool exception_thrown() | Returns: `true` if during the last call to wait_for_all() an exception was thrown, `false` otherwise. See Section "Exceptions" for information on exception handling.
void reset() | Resets the internal state of the nodes of a graph to their initial state. The state of the bodies of function_nodes, continue_nodes, source_nodes and multifunction_nodes are not changed. See `task_group_context` for a description of cancellation. See Section "Exceptions" for information on exception handling.

Parent topic: Flow Graph

## See Also

task_group_context
Exceptions