diff options
Diffstat (limited to 'src/concurrent/doc')
11 files changed, 487 insertions, 264 deletions
diff --git a/src/concurrent/doc/qtconcurrent.qdocconf b/src/concurrent/doc/qtconcurrent.qdocconf index 356d602a7c..c4efe64d0a 100644 --- a/src/concurrent/doc/qtconcurrent.qdocconf +++ b/src/concurrent/doc/qtconcurrent.qdocconf @@ -1,4 +1,5 @@ include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf) +include($QT_INSTALL_DOCS/config/exampleurl-qtbase.qdocconf) project = QtConcurrent description = Qt Concurrent Reference Documentation @@ -14,33 +15,33 @@ qhp.QtConcurrent.virtualFolder = qtconcurrent qhp.QtConcurrent.indexTitle = Qt Concurrent qhp.QtConcurrent.indexRoot = -qhp.QtConcurrent.filterAttributes = qtconcurrent $QT_VERSION qtrefdoc -qhp.QtConcurrent.customFilters.Qt.name = QtConcurrent $QT_VERSION -qhp.QtConcurrent.customFilters.Qt.filterAttributes = qtconcurrent $QT_VERSION - -qhp.QtConcurrent.subprojects = classes +qhp.QtConcurrent.subprojects = classes examples qhp.QtConcurrent.subprojects.classes.title = C++ Classes qhp.QtConcurrent.subprojects.classes.indexTitle = Qt Concurrent C++ Classes qhp.QtConcurrent.subprojects.classes.selectors = class fake:headerfile qhp.QtConcurrent.subprojects.classes.sortPages = true +qhp.QtConcurrent.subprojects.examples.title = Qt Concurrent Examples +qhp.QtConcurrent.subprojects.examples.indexTitle = Qt Concurrent Examples +qhp.QtConcurrent.subprojects.examples.selectors = fake:example tagfile = ../../../doc/qtconcurrent/qtconcurrent.tags -depends += qtcore qtdoc +depends += qtcore qtnetwork qtdoc qmake qtcmake headerdirs += .. sourcedirs += .. exampledirs += ../../../examples/qtconcurrent \ - ../ \ - snippets - -manifestmeta.highlighted.names = "QtConcurrent/QtConcurrent Progress Dialog Example" + snippets \ + . -excludedirs += ../../../examples/widgets/doc +excludedirs += snippets imagedirs += images navigation.landingpage = "Qt Concurrent" navigation.cppclassespage = "Qt Concurrent C++ Classes" + +# Enforce zero documentation warnings +warninglimit = 0 diff --git a/src/concurrent/doc/snippets/CMakeLists.txt b/src/concurrent/doc/snippets/CMakeLists.txt new file mode 100644 index 0000000000..03ebb75a2e --- /dev/null +++ b/src/concurrent/doc/snippets/CMakeLists.txt @@ -0,0 +1,7 @@ +# Copyright (C) 2022 The Qt Company Ltd. +# SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +#! [cmake_use] +find_package(Qt6 REQUIRED COMPONENTS Concurrent) +target_link_libraries(mytarget PRIVATE Qt6::Concurrent) +#! [cmake_use] diff --git a/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentfilter.cpp b/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentfilter.cpp index 3cc1fe836c..1ea7deace5 100644 --- a/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentfilter.cpp +++ b/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentfilter.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] bool function(const T &t); @@ -82,7 +35,7 @@ void addToDictionary(QSet<QString> &dictionary, const QString &string) } QStringList strings = ...; -QFuture<QSet<QString> > dictionary = QtConcurrent::filteredReduced(strings, allLowerCase, addToDictionary); +QFuture<QSet<QString>> dictionary = QtConcurrent::filteredReduced(strings, allLowerCase, addToDictionary); //! [4] @@ -93,7 +46,7 @@ QFuture<QString> lowerCaseStrings = QtConcurrent::filtered(strings.constBegin(), // filter in-place only works on non-const iterators QFuture<void> future = QtConcurrent::filter(strings.begin(), strings.end(), allLowerCase); -QFuture<QSet<QString> > dictionary = QtConcurrent::filteredReduced(strings.constBegin(), strings.constEnd(), allLowerCase, addToDictionary); +QFuture<QSet<QString>> dictionary = QtConcurrent::filteredReduced(strings.constBegin(), strings.constEnd(), allLowerCase, addToDictionary); //! [5] @@ -121,7 +74,8 @@ QFuture<QImage> grayscaleImages = QtConcurrent::filtered(images, &QImage::isGray // create a set of all printable characters QList<QChar> characters = ...; -QFuture<QSet<QChar> > set = QtConcurrent::filteredReduced(characters, &QChar::isPrint, &QSet<QChar>::insert); +QFuture<QSet<QChar>> set = QtConcurrent::filteredReduced(characters, qOverload<>(&QChar::isPrint), + qOverload<const QChar&>(&QSet<QChar>::insert)); //! [7] @@ -131,7 +85,8 @@ QFuture<QSet<QChar> > set = QtConcurrent::filteredReduced(characters, &QChar::is // create a dictionary of all lower cased strings extern bool allLowerCase(const QString &string); QStringList strings = ...; -QFuture<QSet<int> > averageWordLength = QtConcurrent::filteredReduced(strings, allLowerCase, QSet<QString>::insert); +QFuture<QSet<QString>> lowerCase = QtConcurrent::filteredReduced(strings, allLowerCase, + qOverload<const QString&>(&QSet<QString>::insert)); // create a collage of all gray scale images extern void addToCollage(QImage &collage, const QImage &grayscaleImage); @@ -158,8 +113,6 @@ struct StartsWith StartsWith(const QString &string) : m_string(string) { } - typedef bool result_type; - bool operator()(const QString &testString) { return testString.startsWith(m_string); @@ -179,7 +132,59 @@ struct StringTransform }; QFuture<QString> fooString = - QtConcurrent::filteredReduced<QString>(strings, - StartsWith(QLatin1String("Foo")), - StringTransform()); + QtConcurrent::filteredReduced(strings, StartsWith(QLatin1String("Foo")), StringTransform()); //! [14] + +//! [15] +// keep only even integers +QList<int> list { 1, 2, 3, 4 }; +QtConcurrent::blockingFilter(list, [](int n) { return (n & 1) == 0; }); + +// retrieve only even integers +QList<int> list2 { 1, 2, 3, 4 }; +QFuture<int> future = QtConcurrent::filtered(list2, [](int x) { + return (x & 1) == 0; +}); +QList<int> results = future.results(); + +// add up all even integers +QList<int> list3 { 1, 2, 3, 4 }; +QFuture<int> sum = QtConcurrent::filteredReduced(list3, + [](int x) { + return (x & 1) == 0; + }, + [](int &sum, int x) { + sum += x; + } +); +//! [15] + +//! [16] +void intSumReduce(int &sum, int x) +{ + sum += x; +} + +QList<int> list { 1, 2, 3, 4 }; +QFuture<int> sum = QtConcurrent::filteredReduced(list, + [] (int x) { + return (x & 1) == 0; + }, + intSumReduce +); +//! [16] + +//! [17] +bool keepEvenIntegers(int x) +{ + return (x & 1) == 0; +} + +QList<int> list { 1, 2, 3, 4 }; +QFuture<int> sum = QtConcurrent::filteredReduced(list, + keepEvenIntegers, + [](int &sum, int x) { + sum += x; + } +); +//! [17] diff --git a/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentmap.cpp b/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentmap.cpp index fc574302d2..35345c6f24 100644 --- a/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentmap.cpp +++ b/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentmap.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] U function(const T &t); @@ -130,11 +83,13 @@ QFuture<void> squeezedStrings = QtConcurrent::map(strings, &QString::squeeze); // Swap the rgb values of all pixels on a list of images. QList<QImage> images = ...; -QFuture<QImage> bgrImages = QtConcurrent::mapped(images, &QImage::rgbSwapped); +QFuture<QImage> bgrImages = QtConcurrent::mapped(images, + static_cast<QImage (QImage::*)() const &>(&QImage::rgbSwapped)); // Create a set of the lengths of all strings in a list. QStringList strings = ...; -QFuture<QSet<int> > wordLengths = QtConcurrent::mappedReduced(strings, &QString::length, &QSet<int>::insert); +QFuture<QSet<int>> wordLengths = QtConcurrent::mappedReduced(strings, &QString::length, + qOverload<const int&>(&QSet<int>::insert)); //! [8] @@ -149,7 +104,8 @@ QFuture<int> averageWordLength = QtConcurrent::mappedReduced(strings, &QString:: // Create a set of the color distribution of all images in a list. extern int colorDistribution(const QImage &string); QList<QImage> images = ...; -QFuture<QSet<int> > totalColorDistribution = QtConcurrent::mappedReduced(images, colorDistribution, QSet<int>::insert); +QFuture<QSet<int>> totalColorDistribution = QtConcurrent::mappedReduced(images, colorDistribution, + qOverload<const int&>(&QSet<int>::insert)); //! [9] @@ -164,10 +120,8 @@ struct ImageTransform }; QFuture<QImage> thumbNails = - QtConcurrent::mappedReduced<QImage>(images, - Scaled(100), - ImageTransform(), - QtConcurrent::SequentialReduce); + QtConcurrent::mappedReduced(images, Scaled(100), ImageTransform(), + QtConcurrent::SequentialReduce); //! [11] //! [13] @@ -197,3 +151,37 @@ struct Scaled QList<QImage> images = ...; QFuture<QImage> thumbnails = QtConcurrent::mapped(images, Scaled(100)); //! [14] + +//! [15] +QList<int> vector { 1, 2, 3, 4 }; +QtConcurrent::blockingMap(vector, [](int &x) { x *= 2; }); + +int size = 100; +QList<QImage> images = ...; + +QList<QImage> thumbnails = QtConcurrent::mapped(images, + [&size](const QImage &image) { + return image.scaled(size, size); + } + ).results(); +//! [15] + +//! [16] +QList<QImage> collage = QtConcurrent::mappedReduced(images, + [&size](const QImage &image) { + return image.scaled(size, size); + }, + addToCollage + ).results(); +//! [16] + +//! [17] +QList<QImage> collage = QtConcurrent::mappedReduced(images, + [&size](const QImage &image) { + return image.scaled(size, size); + }, + [](QImage &result, const QImage &value) { + // do some transformation + } + ).results(); +//! [17] diff --git a/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentrun.cpp b/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentrun.cpp index 5437822842..f934abdd9e 100644 --- a/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentrun.cpp +++ b/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrentrun.cpp @@ -1,52 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:BSD$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** BSD License Usage -** Alternatively, you may use this file under the terms of the BSD license -** as follows: -** -** "Redistribution and use in source and binary forms, with or without -** modification, are permitted provided that the following conditions are -** met: -** * Redistributions of source code must retain the above copyright -** notice, this list of conditions and the following disclaimer. -** * Redistributions in binary form must reproduce the above copyright -** notice, this list of conditions and the following disclaimer in -** the documentation and/or other materials provided with the -** distribution. -** * Neither the name of The Qt Company Ltd nor the names of its -** contributors may be used to endorse or promote products derived -** from this software without specific prior written permission. -** -** -** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." -** -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause //! [0] extern void aFunction(); @@ -93,7 +46,7 @@ QString result = future.result(); //! [4] // call 'QList<QByteArray> QByteArray::split(char sep) const' in a separate thread QByteArray bytearray = "hello world"; -QFuture<QList<QByteArray> > future = QtConcurrent::run(bytearray, &QByteArray::split, ','); +QFuture<QList<QByteArray> > future = QtConcurrent::run(&QByteArray::split, bytearray, ' '); ... QList<QByteArray> result = future.result(); //! [4] @@ -101,16 +54,150 @@ QList<QByteArray> result = future.result(); //! [5] // call 'void QImage::invertPixels(InvertMode mode)' in a separate thread QImage image = ...; -QFuture<void> future = QtConcurrent::run(&image, &QImage::invertPixels, QImage::InvertRgba); +QFuture<void> future = QtConcurrent::run(&QImage::invertPixels, &image, QImage::InvertRgba); ... future.waitForFinished(); // At this point, the pixels in 'image' have been inverted //! [5] - //! [6] QFuture<void> future = QtConcurrent::run([=]() { // Code in this block will run in another thread }); ... //! [6] + +//! [7] +static void addOne(int &n) { ++n; } +... +int n = 42; +QtConcurrent::run(&addOne, std::ref(n)).waitForFinished(); // n == 43 +//! [7] + +//! [8] +struct TestClass +{ + void operator()(int s1) { s = s1; } + int s = 42; +}; + +... + +TestClass o; + +// Modify original object +QtConcurrent::run(std::ref(o), 15).waitForFinished(); // o.s == 15 + +// Modify a copy of the original object +QtConcurrent::run(o, 42).waitForFinished(); // o.s == 15 + +// Use a temporary object +QtConcurrent::run(TestClass(), 42).waitForFinished(); + +// Ill-formed +QtConcurrent::run(&o, 42).waitForFinished(); // compilation error +//! [8] + +//! [9] +extern void aFunction(QPromise<void> &promise); +QFuture<void> future = QtConcurrent::run(aFunction); +//! [9] + +//! [10] +extern void aFunction(QPromise<void> &promise, int arg1, const QString &arg2); + +int integer = ...; +QString string = ...; + +QFuture<void> future = QtConcurrent::run(aFunction, integer, string); +//! [10] + +//! [11] +void helloWorldFunction(QPromise<QString> &promise) +{ + promise.addResult("Hello"); + promise.addResult("world"); +} + +QFuture<QString> future = QtConcurrent::run(helloWorldFunction); +... +QList<QString> results = future.results(); +//! [11] + +//! [12] +void aFunction(QPromise<int> &promise) +{ + for (int i = 0; i < 100; ++i) { + promise.suspendIfRequested(); + if (promise.isCanceled()) + return; + + // computes the next result, may be time consuming like 1 second + const int res = ... ; + promise.addResult(res); + } +} + +QFuture<int> future = QtConcurrent::run(aFunction); + +... // user pressed a pause button after 10 seconds +future.suspend(); + +... // user pressed a resume button after 10 seconds +future.resume(); + +... // user pressed a cancel button after 10 seconds +future.cancel(); +//! [12] + +//! [13] +void aFunction(QPromise<int> &promise) +{ + promise.setProgressRange(0, 100); + int result = 0; + for (int i = 0; i < 100; ++i) { + // computes some part of the task + const int part = ... ; + result += part; + promise.setProgressValue(i); + } + promise.addResult(result); +} + +QFutureWatcher<int> watcher; +QObject::connect(&watcher, &QFutureWatcher::progressValueChanged, [](int progress){ + ... ; // update GUI with a progress + qDebug() << "current progress:" << progress; +}); +watcher.setFuture(QtConcurrent::run(aFunction)); +//! [13] + +//! [14] +struct Functor { + void operator()(QPromise<int> &) { } + void operator()(QPromise<double> &) { } +}; + +Functor f; +run<double>(f); // this will select the 2nd overload +// run(f); // error, both candidate overloads potentially match +//! [14] + +//! [15] +void foo(int arg); +void foo(int arg1, int arg2); +... +QFuture<void> future = QtConcurrent::run(foo, 42); +//! [15] + +//! [16] +QFuture<void> future = QtConcurrent::run([] { foo(42); }); +//! [16] + +//! [17] +QFuture<void> future = QtConcurrent::run(static_cast<void(*)(int)>(foo), 42); +//! [17] + +//! [18] +QFuture<void> future = QtConcurrent::run(qOverload<int>(foo), 42); +//! [18] diff --git a/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrenttask.cpp b/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrenttask.cpp new file mode 100644 index 0000000000..cb1889afb6 --- /dev/null +++ b/src/concurrent/doc/snippets/code/src_concurrent_qtconcurrenttask.cpp @@ -0,0 +1,93 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause + +//! [0] +QtConcurrent::task([]{ qDebug("Hello, world!"); }).spawn(); +//! [0] + +//! [1] +auto task = [](const QString &s){ qDebug() << ("Hello, " + s); }; +QtConcurrent::task(std::move(task)) + .withArguments("world!") + .spawn(); +//! [1] + +//! [2] +QString s("Hello, "); +QtConcurrent::task([](QString &s){ s.append("world!"); }) + .withArguments(std::ref(s)) + .spawn(); +//! [2] + +//! [3] +auto future = QtConcurrent::task([]{ return 42; }).spawn(); +auto result = future.result(); // result == 42 +//! [3] + +//! [4] +std::is_invocable_v<std::decay_t<Task>, std::decay_t<Args>...> +//! [4] + +//! [5] +QVariant value(42); +auto result = QtConcurrent::task([](const QVariant &var){return qvariant_cast<int>(var);}) + .withArguments(value) + .spawn() + .result(); // result == 42 +//! [5] + +//! [6] +QString result("Hello, world!"); + +QtConcurrent::task(&QString::chop) + .withArguments(&result, 8) + .spawn() + .waitForFinished(); // result == "Hello" +//! [6] + +//! [7] +auto result = QtConcurrent::task(std::plus<int>()) + .withArguments(40, 2) + .spawn() + .result() // result == 42 +//! [7] + +//! [8] +struct CallableWithState +{ + void operator()(int newState) { state = newState; } + + // ... +}; + +// ... + +CallableWithState object; + +QtConcurrent::task(std::ref(object)) + .withArguments(42) + .spawn() + .waitForFinished(); // The object's state is set to 42 +//! [8] + +//! [9] +QThreadPool pool; +QtConcurrent::task([]{ return 42; }).onThreadPool(pool).spawn(); +//! [9] + +//! [10] +QtConcurrent::task([]{ return 42; }).withPriority(10).spawn(); +//! [10] + +//! [11] +QtConcurrent::task([]{ qDebug("Hello, world!"); }).spawn(FutureResult::Ignore); +//! [11] + +//! [12] +void increment(QPromise<int> &promise, int i) +{ + promise.addResult(i + 1); +} + +int result = QtConcurrent::task(&increment).withArguments(10).spawn().result(); // result == 11 +//! [12] diff --git a/src/concurrent/doc/snippets/snippets.pro b/src/concurrent/doc/snippets/snippets.pro new file mode 100644 index 0000000000..6e99051951 --- /dev/null +++ b/src/concurrent/doc/snippets/snippets.pro @@ -0,0 +1,3 @@ +#! [qmake_use] +QT += concurrent +#! [qmake_use] diff --git a/src/concurrent/doc/src/qt6-changes.qdoc b/src/concurrent/doc/src/qt6-changes.qdoc new file mode 100644 index 0000000000..fa23ee21a7 --- /dev/null +++ b/src/concurrent/doc/src/qt6-changes.qdoc @@ -0,0 +1,57 @@ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \page concurrent-changes-qt6.html + \title Changes to Qt Concurrent + \ingroup changes-qt-5-to-6 + \brief Improved to work with a variable number of arguments. + + Qt 6 is a result of the conscious effort to make the framework more + efficient and easy to use. + + We try to maintain binary and source compatibility for all the public + APIs in each release. But some changes were inevitable in an effort to + make Qt a better framework. + + In this topic we summarize those changes in Qt Concurrent, and provide + guidance to handle them. + + \section1 QtConcurrent::run() + + QtConcurrent::run() has been improved to work with a variable number + of arguments, so the signatures are changed to: + + \code + // run + template <typename T> + QFuture<T> run(Function &&f, Args &&...args) + + // run with a QThreadPool argument + template <typename T> + QFuture<T> run(QThreadPool *pool, Function &&f, Args &&...args) + \endcode + + As a side effect, if \c f is a pointer to a member function, the first + argument of \c args should be the object for which that member is defined + (or a reference, or a pointer to it). So instead of writing: + + \code + QImage image = ...; + QFuture<void> future = QtConcurrent::run(&image, &QImage::invertPixels, QImage::InvertRgba); + \endcode + + You have to write: + + \code + QFuture<void> future = QtConcurrent::run(&QImage::invertPixels, &image, QImage::InvertRgba); + \endcode + + Another side effect is that \c QtConcurrent::run() will not work with + overloaded functions anymore. For example, the code below won't compile: + + \include qtconcurrentrun.cpp run-with-overload-calls + + Other methods of QtConcurrent have no behavioral changes and do not introduce + source compatibility breaks. +*/ diff --git a/src/concurrent/doc/src/qtconcurrent-examples.qdoc b/src/concurrent/doc/src/qtconcurrent-examples.qdoc new file mode 100644 index 0000000000..06705cca1b --- /dev/null +++ b/src/concurrent/doc/src/qtconcurrent-examples.qdoc @@ -0,0 +1,14 @@ +// Copyright (C) 2023 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only + +/*! + \group qtconcurrentexamples + \title Qt Concurrent Examples + \brief Examples for the Qt Concurrent module + \ingroup all-examples + \ingroup qtconcurrent + + The list of \l {Qt Concurrent} examples demonstrating how to use + Qt Concurrent API from C++. + +*/ diff --git a/src/concurrent/doc/src/qtconcurrent-index.qdoc b/src/concurrent/doc/src/qtconcurrent-index.qdoc index 3e4aa791f1..5acf19e134 100644 --- a/src/concurrent/doc/src/qtconcurrent-index.qdoc +++ b/src/concurrent/doc/src/qtconcurrent-index.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2018 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \page qtconcurrent-index.html @@ -31,18 +7,17 @@ \brief The Qt Concurrent module contains functionality to support concurrent execution of program code. - \section1 Getting Started - The QtConcurrent namespace provides high-level APIs that make it + The Qt Concurrent module provides high-level APIs that make it possible to write multi-threaded programs without using low-level threading primitives such as mutexes, read-write locks, wait - conditions, or semaphores. Programs written with QtConcurrent + conditions, or semaphores. Programs written with Qt Concurrent automatically adjust the number of threads used according to the number of processor cores available. This means that applications written today will continue to scale when deployed on multi-core systems in the future. - QtConcurrent includes functional programming style APIs for + Qt Concurrent includes functional programming style APIs for parallel list processing, including a MapReduce and FilterReduce implementation for shared-memory (non-distributed) systems, and classes for managing asynchronous computations in GUI @@ -79,6 +54,13 @@ another thread. \endlist + \li \l {Concurrent Task} + \list + \li \l {QtConcurrent::task}{QtConcurrent::task()} creates an instance + of QtConcurrent::QTaskBuilder. This object can be used for adjusting + parameters and for kicking off a task in a separate thread. + \endlist + \li QFuture represents the result of an asynchronous computation. \li QFutureIterator allows iterating through results available via QFuture. @@ -88,11 +70,16 @@ \li QFutureSynchronizer is a convenience class that automatically synchronizes several QFutures. + \li QPromise provides a way to report progress and results of the + asynchronous computation to QFuture. Allows suspending or canceling the task + when requested by QFuture. + \endlist Qt Concurrent supports several STL-compatible container and iterator types, but works best with Qt containers that have random-access iterators, such as - QList or QVector. The map and filter functions accept both containers and begin/end iterators. + QList. The map and filter functions accept both containers and begin/end + iterators. STL Iterator support overview: @@ -115,31 +102,50 @@ \li Supported \row \li Bidirectional Iterator - \li QLinkedList, std::list + \li std::list \li Supported \row \li Random Access Iterator - \li QList, QVector, std::vector + \li QList, std::vector \li Supported and Recommended \endtable - Random access iterators can be faster in cases where Qt Concurrent is iterating - over a large number of lightweight items, since they allow skipping to any point - in the container. In addition, using random access iterators allows Qt Concurrent - to provide progress information trough QFuture::progressValue() and - QFutureWatcher::progressValueChanged(). + Random access iterators can be faster in cases where Qt Concurrent is + iterating over a large number of lightweight items, since they allow + skipping to any point in the container. In addition, using random access + iterators allows Qt Concurrent to provide progress information through + QFuture::progressValue() and QFutureWatcher::progressValueChanged(). The non in-place modifying functions such as mapped() and filtered() makes a - copy of the container when called. If you are using STL containers this copy operation - might take some time, in this case we recommend specifying the begin and end iterators - for the container instead. + copy of the container when called. If you are using STL containers this copy + operation might take some time, in this case we recommend specifying the + begin and end iterators for the container instead. + + + \include module-use.qdocinc using qt module + \snippet snippets/CMakeLists.txt cmake_use + + See also the \l {Build with CMake} overview. + + \include module-use.qdocinc building with qmake + \snippet snippets/snippets.pro qmake_use + + \section1 Examples + + \list + \li \l {Qt Concurrent Examples} + \endlist + + \section1 Module Evolution + \l{Changes to Qt Concurrent} lists important changes in the module API + and functionality that were done for the Qt 6 series of Qt. \section1 Licenses - The Qt Concurrent module is available under commercial licenses from \l{The Qt Company}. - In addition, it is available under free software licenses. Since Qt 5.4, - these free software licenses are - \l{GNU Lesser General Public License, version 3}, or + The Qt Concurrent module is available under commercial licenses from + \l{The Qt Company}. + In addition, it is available under free software licenses: + The \l{GNU Lesser General Public License, version 3}, or the \l{GNU General Public License, version 2}. See \l{Qt Licensing} for further details. */ diff --git a/src/concurrent/doc/src/qtconcurrent-module.qdoc b/src/concurrent/doc/src/qtconcurrent-module.qdoc index 9289b4bfa8..ce132c13b7 100644 --- a/src/concurrent/doc/src/qtconcurrent-module.qdoc +++ b/src/concurrent/doc/src/qtconcurrent-module.qdoc @@ -1,29 +1,5 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the documentation of the Qt Toolkit. -** -** $QT_BEGIN_LICENSE:FDL$ -** Commercial License Usage -** Licensees holding valid commercial Qt licenses may use this file in -** accordance with the commercial license agreement provided with the -** Software or, alternatively, in accordance with the terms contained in -** a written agreement between you and The Qt Company. For licensing terms -** and conditions see https://www.qt.io/terms-conditions. For further -** information use the contact form at https://www.qt.io/contact-us. -** -** GNU Free Documentation License Usage -** Alternatively, this file may be used under the terms of the GNU Free -** Documentation License version 1.3 as published by the Free Software -** Foundation and appearing in the file included in the packaging of -** this file. Please review the following information to ensure -** the GNU Free Documentation License version 1.3 requirements -** will be met: https://www.gnu.org/licenses/fdl-1.3.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ +// Copyright (C) 2020 The Qt Company Ltd. +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only /*! \module QtConcurrent @@ -31,22 +7,8 @@ \brief The Qt Concurrent module contains functionality to support concurrent execution of program code. \ingroup modules + \qtcmakepackage Concurrent \qtvariable concurrent - The Qt Concurrent module extends the basic threading support found in \l{Qt Core} module and - simplifies the development of code that can be executed in parallel on all available CPU cores. -*/ - -/*! - \typedef QtConcurrent::Exception - \obsolete - - Use QException from \l{Qt Core} instead. -*/ - -/*! - \typedef QtConcurrent::UnhandledException - \obsolete - - Use QUnhandledException from \l{Qt Core} instead. + The \l{Qt Concurrent} page contains information about how to use the module. */ |