QtConcurrent::run: allow to select the thread pool on which to run the task

This is the second and last part of the forward-port of
https://qt.gitorious.org/qt/qt/merge_requests/1281

[ChangeLog][QtConcurrent] run() now optionally takes as its first argument
the QThreadPool to run the task on.

Task-number: QTBUG-17220
Change-Id: I4b46eca6ef7de9cd34dac07e6d4b8ad830426b97
Reviewed-by: Olivier Goffart <ogoffart@woboq.com>

1 files changed, 29 insertions, 2 deletions

diff --git a/src/concurrent/qtconcurrentrun.cpp b/src/concurrent/qtconcurrentrun.cpp
index c71fc9048f..0b557f054c 100644
--- a/src/concurrent/qtconcurrentrun.cpp
+++ b/src/concurrent/qtconcurrentrun.cpp
@@ -59,6 +59,11 @@
     QThreadPool. You can use the QFuture and QFutureWatcher classes to monitor
     the status of the function.
 
+    To use a dedicated thread pool, you can pass the QThreadPool as
+    the first argument:
+
+    \snippet code/src_concurrent_qtconcurrentrun.cpp explicit-pool-0
+
     \section1 Passing Arguments to the Function
 
     Passing arguments to the function is done by adding them to the
@@ -130,9 +135,31 @@
 /*!
     \fn QFuture<T> QtConcurrent::run(Function function, ...);
 
+    Equivalent to
+    \code
+    QtConcurrent::run(QThreadPool::globalInstance(), function, ...);
+    \endcode
+
     Runs \a function in a separate thread. The thread is taken from the global
-    QThreadPool. Note that the function may not run immediately; the function
-    will only be run when a thread is available.
+    QThreadPool. Note that \a function may not run immediately; \a function
+    will only be run once a thread becomes available.
+
+    T is the same type as the return value of \a function. Non-void return
+    values can be accessed via the QFuture::result() function.
+
+    Note that the QFuture returned by QtConcurrent::run() does not support
+    canceling, pausing, or progress reporting. The QFuture returned can only
+    be used to query for the running/finished status and the return value of
+    the function.
+*/
+
+/*!
+    \since 5.4
+    \fn QFuture<T> QtConcurrent::run(QThreadPool *pool, Function function, ...);
+
+    Runs \a function in a separate thread. The thread is taken from the
+    QThreadPool \a pool. Note that \a function may not run immediately; \a function
+    will only be run once a thread becomes available.
 
     T is the same type as the return value of \a function. Non-void return
     values can be accessed via the QFuture::result() function.