QtConcurrent Namespace

The QtConcurrent namespace provides high-level APIs that make it possible to write multi-threaded programs without using low-level threading primitives. More...

Header:	#include <QtConcurrent>
qmake:	QT += concurrent
Since:	Qt 4.4

This namespace was introduced in Qt 4.4.

• Obsolete members

Types

enum	ReduceOption { UnorderedReduce, OrderedReduce, SequentialReduce }
flags	ReduceOptions

Functions

void	blockingFilter(Sequence &sequence, KeepFunctor filterFunction)
Sequence	blockingFiltered(const Sequence &sequence, KeepFunctor filterFunction)
OutputSequence	blockingFiltered(Iterator begin, Iterator end, KeepFunctor filterFunction)
ResultType	blockingFilteredReduced(const Sequence &sequence, KeepFunctor filterFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions = ReduceOptions(UnorderedReduce | SequentialReduce))
ResultType	blockingFilteredReduced(Iterator begin, Iterator end, KeepFunctor filterFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions = ReduceOptions(UnorderedReduce | SequentialReduce))
void	blockingMap(Sequence &sequence, MapFunctor function)
void	blockingMap(Iterator begin, Iterator end, MapFunctor function)
OutputSequence	blockingMapped(const InputSequence &sequence, MapFunctor function)
Sequence	blockingMapped(Iterator begin, Iterator end, MapFunctor function)
ResultType	blockingMappedReduced(const Sequence &sequence, MapFunctor mapFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions = ReduceOptions(UnorderedReduce | SequentialReduce))
ResultType	blockingMappedReduced(Iterator begin, Iterator end, MapFunctor mapFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions = QtConcurrent::ReduceOptions(QtConcurrent::UnorderedReduce | QtConcurrent::SequentialReduce))
QFuture<void>	filter(Sequence &sequence, KeepFunctor filterFunction)
QFuture<typename Sequence::value_type>	filtered(const Sequence &sequence, KeepFunctor filterFunction)
QFuture<typename qValueType<Iterator>::value_type>	filtered(Iterator begin, Iterator end, KeepFunctor filterFunction)
QFuture<ResultType>	filteredReduced(const Sequence &sequence, KeepFunctor filterFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions = ReduceOptions(UnorderedReduce | SequentialReduce))
QFuture<ResultType>	filteredReduced(Iterator begin, Iterator end, KeepFunctor filterFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions = ReduceOptions(UnorderedReduce | SequentialReduce))
QFuture<void>	map(Sequence &sequence, MapFunctor function)
QFuture<void>	map(Iterator begin, Iterator end, MapFunctor function)
QFuture<typename QtPrivate::MapResultType<void, MapFunctor>::ResultType>	mapped(const Sequence &sequence, MapFunctor function)
QFuture<typename QtPrivate::MapResultType<void, MapFunctor>::ResultType>	mapped(Iterator begin, Iterator end, MapFunctor function)
QFuture<ResultType>	mappedReduced(const Sequence &sequence, MapFunctor mapFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions = ReduceOptions(UnorderedReduce | SequentialReduce))
QFuture<ResultType>	mappedReduced(Iterator begin, Iterator end, MapFunctor mapFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions = ReduceOptions(UnorderedReduce | SequentialReduce))
QFuture<T>	run(Function function, ...)
QFuture<T>	run(QThreadPool *pool, Function function, ...)

Detailed Description

See the Qt Concurrent module documentation for an overview of available functions, or see below for detailed information on each function.

Type Documentation

enum QtConcurrent::ReduceOptionflags QtConcurrent::ReduceOptions

This enum specifies the order of which results from the map or filter function are passed to the reduce function.

Constant	Value	Description
QtConcurrent::UnorderedReduce	0x1	Reduction is done in an arbitrary order.
QtConcurrent::OrderedReduce	0x2	Reduction is done in the order of the original sequence.
QtConcurrent::SequentialReduce	0x4	Reduction is done sequentially: only one thread will enter the reduce function at a time. (Parallel reduction might be supported in a future version of Qt Concurrent.)

The ReduceOptions type is a typedef for QFlags<ReduceOption>. It stores an OR combination of ReduceOption values.

Function Documentation

void QtConcurrent::blockingFilter(Sequence &sequence, KeepFunctor filterFunction)

Calls filterFunction once for each item in sequence. If filterFunction returns true, the item is kept in sequence; otherwise, the item is removed from sequence.

Note: This function will block until all items in the sequence have been processed.

See also Concurrent Filter and Filter-Reduce.

Sequence QtConcurrent::blockingFiltered(const Sequence &sequence, KeepFunctor filterFunction)

Calls filterFunction once for each item in sequence and returns a new Sequence of kept items. If filterFunction returns true, a copy of the item is put in the new Sequence. Otherwise, the item will not appear in the new Sequence.

Note: This function will block until all items in the sequence have been processed.

See also filtered() and Concurrent Filter and Filter-Reduce.

OutputSequence QtConcurrent::blockingFiltered(Iterator begin, Iterator end, KeepFunctor filterFunction)

Calls filterFunction once for each item from begin to end and returns a new Sequence of kept items. If filterFunction returns true, a copy of the item is put in the new Sequence. Otherwise, the item will not appear in the new Sequence.

Note: This function will block until the iterator reaches the end of the sequence being processed.

See also filtered() and Concurrent Filter and Filter-Reduce.

ResultType QtConcurrent::blockingFilteredReduced(const Sequence &sequence, KeepFunctor filterFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions = ReduceOptions(UnorderedReduce | SequentialReduce))

Calls filterFunction once for each item in sequence. If filterFunction returns true for an item, that item is then passed to reduceFunction. In other words, the return value is the result of reduceFunction for each item where filterFunction returns true.

Note that while filterFunction is called concurrently, only one thread at a time will call reduceFunction. The order in which reduceFunction is called is undefined if reduceOptions is QtConcurrent::UnorderedReduce. If reduceOptions is QtConcurrent::OrderedReduce, reduceFunction is called in the order of the original sequence.

Note: This function will block until all items in the sequence have been processed.

See also filteredReduced() and Concurrent Filter and Filter-Reduce.

ResultType QtConcurrent::blockingFilteredReduced(Iterator begin, Iterator end, KeepFunctor filterFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions = ReduceOptions(UnorderedReduce | SequentialReduce))

Calls filterFunction once for each item from begin to end. If filterFunction returns true for an item, that item is then passed to reduceFunction. In other words, the return value is the result of reduceFunction for each item where filterFunction returns true.

Note that while filterFunction is called concurrently, only one thread at a time will call reduceFunction. The order in which reduceFunction is called is undefined if reduceOptions is QtConcurrent::UnorderedReduce. If reduceOptions is QtConcurrent::OrderedReduce, the reduceFunction is called in the order of the original sequence.

Note: This function will block until the iterator reaches the end of the sequence being processed.

See also filteredReduced() and Concurrent Filter and Filter-Reduce.

void QtConcurrent::blockingMap(Sequence &sequence, MapFunctor function)

Calls function once for each item in sequence. The function is passed a reference to the item, so that any modifications done to the item will appear in sequence.

Note: This function will block until all items in the sequence have been processed.

See also map() and Concurrent Map and Map-Reduce.

void QtConcurrent::blockingMap(Iterator begin, Iterator end, MapFunctor function)

Calls function once for each item from begin to end. The function is passed a reference to the item, so that any modifications done to the item will appear in the sequence which the iterators belong to.

Note: This function will block until the iterator reaches the end of the sequence being processed.

See also map() and Concurrent Map and Map-Reduce.

OutputSequence QtConcurrent::blockingMapped(const InputSequence &sequence, MapFunctor function)

Calls function once for each item in sequence and returns an OutputSequence containing the results. The type of the results will match the type returned my the MapFunctor.

Note: This function will block until all items in the sequence have been processed.

See also mapped() and Concurrent Map and Map-Reduce.

Sequence QtConcurrent::blockingMapped(Iterator begin, Iterator end, MapFunctor function)

Calls function once for each item from begin to end and returns a container with the results. Specify the type of container as the a template argument, like this:

QList<int> ints = QtConcurrent::blockingMapped<QList<int> >(beginIterator, endIterator, fn);

Note: This function will block until the iterator reaches the end of the sequence being processed.

See also mapped() and Concurrent Map and Map-Reduce.

ResultType QtConcurrent::blockingMappedReduced(const Sequence &sequence, MapFunctor mapFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions = ReduceOptions(UnorderedReduce | SequentialReduce))

Calls mapFunction once for each item in sequence. The return value of each mapFunction is passed to reduceFunction.

Note that while mapFunction is called concurrently, only one thread at a time will call reduceFunction. The order in which reduceFunction is called is determined by reduceOptions.

Note: This function will block until all items in the sequence have been processed.

See also mapped() and Concurrent Map and Map-Reduce.

ResultType QtConcurrent::blockingMappedReduced(Iterator begin, Iterator end, MapFunctor mapFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions = QtConcurrent::ReduceOptions(QtConcurrent::UnorderedReduce | QtConcurrent::SequentialReduce))

Calls mapFunction once for each item from begin to end. The return value of each mapFunction is passed to reduceFunction.

Note that while mapFunction is called concurrently, only one thread at a time will call reduceFunction. The order in which reduceFunction is called is undefined.

Note: This function will block until the iterator reaches the end of the sequence being processed.

See also blockingMappedReduced() and Concurrent Map and Map-Reduce.

QFuture<void> QtConcurrent::filter(Sequence &sequence, KeepFunctor filterFunction)

Calls filterFunction once for each item in sequence. If filterFunction returns true, the item is kept in sequence; otherwise, the item is removed from sequence.

See also Concurrent Filter and Filter-Reduce.

QFuture<typename Sequence::value_type> QtConcurrent::filtered(const Sequence &sequence, KeepFunctor filterFunction)

Calls filterFunction once for each item in sequence and returns a new Sequence of kept items. If filterFunction returns true, a copy of the item is put in the new Sequence. Otherwise, the item will not appear in the new Sequence.

See also Concurrent Filter and Filter-Reduce.

QFuture<typename qValueType<Iterator>::value_type> QtConcurrent::filtered(Iterator begin, Iterator end, KeepFunctor filterFunction)

Calls filterFunction once for each item from begin to end and returns a new Sequence of kept items. If filterFunction returns true, a copy of the item is put in the new Sequence. Otherwise, the item will not appear in the new Sequence.

See also Concurrent Filter and Filter-Reduce.

QFuture<ResultType> QtConcurrent::filteredReduced(const Sequence &sequence, KeepFunctor filterFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions = ReduceOptions(UnorderedReduce | SequentialReduce))

Calls filterFunction once for each item in sequence. If filterFunction returns true for an item, that item is then passed to reduceFunction. In other words, the return value is the result of reduceFunction for each item where filterFunction returns true.

Note that while filterFunction is called concurrently, only one thread at a time will call reduceFunction. The order in which reduceFunction is called is undefined if reduceOptions is QtConcurrent::UnorderedReduce. If reduceOptions is QtConcurrent::OrderedReduce, reduceFunction is called in the order of the original sequence.

See also Concurrent Filter and Filter-Reduce.

QFuture<ResultType> QtConcurrent::filteredReduced(Iterator begin, Iterator end, KeepFunctor filterFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions = ReduceOptions(UnorderedReduce | SequentialReduce))

Calls filterFunction once for each item from begin to end. If filterFunction returns true for an item, that item is then passed to reduceFunction. In other words, the return value is the result of reduceFunction for each item where filterFunction returns true.

Note that while filterFunction is called concurrently, only one thread at a time will call reduceFunction. The order in which reduceFunction is called is undefined if reduceOptions is QtConcurrent::UnorderedReduce. If reduceOptions is QtConcurrent::OrderedReduce, the reduceFunction is called in the order of the original sequence.

See also Concurrent Filter and Filter-Reduce.

QFuture<void> QtConcurrent::map(Sequence &sequence, MapFunctor function)

Calls function once for each item in sequence. The function is passed a reference to the item, so that any modifications done to the item will appear in sequence.

See also Concurrent Map and Map-Reduce.

QFuture<void> QtConcurrent::map(Iterator begin, Iterator end, MapFunctor function)

Calls function once for each item from begin to end. The function is passed a reference to the item, so that any modifications done to the item will appear in the sequence which the iterators belong to.

See also Concurrent Map and Map-Reduce.

QFuture<typename QtPrivate::MapResultType<void, MapFunctor>::ResultType> QtConcurrent::mapped(const Sequence &sequence, MapFunctor function)

Calls function once for each item in sequence and returns a future with each mapped item as a result. You can use QFuture::const_iterator or QFutureIterator to iterate through the results.

See also Concurrent Map and Map-Reduce.

QFuture<typename QtPrivate::MapResultType<void, MapFunctor>::ResultType> QtConcurrent::mapped(Iterator begin, Iterator end, MapFunctor function)

Calls function once for each item from begin to end and returns a future with each mapped item as a result. You can use QFuture::const_iterator or QFutureIterator to iterate through the results.

See also Concurrent Map and Map-Reduce.

QFuture<ResultType> QtConcurrent::mappedReduced(const Sequence &sequence, MapFunctor mapFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions = ReduceOptions(UnorderedReduce | SequentialReduce))

Calls mapFunction once for each item in sequence. The return value of each mapFunction is passed to reduceFunction.

Note that while mapFunction is called concurrently, only one thread at a time will call reduceFunction. The order in which reduceFunction is called is determined by reduceOptions.

See also Concurrent Map and Map-Reduce.

QFuture<ResultType> QtConcurrent::mappedReduced(Iterator begin, Iterator end, MapFunctor mapFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions = ReduceOptions(UnorderedReduce | SequentialReduce))

Calls mapFunction once for each item from begin to end. The return value of each mapFunction is passed to reduceFunction.

Note that while mapFunction is called concurrently, only one thread at a time will call reduceFunction. By default, the order in which reduceFunction is called is undefined.

Note: QtConcurrent::OrderedReduce results in the ordered reduction.

See also Concurrent Map and Map-Reduce.

QFuture<T> QtConcurrent::run(Function function, ...)

Equivalent to

QtConcurrent::run(QThreadPool::globalInstance(), function, ...);

Runs function in a separate thread. The thread is taken from the global QThreadPool. Note that function may not run immediately; function will only be run once a thread becomes available.

T is the same type as the return value of function. Non-void return values can be accessed via the QFuture::result() function.

Note: The QFuture returned can only be used to query for the running/finished status and the return value of the function. In particular, canceling or pausing can be issued only if the computations behind the future has not been started.

See also Concurrent Run.

QFuture<T> QtConcurrent::run(QThreadPool *pool, Function function, ...)

Runs function in a separate thread. The thread is taken from the QThreadPool pool. Note that function may not run immediately; function will only be run once a thread becomes available.

T is the same type as the return value of function. Non-void return values can be accessed via the QFuture::result() function.

Note: The QFuture returned can only be used to query for the running/finished status and the return value of the function. In particular, canceling or pausing can be issued only if the computations behind the future has not been started.

This function was introduced in Qt 5.4.

See also Concurrent Run.