Table of Contents

Name

qt_loop_queue_create - allocate a loop queue handle

Synopsis

#include <qthread/qloop.h>

qqloop_handle_t*
qt_loop_queue_create(

const qt_loop_queue_type type,
const size_t start,
const size_t stop,
const size_t step,
const qt_loop_f func,
void * const argptr);

Description

This function allocates a loop queue handle for use with qt_loop_queue_run() or qt_loop_queue_run_there().

The func argument must be a function pointer with a qt_loop_f prototype. Its basic code structure is expected to look like this:

void func (const size_t startat, const size_t stopat, const size_t step, void * arg)
{

for (unsigned int i = startat; i < stopat; i += step) {
/* do work */
}
}

The arguments startat and stopat are determined by the library, and tell the function what range of i values (iterations) it is responsible for.

The type argument defines which adaptive scheduling technique should be used to schedule the processing of loop iterations. The possible values are:

CHUNK
This is the lowest-overhead method, but is the least adaptive. A small default chunk size will be chosen by the library, and all available worker threads will process loop iterations in groups of that size. The chunk size can be specified with the qt_loop_queue_setchunk() function.
GUIDED
This specifies an implementation of guided self-scheduled loops, invented by Constantine D. Polychronopoulos and David J. Kuck in 1987. Iterations are executed in chunks that are halved in size as the loop progresses. This is particularly efficient at slightly imbalanced loops.
FACTORED
This specifies an implementation of factored self-scheduled loops, invented by Susan F. Hummel, and Edith Schonberg, and Lawrence E. Flynn in 1992. Iterations are executed in chunks that are specified in sets. First, half of the iteration space is handed out in equal-sized chunks to all threads, then half of the remaining iterations are handed out in equal-sized chunks, and so forth. This is more effective than GUIDED when loops are more imbalanced.
TIMED
This specifies an implementation of timed self-scheduled loops; iterations are timed and subsequent chunks of iterations are given to worker threads based on the length of time required by the previous iteration chunks. This method can account for overhead better and can potentially handle wildly imbalanced loops more efficiently than FACTORED.

Return Values

A pointer to a valid qqloop_handle_t will be returned OR a NULL pointer if memory could not be allocated.

See Also

qt_loop(3) , qt_loop_future(3) , qt_loop_queue_run(3) , qt_loopaccum_balance(3) , qt_loopaccum_balance_future(3)


Table of Contents