diff options
Diffstat (limited to 'src/corelib/concurrent/qtconcurrentfilter.cpp')
-rw-r--r-- | src/corelib/concurrent/qtconcurrentfilter.cpp | 330 |
1 files changed, 330 insertions, 0 deletions
diff --git a/src/corelib/concurrent/qtconcurrentfilter.cpp b/src/corelib/concurrent/qtconcurrentfilter.cpp new file mode 100644 index 0000000..4fbda82 --- /dev/null +++ b/src/corelib/concurrent/qtconcurrentfilter.cpp @@ -0,0 +1,330 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (qt-info@nokia.com) +** +** This file is part of the QtCore module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** No Commercial Usage +** This file contains pre-release code and may not be distributed. +** You may use this file in accordance with the terms and conditions +** contained in the either Technology Preview License Agreement or the +** Beta Release License Agreement. +** +** GNU Lesser General Public License Usage +** Alternatively, 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.0, 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. +** +** If you are unsure which license is appropriate for your use, please +** contact the sales department at qt-sales@nokia.com. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \headerfile <QtConcurrentFilter> + \title Concurrent Filter and Filter-Reduce + \ingroup threading + + \brief The <QtConcurrentFilter> header provides concurrent Filter and + Filter-Reduce. + + These functions are a part of the \l {threads.html#qtconcurrent-intro}{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 neccesary. 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() +*/ |