1 files changed, 330 insertions, 0 deletions
diff --git a/src/concurrent/qtconcurrentfilter.cpp b/src/concurrent/qtconcurrentfilter.cpp
new file mode 100644
index 0000000000..76ce8ca659
--- /dev/null
+++ b/src/concurrent/qtconcurrentfilter.cpp
@@ -0,0 +1,330 @@
+/****************************************************************************
+**
+** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: http://www.qt-project.org/
+**
+** 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()
+*/