The most important functions in futurelib that a person is going to use are mt_loop and mt_loop_returns. The mt_loop function is for parallel iterations taht do not return values, and the mt_loop_returns function is for parallel iterations that DO return values. The distinction is not always so obvious.

mt_loop is used in a format like so:

mt_loop<...argtypelist..., looptype>
        (function, ...arglist..., startval, stopval, stepval);

The "stepval" is optional, and defaults to 1.

Essentially what you're doing is in the template setup (in the <>) you're specifying how to handle the arguments to the parallel funcitons and what kind of parallelism you want. Options for 'looptype' (i.e. the kind of parallelism) are:

mt_loop_traits::Par

fork all iterations, wait for them to finish

mt_loop_traits::ParNoJoin

same as Par, but without the waiting

mt_loop_traits::Future

a resource-constrained version of Par, will limit the number of threads running at a given time

mt_loop_traits::FutureNoJoin

same as Future, but without waiting for threads to finish

The argtypelist is a list of conceptual types defining how the arguments to the parallel function will be handled. Use one conceptual type per argument, in the order the argumentsk will be passed. Valid conceptual types are:

Iterator

The parallel function will be called with the current loop iteration number passed into this argument.

ArrayPtr

The corresponding argument is a pointer to an array, and each iteration will be passed the value of array[iteration]

Ref

The corresponding argument will be passed as a reference.

Val

The corresponding argument will be passed as a constant value (i.e. the same value will be passed to all iterations)

For example, doing this:

for (int i = 0; i < 10; i++) {
        array[i] = i;
}

Would be achieved like so:

void assign(int &array_value, const int i) {
        array_value = i;
}

mt_loop<ArrayPtr, Iterator, mt_loop_traits::Par>
        (assign, array, 0, 0, 10);

The mt_loop_returns variant adds the specification of what to do with the return values. The pattern is like this:

mt_loop_returns<returnvaltype, ...argtypelist..., looptype>
        (retval, function, ...arglist..., startval, stopval, stepval);

The only difference is in the returnvaltype and the retval. The returnvaltype can be either an ArrayPtr or a Collect. If it is an ArrayPtr, the loop will behave similar to the following loop:

for (int i = start; i < stop; i += step) {
        retval[i] = function(args);
}

Each return value will be stored in a separate entry in the retval array. The Collect type is more interesting, and can be either:

Collect<mt_loop_traits::Add>

this sums all of the return values in parallel

Collect<mt_loop_traits::Sub>

this subtracts all of the return values in parallel. Note that the answer may be nondeterministic.

Collect<mt_loop_traits::Mult>

this multiplies all of the return values in parallel

Collect<mt_loop_traits::Div>

this divides all of the return values in parallel. Note that the answer is nondeterministic.

For example, Collect<mt_loop_traits::Add> is roughly equivalent to the following loop:

for (int i = start; i < stop; i += step) {
        retval += function(args);
}