From 753a47892588b2dead91b4ce033b1510f1496fe5 Mon Sep 17 00:00:00 2001 From: Lars Knoll Date: Thu, 29 Nov 2012 10:27:52 +0100 Subject: Fixup concurrent docs qdoc now finds an overview and the concurrent namespace. Change-Id: I2cd15bc19091f53bd2bb98919e685d49d473dbec Reviewed-by: Jerome Pasion --- src/concurrent/concurrent.pro | 1 + src/concurrent/doc/src/qtconcurrent-index.qdoc | 127 ++++++++++++++++++++++++ src/concurrent/doc/src/qtconcurrent-module.qdoc | 39 ++++++++ src/concurrent/doc/src/qtconcurrent.qdoc | 40 -------- src/concurrent/qtconcurrentmap.cpp | 4 +- 5 files changed, 169 insertions(+), 42 deletions(-) create mode 100644 src/concurrent/doc/src/qtconcurrent-index.qdoc create mode 100644 src/concurrent/doc/src/qtconcurrent-module.qdoc delete mode 100644 src/concurrent/doc/src/qtconcurrent.qdoc (limited to 'src/concurrent') diff --git a/src/concurrent/concurrent.pro b/src/concurrent/concurrent.pro index 375de00344..53b6bd0472 100644 --- a/src/concurrent/concurrent.pro +++ b/src/concurrent/concurrent.pro @@ -14,6 +14,7 @@ PRECOMPILED_HEADER = ../corelib/global/qt_pch.h SOURCES += \ qtconcurrentfilter.cpp \ qtconcurrentmap.cpp \ + qtconcurrentrun.cpp \ qtconcurrentthreadengine.cpp \ qtconcurrentiteratekernel.cpp \ diff --git a/src/concurrent/doc/src/qtconcurrent-index.qdoc b/src/concurrent/doc/src/qtconcurrent-index.qdoc new file mode 100644 index 0000000000..eeb35c2326 --- /dev/null +++ b/src/concurrent/doc/src/qtconcurrent-index.qdoc @@ -0,0 +1,127 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qtconcurrent-index.html + \title Qt Concurrent + + \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 + 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 + 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 + parallel list processing, including a MapReduce and FilterReduce + implementation for shared-memory (non-distributed) systems, and + classes for managing asynchronous computations in GUI + applications: + + \list + + \li QtConcurrent::map() applies a function to every item in a container, + modifying the items in-place. + + \li QtConcurrent::mapped() is like map(), except that it returns a new + container with the modifications. + + \li QtConcurrent::mappedReduced() is like mapped(), except that the + modified results are reduced or folded into a single result. + + \li QtConcurrent::filter() removes all items from a container based on the + result of a filter function. + + \li QtConcurrent::filtered() is like filter(), except that it returns a new + container with the filtered results. + + \li QtConcurrent::filteredReduced() is like filtered(), except that the + filtered results are reduced or folded into a single result. + + \li QtConcurrent::run() runs a function in another thread. + + \li QFuture represents the result of an asynchronous computation. + + \li QFutureIterator allows iterating through results available via QFuture. + + \li QFutureWatcher allows monitoring a QFuture using signals-and-slots. + + \li QFutureSynchronizer is a convenience class that automatically + synchronizes several QFutures. + + \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. + + STL Iterator support overview: + + \table + \header + \li Iterator Type + \li Example classes + \li Support status + \row + \li Input Iterator + \li + \li Not Supported + \row + \li Output Iterator + \li + \li Not Supported + \row + \li Forward Iterator + \li std::slist + \li Supported + \row + \li Bidirectional Iterator + \li QLinkedList, std::list + \li Supported + \row + \li Random Access Iterator + \li QList, QVector, 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(). + + 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. +*/ diff --git a/src/concurrent/doc/src/qtconcurrent-module.qdoc b/src/concurrent/doc/src/qtconcurrent-module.qdoc new file mode 100644 index 0000000000..aa3148b3f5 --- /dev/null +++ b/src/concurrent/doc/src/qtconcurrent-module.qdoc @@ -0,0 +1,39 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/legal +** +** 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 Digia. For licensing terms and +** conditions see http://qt.digia.com/licensing. For further information +** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \module QtConcurrent + \title Qt Concurrent C++ classes + \brief The Qt Concurrent module contains functionality to support concurrent execution of program code + + \ingroup modules + \ingroup technology-apis + + 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. +*/ + diff --git a/src/concurrent/doc/src/qtconcurrent.qdoc b/src/concurrent/doc/src/qtconcurrent.qdoc deleted file mode 100644 index efc43c90ce..0000000000 --- a/src/concurrent/doc/src/qtconcurrent.qdoc +++ /dev/null @@ -1,40 +0,0 @@ -/**************************************************************************** -** -** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies). -** Contact: http://www.qt-project.org/legal -** -** 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 Digia. For licensing terms and -** conditions see http://qt.digia.com/licensing. For further information -** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html. -** $QT_END_LICENSE$ -** -****************************************************************************/ - -/*! - \module QtConcurrent - \title QtConcurrent Module - \ingroup modules - - \keyword QtConcurrent - - \brief The QtConcurrent module contains functionality to support concurrent execution of program code - - The concurrent module extends the basic threading support found in \l{QtCore module}{Qt Core} and - simplifies the development of code that can be executed in parallel on all available CPU cores. -*/ - diff --git a/src/concurrent/qtconcurrentmap.cpp b/src/concurrent/qtconcurrentmap.cpp index f1e46177eb..81f860534d 100644 --- a/src/concurrent/qtconcurrentmap.cpp +++ b/src/concurrent/qtconcurrentmap.cpp @@ -41,7 +41,7 @@ /*! \namespace QtConcurrent - \inmodule QtCore + \inmodule QtConcurrent \since 4.4 \brief The QtConcurrent namespace provides high-level APIs that make it possible to write multi-threaded programs without using low-level @@ -50,7 +50,7 @@ See the \l {Concurrent Programming}{Qt Concurrent} chapter in the \l{threads.html}{threading} documentation. - \inheaderfile QtCore + \inheaderfile QtConcurrent \ingroup thread */ -- cgit v1.2.3