Contents

• Concurrent Map
• Concurrent Map-Reduce
• Additional API Features
• Using Iterators instead of Sequence
• Blocking Variants
• Using Member Functions
• Using Function Objects
• Using Bound Function Arguments

These functions are a part of theQt Concurrent framework.

TheQtConcurrent::map(),QtConcurrent::mapped() andQtConcurrent::mappedReduced() functions run computations in parallel on the items in a sequence such as aQList or aQVector.QtConcurrent::map() modifies a sequence in-place,QtConcurrent::mapped() returns a new sequence containing the modified content, andQtConcurrent::mappedReduced() returns a single result.

Each of the above functions has a blocking variant that returns the final result instead of aQFuture. You use them in the same way as the asynchronous variants.

QList<QImage> images=...;// each call blocks until the entire operation is finishedQList<QImage> future=QtConcurrent::blockingMapped(images, scaled);QtConcurrent::blockingMap(images, scale);QImage collage=QtConcurrent::blockingMappedReduced(images, scaled, addToCollage);

Note that the result types above are notQFuture objects, but real result types (in this case,QList<QImage> andQImage).

Concurrent Map

QtConcurrent::mapped() takes an input sequence and a map function. This map function is then called for each item in the sequence, and a new sequence containing the return values from the map function is returned.

The map function must be of the form:

U function(const T&t);

T and U can be any type (and they can even be the same type), but T must match the type stored in the sequence. The function returns the modified ormapped content.

This example shows how to apply a scale function to all the items in a sequence:

QImage scaled(constQImage&image){return image.scaled(100,100);}QList<QImage> images=...;QFuture<QImage> thumbnails=QtConcurrent::mapped(images, scaled);

The results of the map are made available throughQFuture. See theQFuture andQFutureWatcher documentation for more information on how to useQFuture in your applications.

If you want to modify a sequence in-place, useQtConcurrent::map(). The map function must then be of the form:

U function(T&t);

Note that the return value and return type of the map function are not used.

UsingQtConcurrent::map() is similar to usingQtConcurrent::mapped():

void scale(QImage&image){    image= image.scaled(100,100);}QList<QImage> images=...;QFuture<void> future=QtConcurrent::map(images, scale);

Since the sequence is modified in place,QtConcurrent::map() does not return any results viaQFuture. However, you can still useQFuture andQFutureWatcher to monitor the status of the map.

Concurrent Map-Reduce

QtConcurrent::mappedReduced() is similar toQtConcurrent::mapped(), but instead of returning a sequence with the new results, the results are combined into a single value using a reduce function.

The reduce function must be of the form:

V function(T&result,const U&intermediate)

T is the type of the final result, U is the return type of the map function. Note that the return value and return type of the reduce function are not used.

CallQtConcurrent::mappedReduced() like this:

void addToCollage(QImage&collage,constQImage&thumbnail){QPainter p(&collage);staticQPoint offset=QPoint(0,0);    p.drawImage(offset, thumbnail);    offset+=...;}QList<QImage> images=...;QFuture<QImage> collage=QtConcurrent::mappedReduced(images, scaled, addToCollage);

The reduce function will be called once for each result returned by the map function, and should merge theintermediate into theresult variable.QtConcurrent::mappedReduced() guarantees that only one thread will call reduce at a time, so using a mutex to lock the result variable is not necessary. TheQtConcurrent::ReduceOptions enum provides a way to control the order in which the reduction is done. IfQtConcurrent::UnorderedReduce is used (the default), the order is undefined, whileQtConcurrent::OrderedReduce ensures that the reduction is done in the order of the original sequence.

Additional API Features

Using Iterators instead of Sequence

Each of the above functions has a variant that takes an iterator range instead of a sequence. You use them in the same way as the sequence variants:

QList<QImage> images=...;QFuture<QImage> thumbnails=QtConcurrent::mapped(images.constBegin(), images.constEnd(), scaled);// map in-place only works on non-const iteratorsQFuture<void> future=QtConcurrent::map(images.begin(), images.end(), scale);QFuture<QImage> collage=QtConcurrent::mappedReduced(images.constBegin(), images.constEnd(), scaled, addToCollage);

Blocking Variants

Each of the above functions has a blocking variant that returns the final result instead of aQFuture. You use them in the same way as the asynchronous variants.

QList<QImage> images=...;// each call blocks until the entire operation is finishedQList<QImage> future=QtConcurrent::blockingMapped(images, scaled);QtConcurrent::blockingMap(images, scale);QImage collage=QtConcurrent::blockingMappedReduced(images, scaled, addToCollage);

Note that the result types above are notQFuture objects, but real result types (in this case,QList<QImage> andQImage).

Using Member Functions

QtConcurrent::map(),QtConcurrent::mapped(), andQtConcurrent::mappedReduced() accept pointers to member functions. The member function class type must match the type stored in the sequence:

// squeeze all strings in a QStringListQStringList strings=...;QFuture<void> squeezedStrings=QtConcurrent::map(strings,&QString::squeeze);// swap the rgb values of all pixels on a list of imagesQList<QImage> images=...;QFuture<QImage> bgrImages=QtConcurrent::mapped(images,&QImage::rgbSwapped);// create a set of the lengths of all strings in a listQStringList strings=...;QFuture<QSet<int>> wordLengths=QtConcurrent::mappedReduced(string,&QString::length,&QSet<int>::insert);

Note that when usingQtConcurrent::mappedReduced(), you can mix the use of normal and member functions freely:

// can mix normal functions and member functions with QtConcurrent::mappedReduced()// compute the average length of a list of stringsexternvoid computeAverage(int&average,int length);QStringList strings=...;QFuture<int> averageWordLength=QtConcurrent::mappedReduced(strings,&QString::length, computeAverage);// create a set of the color distribution of all images in a listexternint colorDistribution(constQImage&string);QList<QImage> images=...;QFuture<QSet<int>> totalColorDistribution=QtConcurrent::mappedReduced(images, colorDistribution,QSet<int>::insert);

Using Function Objects

QtConcurrent::map(),QtConcurrent::mapped(), andQtConcurrent::mappedReduced() accept function objects, which can be used to add state to a function call. The result_type typedef must define the result type of the function call operator:

struct Scaled{    Scaled(int size)    : m_size(size) { }typedefQImage result_type;QImageoperator()(constQImage&image)    {return image.scaled(m_size, m_size);    }int m_size;};QList<QImage> images=...;QFuture<QImage> thumbnails=QtConcurrent::mapped(images, Scaled(100));

Using Bound Function Arguments

Note that Qt does not provide support for bound functions. This is provided by 3rd party libraries likeBoost orC++ TR1 Library Extensions.

If you want to use a map function that takes more than one argument you can use boost::bind() or std::tr1::bind() to transform it onto a function that takes one argument.

As an example, we'll useQImage::scaledToWidth():

QImageQImage::scaledToWidth(int width,Qt::TransformationMode)const;

scaledToWidth takes three arguments (including the "this" pointer) and can't be used withQtConcurrent::mapped() directly, becauseQtConcurrent::mapped() expects a function that takes one argument. To useQImage::scaledToWidth() withQtConcurrent::mapped() we have to provide a value for thewidth and thetransformation mode:

boost::bind(&QImage::scaledToWidth,100,Qt::SmoothTransformation)

The return value from boost::bind() is a function object (functor) with the following signature:

QImage scaledToWith(constQImage&image)

This matches whatQtConcurrent::mapped() expects, and the complete example becomes:

QList<QImage> images=...;QFuture<QImage> thumbnails=QtConcurrent::mapped(images, boost::bind(&QImage::scaledToWidth,100Qt::SmoothTransformation));