# Simple Example: Fibonacci Numbers

This section uses computation of the nth Fibonacci number as an example. This example uses an inefficient method to compute Fibonacci numbers, but it demonstrates the basics of a task library using a simple recursive pattern. To get scalable speedup out of task-based programming, you need to specify a lot of tasks. This is typically done in Intel® TBB with a recursive task pattern.

This is the serial code:

    long SerialFib( long n ) {
        if( n<2 )
            return n;
        else
            return SerialFib(n-1)+SerialFib(n-2);
    }

The top-level code for the parallel task-based version is:

    long ParallelFib( long n ) {
        long sum;
        FibTask& a = *new(task::allocate_root()) FibTask(n,&sum);
        task::spawn_root_and_wait(a);
        return sum;
    }

This code uses a task of type `FibTask` to do the real work. It involves the following distinct steps:

1. Allocate space for the task. This is done by a special "overloaded new" and method task::allocate_root. The `_root` suffix in the name denotes the fact that the task created has no parent. It is the root of a task tree. Tasks must be allocated by special methods so that the space can be efficiently recycled when the task completes.

2. Construct the task with the constructor `FibTask(n,&sum)` invoked by `new`. When the task is run in step 3, it computes the nth Fibonacci number and stores it into `*sum`.

3. Run the task to completion with `task::spawn_root_and_wait`.

The real work is inside struct `FibTask`. Its definition is shown below.

    class FibTask: public task {
    public:
        const long n;
        long* const sum;
        FibTask( long n_, long* sum_ ) :
            n(n_), sum(sum_)
        {}
        task* execute() {      // Overrides virtual function task::execute
            if( n<CutOff ) {
                *sum = SerialFib(n);
            } else {
                long x, y;
                FibTask& a = *new( allocate_child() ) FibTask(n-1,&x);
                FibTask& b = *new( allocate_child() ) FibTask(n-2,&y);
                // Set ref_count to 'two children plus one for the wait".
                set_ref_count(3);
                // Start b running.
                spawn( b );
                // Start a running and wait for all children (a and b).
                spawn_and_wait_for_all(a);
                // Do the sum
                *sum = x+y;
            }
            return NULL;
        }
    };

It is a relatively large piece of code, compared to `SerialFib`, because it expresses parallelism without the help of any extensions to standard C++.

Like all tasks scheduled by Intel® TBB, `FibTask` is derived from class `task`. Fields `n` and `sum` hold respectively the input value and pointer to the output. These are copies of the arguments passed to the constructor for `FibTask`. Method `execute` does the actual computation. Every task must provide a definition of `execute` that overrides the pure virtual method task::execute. The definition should do the work of the task, and return either NULL, or a pointer to the next task to run. In this simple example, it returns NULL. For more information on the non-NULL case see Scheduler Bypass.

Method FibTask::execute()does the following:

- Checks if `n` is so small that serial execution would be faster. Finding the right value of `CutOff` requires some experimentation. A value of at least 16 works well in practice for getting most of the possible speedup out of this example. Resorting to a sequential algorithm when the problem size becomes small is characteristic of most divide-and-conquer patterns for parallelism. Finding the point at which to switch requires experimentation, so be sure to write your code in a way that allows you to experiment.

- If the `else` is taken, the code creates and runs two child tasks that compute the (`n`-1)th and (`n`-2)th Fibonacci numbers. Here, inherited method `allocate_child()` is used to allocate space for the task. Remember that the top-level routine `ParallelFib` used `allocate_root()` to allocate space for a task. The difference is that here the task is creating child tasks. This relationship is indicated by the choice of allocation method.

- Calls `set_ref_count(3)`. The number `3` represents the two children and an additional implicit reference that is required by method `spawn_and_wait_for_all`. Make sure to call `set_reference_count(3)` before spawning any children. Failure to do so results in undefined behavior. The debug version of the library usually detects and reports this type of error.

- Spawns two child tasks. Spawning a task indicates to the scheduler that it can run the task whenever it chooses, possibly in parallel with other tasks. For more information on the execution policy see How Task Scheduling Works. The first spawning, by method `spawn`, returns immediately without waiting for the child task to start executing. The second spawning, by method `spawn_and_wait_for_all`, causes the parent to wait until all currently allocated child tasks are finished.

- After the two child tasks complete, the parent computes `x+y` and stores it in `*sum`.

At first glance, the parallelism might appear to be limited, because the task creates only two child tasks. The trick here is recursive parallelism. The two child tasks each create two child tasks, and so on, until `n<Cutoff`. This chain reaction creates a lot of potential parallelism. The advantage of the task scheduler is that it turns this potential parallelism into real parallelism in a very efficient way, because it chooses tasks to run in a way that keeps physical threads busy with relatively little context switching.

Parent topic: The Task Scheduler

## See Also

Scheduler Bypass
How Task Scheduling Works