diff options
Diffstat (limited to 'doc/src/corelib')
| -rw-r--r-- | doc/src/corelib/containers.qdoc | 196 | ||||
| -rw-r--r-- | doc/src/corelib/json.qdoc | 12 | ||||
| -rw-r--r-- | doc/src/corelib/objectmodel/metaobjects.qdoc | 18 | ||||
| -rw-r--r-- | doc/src/corelib/objectmodel/object.qdoc | 26 | ||||
| -rw-r--r-- | doc/src/corelib/objectmodel/properties.qdoc | 22 | ||||
| -rw-r--r-- | doc/src/corelib/threads-basics.qdoc | 88 | ||||
| -rw-r--r-- | doc/src/corelib/threads.qdoc | 132 |
7 files changed, 247 insertions, 247 deletions
diff --git a/doc/src/corelib/containers.qdoc b/doc/src/corelib/containers.qdoc index e28c3bdbfe..b63cc9df28 100644 --- a/doc/src/corelib/containers.qdoc +++ b/doc/src/corelib/containers.qdoc @@ -104,10 +104,10 @@ efficient hash-lookup of objects in a limited cache storage. \table - \header \o Class \o Summary + \header \li Class \li Summary - \row \o \l{QList}<T> - \o This is by far the most commonly used container class. It + \row \li \l{QList}<T> + \li This is by far the most commonly used container class. It stores a list of values of a given type (T) that can be accessed by index. Internally, the QList is implemented using an array, ensuring that index-based access is very fast. @@ -119,8 +119,8 @@ possible in the executable. QStringList inherits from QList<QString>. - \row \o \l{QLinkedList}<T> - \o This is similar to QList, except that it uses + \row \li \l{QLinkedList}<T> + \li This is similar to QList, except that it uses iterators rather than integer indexes to access items. It also provides better performance than QList when inserting in the middle of a huge list, and it has nicer iterator semantics. @@ -128,48 +128,48 @@ long as the item exists, whereas iterators to a QList can become invalid after any insertion or removal.) - \row \o \l{QVector}<T> - \o This stores an array of values of a given type at adjacent + \row \li \l{QVector}<T> + \li This stores an array of values of a given type at adjacent positions in memory. Inserting at the front or in the middle of a vector can be quite slow, because it can lead to large numbers of items having to be moved by one position in memory. - \row \o \l{QStack}<T> - \o This is a convenience subclass of QVector that provides + \row \li \l{QStack}<T> + \li This is a convenience subclass of QVector that provides "last in, first out" (LIFO) semantics. It adds the following functions to those already present in QVector: \l{QStack::push()}{push()}, \l{QStack::pop()}{pop()}, and \l{QStack::top()}{top()}. - \row \o \l{QQueue}<T> - \o This is a convenience subclass of QList that provides + \row \li \l{QQueue}<T> + \li This is a convenience subclass of QList that provides "first in, first out" (FIFO) semantics. It adds the following functions to those already present in QList: \l{QQueue::enqueue()}{enqueue()}, \l{QQueue::dequeue()}{dequeue()}, and \l{QQueue::head()}{head()}. - \row \o \l{QSet}<T> - \o This provides a single-valued mathematical set with fast + \row \li \l{QSet}<T> + \li This provides a single-valued mathematical set with fast lookups. - \row \o \l{QMap}<Key, T> - \o This provides a dictionary (associative array) that maps keys + \row \li \l{QMap}<Key, T> + \li This provides a dictionary (associative array) that maps keys of type Key to values of type T. Normally each key is associated with a single value. QMap stores its data in Key order; if order doesn't matter QHash is a faster alternative. - \row \o \l{QMultiMap}<Key, T> - \o This is a convenience subclass of QMap that provides a nice + \row \li \l{QMultiMap}<Key, T> + \li This is a convenience subclass of QMap that provides a nice interface for multi-valued maps, i.e. maps where one key can be associated with multiple values. - \row \o \l{QHash}<Key, T> - \o This has almost the same API as QMap, but provides + \row \li \l{QHash}<Key, T> + \li This has almost the same API as QMap, but provides significantly faster lookups. QHash stores its data in an arbitrary order. - \row \o \l{QMultiHash}<Key, T> - \o This is a convenience subclass of QHash that + \row \li \l{QMultiHash}<Key, T> + \li This is a convenience subclass of QHash that provides a nice interface for multi-valued hashes. \endtable @@ -271,20 +271,20 @@ read-write access. \table - \header \o Containers \o Read-only iterator - \o Read-write iterator - \row \o QList<T>, QQueue<T> \o QListIterator<T> - \o QMutableListIterator<T> - \row \o QLinkedList<T> \o QLinkedListIterator<T> - \o QMutableLinkedListIterator<T> - \row \o QVector<T>, QStack<T> \o QVectorIterator<T> - \o QMutableVectorIterator<T> - \row \o QSet<T> \o QSetIterator<T> - \o QMutableSetIterator<T> - \row \o QMap<Key, T>, QMultiMap<Key, T> \o QMapIterator<Key, T> - \o QMutableMapIterator<Key, T> - \row \o QHash<Key, T>, QMultiHash<Key, T> \o QHashIterator<Key, T> - \o QMutableHashIterator<Key, T> + \header \li Containers \li Read-only iterator + \li Read-write iterator + \row \li QList<T>, QQueue<T> \li QListIterator<T> + \li QMutableListIterator<T> + \row \li QLinkedList<T> \li QLinkedListIterator<T> + \li QMutableLinkedListIterator<T> + \row \li QVector<T>, QStack<T> \li QVectorIterator<T> + \li QMutableVectorIterator<T> + \row \li QSet<T> \li QSetIterator<T> + \li QMutableSetIterator<T> + \row \li QMap<Key, T>, QMultiMap<Key, T> \li QMapIterator<Key, T> + \li QMutableMapIterator<Key, T> + \row \li QHash<Key, T>, QMultiHash<Key, T> \li QHashIterator<Key, T> + \li QMutableHashIterator<Key, T> \endtable In this discussion, we will concentrate on QList and QMap. The @@ -334,23 +334,23 @@ The following table summarizes the QListIterator API: \table - \header \o Function \o Behavior - \row \o \l{QListIterator::toFront()}{toFront()} - \o Moves the iterator to the front of the list (before the first item) - \row \o \l{QListIterator::toBack()}{toBack()} - \o Moves the iterator to the back of the list (after the last item) - \row \o \l{QListIterator::hasNext()}{hasNext()} - \o Returns true if the iterator isn't at the back of the list - \row \o \l{QListIterator::next()}{next()} - \o Returns the next item and advances the iterator by one position - \row \o \l{QListIterator::peekNext()}{peekNext()} - \o Returns the next item without moving the iterator - \row \o \l{QListIterator::hasPrevious()}{hasPrevious()} - \o Returns true if the iterator isn't at the front of the list - \row \o \l{QListIterator::previous()}{previous()} - \o Returns the previous item and moves the iterator back by one position - \row \o \l{QListIterator::peekPrevious()}{peekPrevious()} - \o Returns the previous item without moving the iterator + \header \li Function \li Behavior + \row \li \l{QListIterator::toFront()}{toFront()} + \li Moves the iterator to the front of the list (before the first item) + \row \li \l{QListIterator::toBack()}{toBack()} + \li Moves the iterator to the back of the list (after the last item) + \row \li \l{QListIterator::hasNext()}{hasNext()} + \li Returns true if the iterator isn't at the back of the list + \row \li \l{QListIterator::next()}{next()} + \li Returns the next item and advances the iterator by one position + \row \li \l{QListIterator::peekNext()}{peekNext()} + \li Returns the next item without moving the iterator + \row \li \l{QListIterator::hasPrevious()}{hasPrevious()} + \li Returns true if the iterator isn't at the front of the list + \row \li \l{QListIterator::previous()}{previous()} + \li Returns the previous item and moves the iterator back by one position + \row \li \l{QListIterator::peekPrevious()}{peekPrevious()} + \li Returns the previous item without moving the iterator \endtable QListIterator provides no functions to insert or remove items @@ -440,20 +440,20 @@ possible because they are faster than read-write iterators. \table - \header \o Containers \o Read-only iterator - \o Read-write iterator - \row \o QList<T>, QQueue<T> \o QList<T>::const_iterator - \o QList<T>::iterator - \row \o QLinkedList<T> \o QLinkedList<T>::const_iterator - \o QLinkedList<T>::iterator - \row \o QVector<T>, QStack<T> \o QVector<T>::const_iterator - \o QVector<T>::iterator - \row \o QSet<T> \o QSet<T>::const_iterator - \o QSet<T>::iterator - \row \o QMap<Key, T>, QMultiMap<Key, T> \o QMap<Key, T>::const_iterator - \o QMap<Key, T>::iterator - \row \o QHash<Key, T>, QMultiHash<Key, T> \o QHash<Key, T>::const_iterator - \o QHash<Key, T>::iterator + \header \li Containers \li Read-only iterator + \li Read-write iterator + \row \li QList<T>, QQueue<T> \li QList<T>::const_iterator + \li QList<T>::iterator + \row \li QLinkedList<T> \li QLinkedList<T>::const_iterator + \li QLinkedList<T>::iterator + \row \li QVector<T>, QStack<T> \li QVector<T>::const_iterator + \li QVector<T>::iterator + \row \li QSet<T> \li QSet<T>::const_iterator + \li QSet<T>::iterator + \row \li QMap<Key, T>, QMultiMap<Key, T> \li QMap<Key, T>::const_iterator + \li QMap<Key, T>::iterator + \row \li QHash<Key, T>, QMultiHash<Key, T> \li QHash<Key, T>::const_iterator + \li QHash<Key, T>::iterator \endtable The API of the STL iterators is modelled on pointers in an array. @@ -509,13 +509,13 @@ The following table summarizes the STL-style iterators' API: \table - \header \o Expression \o Behavior - \row \o \c{*i} \o Returns the current item - \row \o \c{++i} \o Advances the iterator to the next item - \row \o \c{i += n} \o Advances the iterator by \c n items - \row \o \c{--i} \o Moves the iterator back by one item - \row \o \c{i -= n} \o Moves the iterator back by \c n items - \row \o \c{i - j} \o Returns the number of items between iterators \c i and \c j + \header \li Expression \li Behavior + \row \li \c{*i} \li Returns the current item + \row \li \c{++i} \li Advances the iterator to the next item + \row \li \c{i += n} \li Advances the iterator by \c n items + \row \li \c{--i} \li Moves the iterator back by one item + \row \li \c{i -= n} \li Moves the iterator back by \c n items + \row \li \c{i - j} \li Returns the number of items between iterators \c i and \c j \endtable The \c{++} and \c{--} operators are available both as prefix @@ -625,17 +625,17 @@ be used with the \c foreach keyword. \list - \o QVarLengthArray<T, Prealloc> provides a low-level + \li QVarLengthArray<T, Prealloc> provides a low-level variable-length array. It can be used instead of QVector in places where speed is particularly important. - \o QCache<Key, T> provides a cache to store objects of a certain + \li QCache<Key, T> provides a cache to store objects of a certain type T associated with keys of type Key. - \o QContiguousCache<T> provides an efficient way of caching data + \li QContiguousCache<T> provides an efficient way of caching data that is typically accessed in a contiguous way. - \o QPair<T1, T2> stores a pair of elements. + \li QPair<T1, T2> stores a pair of elements. \endlist Additional non-template types that compete with Qt's template @@ -662,27 +662,27 @@ \keyword quadratic time \list - \o \bold{Constant time:} O(1). A function is said to run in constant + \li \b{Constant time:} O(1). A function is said to run in constant time if it requires the same amount of time no matter how many items are present in the container. One example is QLinkedList::insert(). - \o \bold{Logarithmic time:} O(log \e n). A function that runs in + \li \b{Logarithmic time:} O(log \e n). A function that runs in logarithmic time is a function whose running time is proportional to the logarithm of the number of items in the container. One example is qBinaryFind(). - \o \bold{Linear time:} O(\e n). A function that runs in linear time + \li \b{Linear time:} O(\e n). A function that runs in linear time will execute in a time directly proportional to the number of items stored in the container. One example is QVector::insert(). - \o \bold{Linear-logarithmic time:} O(\e{n} log \e n). A function + \li \b{Linear-logarithmic time:} O(\e{n} log \e n). A function that runs in linear-logarithmic time is asymptotically slower than a linear-time function, but faster than a quadratic-time function. - \o \bold{Quadratic time:} O(\e{n}\unicode{178}). A quadratic-time function + \li \b{Quadratic time:} O(\e{n}\unicode{178}). A quadratic-time function executes in a time that is proportional to the square of the number of items stored in the container. \endlist @@ -691,10 +691,10 @@ sequential container classes: \table - \header \o \o Index lookup \o Insertion \o Prepending \o Appending - \row \o QLinkedList<T> \o O(\e n) \o O(1) \o O(1) \o O(1) - \row \o QList<T> \o O(1) \o O(n) \o Amort. O(1) \o Amort. O(1) - \row \o QVector<T> \o O(1) \o O(n) \o O(n) \o Amort. O(1) + \header \li \li Index lookup \li Insertion \li Prepending \li Appending + \row \li QLinkedList<T> \li O(\e n) \li O(1) \li O(1) \li O(1) + \row \li QList<T> \li O(1) \li O(n) \li Amort. O(1) \li Amort. O(1) + \row \li QVector<T> \li O(1) \li O(n) \li O(n) \li Amort. O(1) \endtable In the table, "Amort." stands for "amortized behavior". For @@ -707,12 +707,12 @@ associative containers and sets: \table - \header \o{1,2} \o{2,1} Key lookup \o{2,1} Insertion - \header \o Average \o Worst case \o Average \o Worst case - \row \o QMap<Key, T> \o O(log \e n) \o O(log \e n) \o O(log \e n) \o O(log \e n) - \row \o QMultiMap<Key, T> \o O(log \e n) \o O(log \e n) \o O(log \e n) \o O(log \e n) - \row \o QHash<Key, T> \o Amort. O(1) \o O(\e n) \o Amort. O(1) \o O(\e n) - \row \o QSet<Key> \o Amort. O(1) \o O(\e n) \o Amort. O(1) \o O(\e n) + \header \li{1,2} \li{2,1} Key lookup \li{2,1} Insertion + \header \li Average \li Worst case \li Average \li Worst case + \row \li QMap<Key, T> \li O(log \e n) \li O(log \e n) \li O(log \e n) \li O(log \e n) + \row \li QMultiMap<Key, T> \li O(log \e n) \li O(log \e n) \li O(log \e n) \li O(log \e n) + \row \li QHash<Key, T> \li Amort. O(1) \li O(\e n) \li Amort. O(1) \li O(\e n) + \row \li QSet<Key> \li Amort. O(1) \li O(\e n) \li Amort. O(1) \li O(\e n) \endtable With QVector, QHash, and QSet, the performance of appending items @@ -749,13 +749,13 @@ The values above may seem a bit strange, but here are the guiding principles: \list - \o QString allocates 4 characters at a time until it reaches size 20. - \o From 20 to 4084, it advances by doubling the size each time. + \li QString allocates 4 characters at a time until it reaches size 20. + \li From 20 to 4084, it advances by doubling the size each time. More precisely, it advances to the next power of two, minus 12. (Some memory allocators perform worst when requested exact powers of two, because they use a few bytes per block for book-keeping.) - \o From 4084 on, it advances by blocks of 2048 characters (4096 + \li From 4084 on, it advances by blocks of 2048 characters (4096 bytes). This makes sense because modern operating systems don't copy the entire data when reallocating a buffer; the physical memory pages are simply reordered, and only the data @@ -787,12 +787,12 @@ use to store the items: \list - \o \l{QString::capacity()}{capacity()} returns the + \li \l{QString::capacity()}{capacity()} returns the number of items for which memory is allocated (for QHash and QSet, the number of buckets in the hash table). - \o \l{QString::reserve()}{reserve}(\e size) explicitly + \li \l{QString::reserve()}{reserve}(\e size) explicitly preallocates memory for \e size items. - \o \l{QString::squeeze()}{squeeze()} frees any memory + \li \l{QString::squeeze()}{squeeze()} frees any memory not required to store the items. \endlist diff --git a/doc/src/corelib/json.qdoc b/doc/src/corelib/json.qdoc index 91a89761e3..88b5377074 100644 --- a/doc/src/corelib/json.qdoc +++ b/doc/src/corelib/json.qdoc @@ -59,12 +59,12 @@ JSON is a format to store structured data. It has 6 basic data types: \list - \o bool - \o double - \o string - \o array - \o object - \o null + \li bool + \li double + \li string + \li array + \li object + \li null \endlist Any value can be any of the above type. A boolean value is represented by the diff --git a/doc/src/corelib/objectmodel/metaobjects.qdoc b/doc/src/corelib/objectmodel/metaobjects.qdoc index 7edb376e25..c92f6f2f09 100644 --- a/doc/src/corelib/objectmodel/metaobjects.qdoc +++ b/doc/src/corelib/objectmodel/metaobjects.qdoc @@ -41,12 +41,12 @@ The meta-object system is based on three things: \list 1 - \o The \l QObject class provides a base class for objects that can + \li The \l QObject class provides a base class for objects that can take advantage of the meta-object system. - \o The Q_OBJECT macro inside the private section of the class + \li The Q_OBJECT macro inside the private section of the class declaration is used to enable meta-object features, such as dynamic properties, signals, and slots. - \o The \l{moc}{Meta-Object Compiler} (\c moc) supplies each + \li The \l{moc}{Meta-Object Compiler} (\c moc) supplies each QObject subclass with the necessary code to implement meta-object features. \endlist @@ -64,19 +64,19 @@ additional features: \list - \o QObject::metaObject() returns the associated + \li QObject::metaObject() returns the associated \l{QMetaObject}{meta-object} for the class. - \o QMetaObject::className() returns the class name as a + \li QMetaObject::className() returns the class name as a string at run-time, without requiring native run-time type information (RTTI) support through the C++ compiler. - \o QObject::inherits() function returns whether an object is an + \li QObject::inherits() function returns whether an object is an instance of a class that inherits a specified class within the QObject inheritance tree. - \o QObject::tr() and QObject::trUtf8() translate strings for + \li QObject::tr() and QObject::trUtf8() translate strings for \l{Internationalization with Qt}{internationalization}. - \o QObject::setProperty() and QObject::property() + \li QObject::setProperty() and QObject::property() dynamically set and get properties by name. - \o QMetaObject::newInstance() constructs a new instance of the class. + \li QMetaObject::newInstance() constructs a new instance of the class. \endlist \target qobjectcast diff --git a/doc/src/corelib/objectmodel/object.qdoc b/doc/src/corelib/objectmodel/object.qdoc index cf3ce4ef31..4e212b37dd 100644 --- a/doc/src/corelib/objectmodel/object.qdoc +++ b/doc/src/corelib/objectmodel/object.qdoc @@ -41,20 +41,20 @@ Qt adds these features to C++: \list - \o a very powerful mechanism for seamless object + \li a very powerful mechanism for seamless object communication called \l{signals and slots} - \o queryable and designable \l{Qt's Property System}{object + \li queryable and designable \l{Qt's Property System}{object properties} - \o powerful \l{The Event System}{events and event filters} - \o contextual \l{i18n}{string translation for internationalization} - \o sophisticated interval driven \l timers that make it possible + \li powerful \l{The Event System}{events and event filters} + \li contextual \l{i18n}{string translation for internationalization} + \li sophisticated interval driven \l timers that make it possible to elegantly integrate many tasks in an event-driven GUI - \o hierarchical and queryable \l{Object Trees & Ownership}{object + \li hierarchical and queryable \l{Object Trees & Ownership}{object trees} that organize object ownership in a natural way - \o guarded pointers (QPointer) that are automatically + \li guarded pointers (QPointer) that are automatically set to 0 when the referenced object is destroyed, unlike normal C++ pointers which become dangling pointers when their objects are destroyed - \o a \l{metaobjects.html#qobjectcast}{dynamic cast} that works across + \li a \l{metaobjects.html#qobjectcast}{dynamic cast} that works across library boundaries. \endlist @@ -92,22 +92,22 @@ or assigning a value. We can see what this means in the Qt Object Model. - \bold{A Qt Object...} + \b{A Qt Object...} \list - \o might have a unique \l{QObject::objectName()}. If we copy a Qt + \li might have a unique \l{QObject::objectName()}. If we copy a Qt Object, what name should we give the copy? - \o has a location in an \l{Object Trees & Ownership} + \li has a location in an \l{Object Trees & Ownership} {object hierarchy}. If we copy a Qt Object, where should the copy be located? - \o can be connected to other Qt Objects to emit signals to them or + \li can be connected to other Qt Objects to emit signals to them or to receive signals emitted by them. If we copy a Qt Object, how should we transfer these connections to the copy? - \o can have \l{Qt's Property System} {new properties} added to it + \li can have \l{Qt's Property System} {new properties} added to it at runtime that are not declared in the C++ class. If we copy a Qt Object, should the copy include the properties that were added to the original? diff --git a/doc/src/corelib/objectmodel/properties.qdoc b/doc/src/corelib/objectmodel/properties.qdoc index 894efd017d..4d090af8fc 100644 --- a/doc/src/corelib/objectmodel/properties.qdoc +++ b/doc/src/corelib/objectmodel/properties.qdoc @@ -58,20 +58,20 @@ \list - \o A \c READ accessor function is required. It is for reading the + \li A \c READ accessor function is required. It is for reading the property value. Ideally, a const function is used for this purpose, and it must return either the property's type or a pointer or reference to that type. e.g., QWidget::focus is a read-only property with \c READ function, QWidget::hasFocus(). - \o A \c WRITE accessor function is optional. It is for setting the + \li A \c WRITE accessor function is optional. It is for setting the property value. It must return void and must take exactly one argument, either of the property's type or a pointer or reference to that type. e.g., QWidget::enabled has the \c WRITE function QWidget::setEnabled(). Read-only properties do not need \c WRITE functions. e.g., QWidget::focus has no \c WRITE function. - \o A \c RESET function is optional. It is for setting the property + \li A \c RESET function is optional. It is for setting the property back to its context specific default value. e.g., QWidget::cursor has the typical \c READ and \c WRITE functions, QWidget::cursor() and QWidget::setCursor(), and it also has a \c RESET function, @@ -79,26 +79,26 @@ mean \e {reset to the context specific cursor}. The \c RESET function must return void and take no parameters. - \o A \c NOTIFY signal is optional. If defined, it should specify one + \li A \c NOTIFY signal is optional. If defined, it should specify one existing signal in that class that is emitted whenever the value of the property changes. - \o A \c REVISION number is optional. If included, it defines the + \li A \c REVISION number is optional. If included, it defines the the property and its notifier signal to be used in a particular revision of the API that is exposed to QML. - \o The \c DESIGNABLE attribute indicates whether the property + \li The \c DESIGNABLE attribute indicates whether the property should be visible in the property editor of GUI design tool (e.g., \l {Qt Designer}). Most properties are \c DESIGNABLE (default true). Instead of true or false, you can specify a boolean member function. - \o The \c SCRIPTABLE attribute indicates whether this property + \li The \c SCRIPTABLE attribute indicates whether this property should be accessible by a scripting engine (default true). Instead of true or false, you can specify a boolean member function. - \o The \c STORED attribute indicates whether the property should + \li The \c STORED attribute indicates whether the property should be thought of as existing on its own or as depending on other values. It also indicates whether the property value must be saved when storing the object's state. Most properties are \c STORED @@ -106,20 +106,20 @@ false, because its value is just taken from the width component of property QWidget::minimumSize(), which is a QSize. - \o The \c USER attribute indicates whether the property is + \li The \c USER attribute indicates whether the property is designated as the user-facing or user-editable property for the class. Normally, there is only one \c USER property per class (default false). e.g., QAbstractButton::checked is the user editable property for (checkable) buttons. Note that QItemDelegate gets and sets a widget's \c USER property. - \o The presence of the \c CONSTANT attibute indicates that the property + \li The presence of the \c CONSTANT attibute indicates that the property value is constant. For a given object instance, the READ method of a constant property must return the same value every time it is called. This constant value may be different for different instances of the object. A constant property cannot have a WRITE method or a NOTIFY signal. - \o The presence of the \c FINAL attribute indicates that the property + \li The presence of the \c FINAL attribute indicates that the property will not be overridden by a derived class. This can be used for performance optimizations in some cases, but is not enforced by moc. Care must be taken never to override a \c FINAL property. diff --git a/doc/src/corelib/threads-basics.qdoc b/doc/src/corelib/threads-basics.qdoc index 44a3961177..e54f8a7ccb 100644 --- a/doc/src/corelib/threads-basics.qdoc +++ b/doc/src/corelib/threads-basics.qdoc @@ -123,8 +123,8 @@ There are basically two use cases for threads: \list - \o Make processing faster by making use of multicore processors. - \o Keep the GUI thread or other time critical threads responsive by + \li Make processing faster by making use of multicore processors. + \li Keep the GUI thread or other time critical threads responsive by offloading long lasting processing or blocking calls to other threads. \endlist @@ -138,23 +138,23 @@ \table \header - \o Alternative - \o Comment + \li Alternative + \li Comment \row - \o QEventLoop::processEvents() - \o Calling QEventLoop::processEvents() repeatedly during a + \li QEventLoop::processEvents() + \li Calling QEventLoop::processEvents() repeatedly during a time-consuming calculation prevents GUI blocking. However, this solution doesn't scale well because the call to processEvents() may occur too often, or not often enough, depending on hardware. \row - \o QTimer - \o Background processing can sometimes be done conveniently using a + \li QTimer + \li Background processing can sometimes be done conveniently using a timer to schedule execution of a slot at some point in the future. A timer with an interval of 0 will time out as soon as there are no more events to process. \row - \o QSocketNotifier QNetworkAccessManager QIODevice::readyRead() - \o This is an alternative to having one or multiple threads, each with + \li QSocketNotifier QNetworkAccessManager QIODevice::readyRead() + \li This is an alternative to having one or multiple threads, each with a blocking read on a slow network connection. As long as the calculation in response to a chunk of network data can be executed quickly, this reactive design is better than synchronous waiting in @@ -183,55 +183,55 @@ \table \header - \o Lifetime of thread - \o Development task - \o Solution + \li Lifetime of thread + \li Development task + \li Solution \row - \o One call - \o Run one method within another thread and quit the thread when the + \li One call + \li Run one method within another thread and quit the thread when the method is finished. - \o Qt provides different solutions: + \li Qt provides different solutions: \list - \o Write a function and run it with QtConcurrent::run() - \o Derive a class from QRunnable and run it in the global thread + \li Write a function and run it with QtConcurrent::run() + \li Derive a class from QRunnable and run it in the global thread pool with QThreadPool::globalInstance()->start() - \o Derive a class from QThread, reimplement the QThread::run() + \li Derive a class from QThread, reimplement the QThread::run() method and use QThread::start() to run it. \endlist \row - \o One call - \o Operations are to be performed on all items of a container. + \li One call + \li Operations are to be performed on all items of a container. Processing should be performed using all available cores. A common example is to produce thumbnails from a list of images. - \o QtConcurrent provides the \l{QtConcurrent::}{map()} function for + \li QtConcurrent provides the \l{QtConcurrent::}{map()} function for applying operations on every container element, \l{QtConcurrent::}{filter()} for selecting container elements, and the option of specifying a reduce function for combining the remaining elements. \row - \o One call - \o A long running operation has to be put in another thread. During the + \li One call + \li A long running operation has to be put in another thread. During the course of processing, status information should be sent to the GUI thread. - \o Use QThread, reimplement run and emit signals as needed. Connect the + \li Use QThread, reimplement run and emit signals as needed. Connect the signals to the GUI thread's slots using queued signal/slot connections. \row - \o Permanent - \o Have an object living in another thread and let it perform different + \li Permanent + \li Have an object living in another thread and let it perform different tasks upon request. This means communication to and from the worker thread is required. - \o Derive a class from QObject and implement the necessary slots and + \li Derive a class from QObject and implement the necessary slots and signals, move the object to a thread with a running event loop and communicate with the object over queued signal/slot connections. \row - \o Permanent - \o Have an object living in another thread, let the object perform + \li Permanent + \li Have an object living in another thread, let the object perform repeated tasks such as polling a port and enable communication with the GUI thread. - \o Same as above but also use a timer in the worker thread to implement + \li Same as above but also use a timer in the worker thread to implement polling. However, the best solution for polling is to avoid it completely. Sometimes using QSocketNotifier is an alternative. \endtable @@ -304,18 +304,18 @@ The anatomy of QThread is quite interesting: \list - \o QThread does not live in the new thread where \l{QThread::}{run()} is + \li QThread does not live in the new thread where \l{QThread::}{run()} is executed. It lives in the old thread. - \o Most QThread methods are the thread's control interface and are meant to + \li Most QThread methods are the thread's control interface and are meant to be called from the old thread. Do not move this interface to the newly created thread using \l{QObject::}{moveToThread()}; i.e., calling \l{QObject::moveToThread()}{moveToThread(this)} is regarded as bad practice. - \o \l{QThread::}{exec()} and the static methods + \li \l{QThread::}{exec()} and the static methods \l{QThread::}{usleep()}, \l{QThread::}{msleep()}, \l{QThread::}{sleep()} are meant to be called from the newly created thread. - \o Additional members defined in the QThread subclass are + \li Additional members defined in the QThread subclass are accessible by both threads. The developer is responsible for coordinating access. A typical strategy is to set the members before \l{QThread::}{start()} is called. Once the worker thread is running, @@ -432,11 +432,11 @@ main thread. \list - \o Using QThread as shown \l{Qt thread basics}{above} - \o \l{Example 1: Using the Thread Pool}{Using the global QThreadPool} - \o \l{Example 2: Using QtConcurrent}{Using QtConcurrent} - \o \l{Example 3: Clock}{Communication with the GUI thread} - \o \l{Example 4: A Permanent Thread}{A permanent QObject in another thread + \li Using QThread as shown \l{Qt thread basics}{above} + \li \l{Example 1: Using the Thread Pool}{Using the global QThreadPool} + \li \l{Example 2: Using QtConcurrent}{Using QtConcurrent} + \li \l{Example 3: Clock}{Communication with the GUI thread} + \li \l{Example 4: A Permanent Thread}{A permanent QObject in another thread provides service to the main thread} \endlist @@ -558,13 +558,13 @@ can help you go into the subject in more depth: \list - \o Good video tutorials about threads with Qt can be found in the material + \li Good video tutorials about threads with Qt can be found in the material from the \l{Training Day at Qt Developer Days 2009}. - \o The \l{Thread Support in Qt} document is a good starting point into + \li The \l{Thread Support in Qt} document is a good starting point into the reference documentation. - \o Qt comes with several additional examples for + \li Qt comes with several additional examples for \l{Threading and Concurrent Programming Examples}{QThread and QtConcurrent}. - \o Several good books describe how to work with Qt threads. The most + \li Several good books describe how to work with Qt threads. The most extensive coverage can be found in \e{Advanced Qt Programming} by Mark Summerfield, Prentice Hall - roughly 70 of 500 pages cover QThread and QtConcurrent. diff --git a/doc/src/corelib/threads.qdoc b/doc/src/corelib/threads.qdoc index 3b4def4174..04a5379b2d 100644 --- a/doc/src/corelib/threads.qdoc +++ b/doc/src/corelib/threads.qdoc @@ -54,14 +54,14 @@ \section1 Topics: \list - \o \l{Recommended Reading} - \o \l{The Threading Classes} - \o \l{Starting Threads with QThread} - \o \l{Synchronizing Threads} - \o \l{Reentrancy and Thread-Safety} - \o \l{Threads and QObjects} - \o \l{Concurrent Programming} - \o \l{Thread-Support in Qt Modules} + \li \l{Recommended Reading} + \li \l{The Threading Classes} + \li \l{Starting Threads with QThread} + \li \l{Synchronizing Threads} + \li \l{Reentrancy and Thread-Safety} + \li \l{Threads and QObjects} + \li \l{Concurrent Programming} + \li \l{Thread-Support in Qt Modules} \endlist \section1 Recommended Reading @@ -71,10 +71,10 @@ to threading see our Recommended Reading list: \list - \o \l{Threads Primer: A Guide to Multithreaded Programming} - \o \l{Thread Time: The Multithreaded Programming Guide} - \o \l{Pthreads Programming: A POSIX Standard for Better Multiprocessing} - \o \l{Win32 Multithreaded Programming} + \li \l{Threads Primer: A Guide to Multithreaded Programming} + \li \l{Thread Time: The Multithreaded Programming Guide} + \li \l{Pthreads Programming: A POSIX Standard for Better Multiprocessing} + \li \l{Win32 Multithreaded Programming} \endlist \section1 The Threading Classes @@ -85,21 +85,21 @@ \omit \list - \o QThread provides the means to start a new thread. - \o QThreadStorage provides per-thread data storage. - \o QThreadPool manages a pool of threads that run QRunnable objects. - \o QRunnable is an abstract class representing a runnable object. - \o QMutex provides a mutual exclusion lock, or mutex. - \o QMutexLocker is a convenience class that automatically locks + \li QThread provides the means to start a new thread. + \li QThreadStorage provides per-thread data storage. + \li QThreadPool manages a pool of threads that run QRunnable objects. + \li QRunnable is an abstract class representing a runnable object. + \li QMutex provides a mutual exclusion lock, or mutex. + \li QMutexLocker is a convenience class that automatically locks and unlocks a QMutex. - \o QReadWriteLock provides a lock that allows simultaneous read access. - \o QReadLocker and QWriteLocker are convenience classes that automatically + \li QReadWriteLock provides a lock that allows simultaneous read access. + \li QReadLocker and QWriteLocker are convenience classes that automatically lock and unlock a QReadWriteLock. - \o QSemaphore provides an integer semaphore (a generalization of a mutex). - \o QWaitCondition provides a way for threads to go to sleep until + \li QSemaphore provides an integer semaphore (a generalization of a mutex). + \li QWaitCondition provides a way for threads to go to sleep until woken up by another thread. - \o QAtomicInt provides atomic operations on integers. - \o QAtomicPointer provides atomic operations on pointers. + \li QAtomicInt provides atomic operations on integers. + \li QAtomicPointer provides atomic operations on pointers. \endlist \endomit @@ -226,10 +226,10 @@ how they can be used in multithread applications: \list - \o A \e thread-safe function can be called simultaneously from + \li A \e thread-safe function can be called simultaneously from multiple threads, even when the invocations use shared data, because all references to the shared data are serialized. - \o A \e reentrant function can also be called simultaneously from + \li A \e reentrant function can also be called simultaneously from multiple threads, but only if each invocation uses its own data. \endlist @@ -267,9 +267,9 @@ Indeed, they usually expand to three machine instructions: \list 1 - \o Load the variable's value in a register. - \o Increment or decrement the register's value. - \o Store the register's value back into main memory. + \li Load the variable's value in a register. + \li Increment or decrement the register's value. + \li Store the register's value back into main memory. \endlist If thread A and thread B load the variable's old value @@ -346,19 +346,19 @@ guaranteed to work. There are three constraints to be aware of: \list - \o \e{The child of a QObject must always be created in the thread + \li \e{The child of a QObject must always be created in the thread where the parent was created.} This implies, among other things, that you should never pass the QThread object (\c this) as the parent of an object created in the thread (since the QThread object itself was created in another thread). - \o \e{Event driven objects may only be used in a single thread.} + \li \e{Event driven objects may only be used in a single thread.} Specifically, this applies to the \l{timers.html}{timer mechanism} and the \l{QtNetwork}{network module}. For example, you cannot start a timer or connect a socket in a thread that is not the \l{QObject::thread()}{object's thread}. - \o \e{You must ensure that all objects created in a thread are + \li \e{You must ensure that all objects created in a thread are deleted before you delete the QThread.} This can be done easily by creating the objects on the stack in your \l{QThread::run()}{run()} implementation. @@ -469,26 +469,26 @@ \list - \o \l{Qt::AutoConnection}{Auto Connection} (default) If the signal is + \li \l{Qt::AutoConnection}{Auto Connection} (default) If the signal is emitted in the thread which the receiving object has affinity then the behavior is the same as the Direct Connection. Otherwise, the behavior is the same as the Queued Connection." - \o \l{Qt::DirectConnection}{Direct Connection} The slot is invoked + \li \l{Qt::DirectConnection}{Direct Connection} The slot is invoked immediately, when the signal is emitted. The slot is executed in the emitter's thread, which is not necessarily the receiver's thread. - \o \l{Qt::QueuedConnection}{Queued Connection} The slot is invoked + \li \l{Qt::QueuedConnection}{Queued Connection} The slot is invoked when control returns to the event loop of the receiver's thread. The slot is executed in the receiver's thread. - \o \l{Qt::BlockingQueuedConnection}{Blocking Queued Connection} + \li \l{Qt::BlockingQueuedConnection}{Blocking Queued Connection} The slot is invoked as for the Queued Connection, except the current thread blocks until the slot returns. \note Using this type to connect objects in the same thread will cause deadlock. - \o \l{Qt::UniqueConnection}{Unique Connection} The behavior is the + \li \l{Qt::UniqueConnection}{Unique Connection} The behavior is the same as the Auto Connection, but the connection is made only if it does not duplicate an existing connection. i.e., if the same signal is already connected to the same slot for the same pair @@ -546,33 +546,33 @@ \list - \o QtConcurrent::map() applies a function to every item in a container, + \li QtConcurrent::map() applies a function to every item in a container, modifying the items in-place. - \o QtConcurrent::mapped() is like map(), except that it returns a new + \li QtConcurrent::mapped() is like map(), except that it returns a new container with the modifications. - \o QtConcurrent::mappedReduced() is like mapped(), except that the + \li QtConcurrent::mappedReduced() is like mapped(), except that the modified results are reduced or folded into a single result. - \o QtConcurrent::filter() removes all items from a container based on the + \li QtConcurrent::filter() removes all items from a container based on the result of a filter function. - \o QtConcurrent::filtered() is like filter(), except that it returns a new + \li QtConcurrent::filtered() is like filter(), except that it returns a new container with the filtered results. - \o QtConcurrent::filteredReduced() is like filtered(), except that the + \li QtConcurrent::filteredReduced() is like filtered(), except that the filtered results are reduced or folded into a single result. - \o QtConcurrent::run() runs a function in another thread. + \li QtConcurrent::run() runs a function in another thread. - \o QFuture represents the result of an asynchronous computation. + \li QFuture represents the result of an asynchronous computation. - \o QFutureIterator allows iterating through results available via QFuture. + \li QFutureIterator allows iterating through results available via QFuture. - \o QFutureWatcher allows monitoring a QFuture using signals-and-slots. + \li QFutureWatcher allows monitoring a QFuture using signals-and-slots. - \o QFutureSynchronizer is a convenience class that automatically + \li QFutureSynchronizer is a convenience class that automatically synchronizes several QFutures. \endlist @@ -585,29 +585,29 @@ \table \header - \o Iterator Type - \o Example classes - \o Support status + \li Iterator Type + \li Example classes + \li Support status \row - \o Input Iterator - \o - \o Not Supported + \li Input Iterator + \li + \li Not Supported \row - \o Output Iterator - \o - \o Not Supported + \li Output Iterator + \li + \li Not Supported \row - \o Forward Iterator - \o std::slist - \o Supported + \li Forward Iterator + \li std::slist + \li Supported \row - \o Bidirectional Iterator - \o QLinkedList, std::list - \o Supported + \li Bidirectional Iterator + \li QLinkedList, std::list + \li Supported \row - \o Random Access Iterator - \o QList, QVector, std::vector - \o Supported and Recommended + \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 |