/**************************************************************************** | |
** | |
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). | |
** All rights reserved. | |
** Contact: Nokia Corporation (qt-info@nokia.com) | |
** | |
** This file is part of the QtCore module of the Qt Toolkit. | |
** | |
** $QT_BEGIN_LICENSE:LGPL$ | |
** GNU Lesser General Public License Usage | |
** This file may be used under the terms of the GNU Lesser General Public | |
** License version 2.1 as published by the Free Software Foundation and | |
** appearing in the file LICENSE.LGPL included in the packaging of this | |
** file. Please review the following information to ensure the GNU Lesser | |
** General Public License version 2.1 requirements will be met: | |
** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html. | |
** | |
** In addition, as a special exception, Nokia gives you certain additional | |
** rights. These rights are described in the Nokia Qt LGPL Exception | |
** version 1.1, included in the file LGPL_EXCEPTION.txt in this package. | |
** | |
** GNU General Public License Usage | |
** Alternatively, this file may be used under the terms of the GNU General | |
** Public License version 3.0 as published by the Free Software Foundation | |
** and appearing in the file LICENSE.GPL included in the packaging of this | |
** file. Please review the following information to ensure the GNU General | |
** Public License version 3.0 requirements will be met: | |
** http://www.gnu.org/copyleft/gpl.html. | |
** | |
** Other Usage | |
** Alternatively, this file may be used in accordance with the terms and | |
** conditions contained in a signed written agreement between you and Nokia. | |
** | |
** | |
** | |
** | |
** | |
** $QT_END_LICENSE$ | |
** | |
****************************************************************************/ | |
/*! | |
\headerfile <QtConcurrentFilter> | |
\title Concurrent Filter and Filter-Reduce | |
\ingroup thread | |
\brief The <QtConcurrentFilter> header provides concurrent Filter and | |
Filter-Reduce. | |
These functions are a part of the \l {Concurrent Programming}{Qt Concurrent} framework. | |
The QtConcurrent::filter(), QtConcurrent::filtered() and | |
QtConcurrent::filteredReduced() functions filter items in a sequence such | |
as a QList or a QVector in parallel. QtConcurrent::filter() modifies a | |
sequence in-place, QtConcurrent::filtered() returns a new sequence | |
containing the filtered content, and QtConcurrent::filteredReduced() | |
returns a single result. | |
Each of the above functions have a blocking variant that returns the final | |
result instead of a QFuture. You use them in the same way as the | |
asynchronous variants. | |
\snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 6 | |
Note that the result types above are not QFuture objects, but real result | |
types (in this case, QStringList and QSet<QString>). | |
\section1 Concurrent Filter | |
QtConcurrent::filtered() takes an input sequence and a filter function. | |
This filter function is then called for each item in the sequence, and a | |
new sequence containing the filtered values is returned. | |
The filter function must be of the form: | |
\snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 0 | |
T must match the type stored in the sequence. The function returns true if | |
the item should be kept, false if it should be discarded. | |
This example shows how to keep strings that are all lower-case from a | |
QStringList: | |
\snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 1 | |
The results of the filter are made available through QFuture. See the | |
QFuture and QFutureWatcher documentation for more information on how to | |
use QFuture in your applications. | |
If you want to modify a sequence in-place, use QtConcurrent::filter(): | |
\snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 2 | |
Since the sequence is modified in place, QtConcurrent::filter() does not | |
return any results via QFuture. However, you can still use QFuture and | |
QFutureWatcher to monitor the status of the filter. | |
\section1 Concurrent Filter-Reduce | |
QtConcurrent::filteredReduced() is similar to QtConcurrent::filtered(), | |
but instead of returing a sequence with the filtered results, the results | |
are combined into a single value using a reduce function. | |
The reduce function must be of the form: | |
\snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 3 | |
T is the type of the final result, U is the type of items being filtered. | |
Note that the return value and return type of the reduce function are not | |
used. | |
Call QtConcurrent::filteredReduced() like this: | |
\snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 4 | |
The reduce function will be called once for each result kept by the filter | |
function, and should merge the \e{intermediate} into the \e{result} | |
variable. QtConcurrent::filteredReduced() guarantees that only one thread | |
will call reduce at a time, so using a mutex to lock the result variable | |
is not necessary. The QtConcurrent::ReduceOptions enum provides a way to | |
control the order in which the reduction is done. | |
\section1 Additional API Features | |
\section2 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: | |
\snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 5 | |
\section2 Using Member Functions | |
QtConcurrent::filter(), QtConcurrent::filtered(), and | |
QtConcurrent::filteredReduced() accept pointers to member functions. | |
The member function class type must match the type stored in the sequence: | |
\snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 7 | |
Note that when using QtConcurrent::filteredReduced(), you can mix the use of | |
normal and member functions freely: | |
\snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 8 | |
\section2 Using Function Objects | |
QtConcurrent::filter(), QtConcurrent::filtered(), and | |
QtConcurrent::filteredReduced() 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: | |
\snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 13 | |
\section2 Using Bound Function Arguments | |
Note that Qt does not provide support for bound functions. This is | |
provided by 3rd party libraries like | |
\l{http://www.boost.org/libs/bind/bind.html}{Boost} or | |
\l{http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf} | |
{C++ TR1 Library Extensions}. | |
If you want to use a filter function 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 use QString::contains(): | |
\snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 9 | |
QString::contains() takes 2 arguments (including the "this" pointer) and | |
can't be used with QtConcurrent::filtered() directly, because | |
QtConcurrent::filtered() expects a function that takes one argument. To | |
use QString::contains() with QtConcurrent::filtered() we have to provide a | |
value for the \e regexp argument: | |
\snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 10 | |
The return value from boost::bind() is a function object (functor) with | |
the following signature: | |
\snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 11 | |
This matches what QtConcurrent::filtered() expects, and the complete | |
example becomes: | |
\snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentfilter.cpp 12 | |
*/ | |
/*! | |
\fn QFuture<void> QtConcurrent::filter(Sequence &sequence, FilterFunction filterFunction) | |
\relates <QtConcurrentFilter> | |
Calls \a filterFunction once for each item in \a sequence. If | |
\a filterFunction returns true, the item is kept in \a sequence; | |
otherwise, the item is removed from \a sequence. | |
*/ | |
/*! | |
\fn QFuture<T> QtConcurrent::filtered(const Sequence &sequence, FilterFunction filterFunction) | |
\relates <QtConcurrentFilter> | |
Calls \a filterFunction once for each item in \a sequence and returns a | |
new Sequence of kept items. If \a filterFunction returns true, a copy of | |
the item is put in the new Sequence. Otherwise, the item will \e not | |
appear in the new Sequence. | |
*/ | |
/*! | |
\fn QFuture<T> QtConcurrent::filtered(ConstIterator begin, ConstIterator end, FilterFunction filterFunction) | |
\relates <QtConcurrentFilter> | |
Calls \a filterFunction once for each item from \a begin to \a end and | |
returns a new Sequence of kept items. If \a filterFunction returns true, a | |
copy of the item is put in the new Sequence. Otherwise, the item will | |
\e not appear in the new Sequence. | |
*/ | |
/*! | |
\fn QFuture<T> QtConcurrent::filteredReduced(const Sequence &sequence, FilterFunction filterFunction, ReduceFunction reduceFunction, QtConcurrent::ReduceOptions reduceOptions) | |
\relates <QtConcurrentFilter> | |
Calls \a filterFunction once for each item in \a sequence. If | |
\a filterFunction returns true for an item, that item is then passed to | |
\a reduceFunction. In other words, the return value is the result of | |
\a reduceFunction for each item where \a filterFunction returns true. | |
Note that while \a filterFunction is called concurrently, only one thread | |
at a time will call \a reduceFunction. The order in which \a reduceFunction | |
is called is undefined if \a reduceOptions is | |
QtConcurrent::UnorderedReduce. If \a reduceOptions is | |
QtConcurrent::OrderedReduce, \a reduceFunction is called in the order of | |
the original sequence. | |
*/ | |
/*! | |
\fn QFuture<T> QtConcurrent::filteredReduced(ConstIterator begin, ConstIterator end, FilterFunction filterFunction, ReduceFunction reduceFunction, QtConcurrent::ReduceOptions reduceOptions) | |
\relates <QtConcurrentFilter> | |
Calls \a filterFunction once for each item from \a begin to \a end. If | |
\a filterFunction returns true for an item, that item is then passed to | |
\a reduceFunction. In other words, the return value is the result of | |
\a reduceFunction for each item where \a filterFunction returns true. | |
Note that while \a filterFunction is called concurrently, only one thread | |
at a time will call \a reduceFunction. The order in which | |
\a reduceFunction is called is undefined if \a reduceOptions is | |
QtConcurrent::UnorderedReduce. If \a reduceOptions is | |
QtConcurrent::OrderedReduce, the \a reduceFunction is called in the order | |
of the original sequence. | |
*/ | |
/*! | |
\fn void QtConcurrent::blockingFilter(Sequence &sequence, FilterFunction filterFunction) | |
Calls \a filterFunction once for each item in \a sequence. If | |
\a filterFunction returns true, the item is kept in \a sequence; | |
otherwise, the item is removed from \a sequence. | |
\note This function will block until all items in the sequence have been processed. | |
*/ | |
/*! | |
\fn Sequence QtConcurrent::blockingFiltered(const Sequence &sequence, FilterFunction filterFunction) | |
Calls \a filterFunction once for each item in \a sequence and returns a | |
new Sequence of kept items. If \a filterFunction returns true, a copy of | |
the item is put in the new Sequence. Otherwise, the item will \e not | |
appear in the new Sequence. | |
\note This function will block until all items in the sequence have been processed. | |
\sa filtered() | |
*/ | |
/*! | |
\fn Sequence QtConcurrent::blockingFiltered(ConstIterator begin, ConstIterator end, FilterFunction filterFunction) | |
Calls \a filterFunction once for each item from \a begin to \a end and | |
returns a new Sequence of kept items. If \a filterFunction returns true, a | |
copy of the item is put in the new Sequence. Otherwise, the item will | |
\e not appear in the new Sequence. | |
\note This function will block until the iterator reaches the end of the | |
sequence being processed. | |
\sa filtered() | |
*/ | |
/*! | |
\fn T QtConcurrent::blockingFilteredReduced(const Sequence &sequence, FilterFunction filterFunction, ReduceFunction reduceFunction, QtConcurrent::ReduceOptions reduceOptions) | |
Calls \a filterFunction once for each item in \a sequence. If | |
\a filterFunction returns true for an item, that item is then passed to | |
\a reduceFunction. In other words, the return value is the result of | |
\a reduceFunction for each item where \a filterFunction returns true. | |
Note that while \a filterFunction is called concurrently, only one thread | |
at a time will call \a reduceFunction. The order in which \a reduceFunction | |
is called is undefined if \a reduceOptions is | |
QtConcurrent::UnorderedReduce. If \a reduceOptions is | |
QtConcurrent::OrderedReduce, \a reduceFunction is called in the order of | |
the original sequence. | |
\note This function will block until all items in the sequence have been processed. | |
\sa filteredReduced() | |
*/ | |
/*! | |
\fn T QtConcurrent::blockingFilteredReduced(ConstIterator begin, ConstIterator end, FilterFunction filterFunction, ReduceFunction reduceFunction, QtConcurrent::ReduceOptions reduceOptions) | |
Calls \a filterFunction once for each item from \a begin to \a end. If | |
\a filterFunction returns true for an item, that item is then passed to | |
\a reduceFunction. In other words, the return value is the result of | |
\a reduceFunction for each item where \a filterFunction returns true. | |
Note that while \a filterFunction is called concurrently, only one thread | |
at a time will call \a reduceFunction. The order in which | |
\a reduceFunction is called is undefined if \a reduceOptions is | |
QtConcurrent::UnorderedReduce. If \a reduceOptions is | |
QtConcurrent::OrderedReduce, the \a 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. | |
\sa filteredReduced() | |
*/ |