diff options
author | Casper van Donderen <casper.vandonderen@nokia.com> | 2011-09-16 14:14:43 +0200 |
---|---|---|
committer | Qt by Nokia <qt-info@nokia.com> | 2011-09-19 10:24:25 +0200 |
commit | cd621c201ca637385c6e3409d5c84ecec5fb5418 (patch) | |
tree | 981b062e3bbc5c513498b18c10ad55f8252e8486 /doc/src/core | |
parent | 20009ed797fb30952a889df5716aa2399102be58 (diff) | |
download | qtbase-cd621c201ca637385c6e3409d5c84ecec5fb5418.tar.gz |
Move the module qdoc files from qtdoc and split up doc/src.
Change-Id: I7d992889379d78e07a0b7023facebd7421cf6d22
Reviewed-on: http://codereview.qt-project.org/5092
Reviewed-by: Qt Sanity Bot <qt_sanity_bot@ovi.com>
Reviewed-by: Jerome Pasion <jerome.pasion@nokia.com>
Diffstat (limited to 'doc/src/core')
-rw-r--r-- | doc/src/core/objectmodel/metaobjects.qdoc | 137 | ||||
-rw-r--r-- | doc/src/core/objectmodel/object.qdoc | 124 | ||||
-rw-r--r-- | doc/src/core/objectmodel/objecttrees.qdoc | 102 | ||||
-rw-r--r-- | doc/src/core/objectmodel/properties.qdoc | 273 | ||||
-rw-r--r-- | doc/src/core/objectmodel/signalsandslots.qdoc | 451 | ||||
-rw-r--r-- | doc/src/core/threads.qdoc | 572 |
6 files changed, 1659 insertions, 0 deletions
diff --git a/doc/src/core/objectmodel/metaobjects.qdoc b/doc/src/core/objectmodel/metaobjects.qdoc new file mode 100644 index 0000000000..597210e789 --- /dev/null +++ b/doc/src/core/objectmodel/metaobjects.qdoc @@ -0,0 +1,137 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** 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. +** +** 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$ +** +****************************************************************************/ + +/*! + \page metaobjects.html + \title The Meta-Object System + \brief An overview of Qt's meta-object system and introspection capabilities. + + \ingroup qt-basic-concepts + \keyword meta-object + \target Meta-Object System + + Qt's meta-object system provides the signals and slots mechanism for + inter-object communication, run-time type information, and the dynamic + property system. + + The meta-object system is based on three things: + + \list 1 + \o 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 + 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 + QObject subclass with the necessary code to implement + meta-object features. + \endlist + + The \c moc tool reads a C++ source file. If it finds one or more + class declarations that contain the Q_OBJECT macro, it + produces another C++ source file which contains the meta-object + code for each of those classes. This generated source file is + either \c{#include}'d into the class's source file or, more + usually, compiled and linked with the class's implementation. + + In addition to providing the \l{signals and slots} mechanism for + communication between objects (the main reason for introducing + the system), the meta-object code provides the following + additional features: + + \list + \o QObject::metaObject() returns the associated + \l{QMetaObject}{meta-object} for the class. + \o 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 + instance of a class that inherits a specified class within the + QObject inheritance tree. + \o QObject::tr() and QObject::trUtf8() translate strings for + \l{Internationalization with Qt}{internationalization}. + \o QObject::setProperty() and QObject::property() + dynamically set and get properties by name. + \o QMetaObject::newInstance() constructs a new instance of the class. + \endlist + + \target qobjectcast + It is also possible to perform dynamic casts using qobject_cast() + on QObject classes. The qobject_cast() function behaves similarly + to the standard C++ \c dynamic_cast(), with the advantages + that it doesn't require RTTI support and it works across dynamic + library boundaries. It attempts to cast its argument to the pointer + type specified in angle-brackets, returning a non-zero pointer if the + object is of the correct type (determined at run-time), or 0 + if the object's type is incompatible. + + For example, let's assume \c MyWidget inherits from QWidget and + is declared with the Q_OBJECT macro: + + \snippet doc/src/snippets/qtcast/qtcast.cpp 0 + + The \c obj variable, of type \c{QObject *}, actually refers to a + \c MyWidget object, so we can cast it appropriately: + + \snippet doc/src/snippets/qtcast/qtcast.cpp 1 + + The cast from QObject to QWidget is successful, because the + object is actually a \c MyWidget, which is a subclass of QWidget. + Since we know that \c obj is a \c MyWidget, we can also cast it to + \c{MyWidget *}: + + \snippet doc/src/snippets/qtcast/qtcast.cpp 2 + + The cast to \c MyWidget is successful because qobject_cast() + makes no distinction between built-in Qt types and custom types. + + \snippet doc/src/snippets/qtcast/qtcast.cpp 3 + \snippet doc/src/snippets/qtcast/qtcast.cpp 4 + + The cast to QLabel, on the other hand, fails. The pointer is then + set to 0. This makes it possible to handle objects of different + types differently at run-time, based on the type: + + \snippet doc/src/snippets/qtcast/qtcast.cpp 5 + \snippet doc/src/snippets/qtcast/qtcast.cpp 6 + + While it is possible to use QObject as a base class without the + Q_OBJECT macro and without meta-object code, neither signals + and slots nor the other features described here will be available + if the Q_OBJECT macro is not used. From the meta-object + system's point of view, a QObject subclass without meta code is + equivalent to its closest ancestor with meta-object code. This + means for example, that QMetaObject::className() will not return + the actual name of your class, but the class name of this + ancestor. + + Therefore, we strongly recommend that all subclasses of QObject + use the Q_OBJECT macro regardless of whether or not they + actually use signals, slots, and properties. + + \sa QMetaObject, {Qt's Property System}, {Signals and Slots} +*/ diff --git a/doc/src/core/objectmodel/object.qdoc b/doc/src/core/objectmodel/object.qdoc new file mode 100644 index 0000000000..d843f834a5 --- /dev/null +++ b/doc/src/core/objectmodel/object.qdoc @@ -0,0 +1,124 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** 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. +** +** 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$ +** +****************************************************************************/ + +/*! + \page object.html + \title Object Model + \ingroup qt-basic-concepts + \brief A description of the powerful features made possible by Qt's dynamic object model. + + The standard C++ object model provides very efficient runtime + support for the object paradigm. But its static nature is + inflexibile in certain problem domains. Graphical user interface + programming is a domain that requires both runtime efficiency and + a high level of flexibility. Qt provides this, by combining the + speed of C++ with the flexibility of the Qt Object Model. + + Qt adds these features to C++: + + \list + \o a very powerful mechanism for seamless object + communication called \l{signals and slots} + \o 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 + to elegantly integrate many tasks in an event-driven GUI + \o hierarchical and queryable \l{Object Trees & Ownership}{object + trees} that organize object ownership in a natural way + \o 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 + library boundaries. + \endlist + + Many of these Qt features are implemented with standard C++ + techniques, based on inheritance from QObject. Others, like the + object communication mechanism and the dynamic property system, + require the \l{Meta-Object System} provided + by Qt's own \l{moc}{Meta-Object Compiler (moc)}. + + The meta-object system is a C++ extension that makes the language + better suited to true component GUI programming. Although + templates can be used to extend C++, the meta-object system + provides benefits using standard C++ that cannot be achieved with + templates; see \l{Why Doesn't Qt Use Templates for Signals and + Slots?} + + \section1 Important Classes + + These classes form the basis of the Qt Object Model. + + \annotatedlist objectmodel + + \target Identity vs Value + \section1 Qt Objects: Identity vs Value + + Some of the added features listed above for the Qt Object Model, + require that we think of Qt Objects as identities, not values. + Values are copied or assigned; identities are cloned. Cloning + means to create a new identity, not an exact copy of the old + one. For example, twins have different identities. They may look + identical, but they have different names, different locations, and + may have completely different social networks. + + Then cloning an identity is a more complex operation than copying + or assigning a value. We can see what this means in the Qt Object + Model. + + \bold{A Qt Object...} + + \list + + \o 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} + {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 + 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 + 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? + + \endlist + + For these reasons, Qt Objects should be treated as identities, not + as values. Identities are cloned, not copied or assigned, and + cloning an identity is a more complex operation than copying or + assigning a value. Therefore, QObject and all subclasses of + QObject (direct or indirect) have their \l{No copy constructor} + {copy constructor and assignment operator} disabled. + + */ diff --git a/doc/src/core/objectmodel/objecttrees.qdoc b/doc/src/core/objectmodel/objecttrees.qdoc new file mode 100644 index 0000000000..46921106b6 --- /dev/null +++ b/doc/src/core/objectmodel/objecttrees.qdoc @@ -0,0 +1,102 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** 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. +** +** 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$ +** +****************************************************************************/ + +/*! + \page objecttrees.html + \title Object Trees & Ownership + \ingroup qt-basic-concepts + \brief Information about the parent-child pattern used to describe + object ownership in Qt. + + \section1 Overview + + \link QObject QObjects\endlink organize themselves in object trees. + When you create a QObject with another object as parent, it's added to + the parent's \link QObject::children() children() \endlink list, and + is deleted when the parent is. It turns out that this approach fits + the needs of GUI objects very well. For example, a \l QShortcut + (keyboard shortcut) is a child of the relevant window, so when the + user closes that window, the shorcut is deleted too. + + \l QWidget, the base class of everything that appears on the screen, + extends the parent-child relationship. A child normally also becomes a + child widget, i.e. it is displayed in its parent's coordinate system + and is graphically clipped by its parent's boundaries. For example, + when the application deletes a message box after it has been + closed, the message box's buttons and label are also deleted, just as + we'd want, because the buttons and label are children of the message + box. + + You can also delete child objects yourself, and they will remove + themselves from their parents. For example, when the user removes a + toolbar it may lead to the application deleting one of its \l QToolBar + objects, in which case the tool bar's \l QMainWindow parent would + detect the change and reconfigure its screen space accordingly. + + The debugging functions \l QObject::dumpObjectTree() and \l + QObject::dumpObjectInfo() are often useful when an application looks or + acts strangely. + + \target note on the order of construction/destruction of QObjects + \section1 Construction/Destruction Order of QObjects + + When \l {QObject} {QObjects} are created on the heap (i.e., created + with \e new), a tree can be constructed from them in any order, and + later, the objects in the tree can be destroyed in any order. When any + QObject in the tree is deleted, if the object has a parent, the + destructor automatically removes the object from its parent. If the + object has children, the destructor automatically deletes each + child. No QObject is deleted twice, regardless of the order of + destruction. + + When \l {QObject} {QObjects} are created on the stack, the same + behavior applies. Normally, the order of destruction still doesn't + present a problem. Consider the following snippet: + + \snippet doc/src/snippets/code/doc_src_objecttrees.cpp 0 + + The parent, \c window, and the child, \c quit, are both \l {QObject} + {QObjects} because QPushButton inherits QWidget, and QWidget inherits + QObject. This code is correct: the destructor of \c quit is \e not + called twice because the C++ language standard \e {(ISO/IEC 14882:2003)} + specifies that destructors of local objects are called in the reverse + order of their constructors. Therefore, the destructor of + the child, \c quit, is called first, and it removes itself from its + parent, \c window, before the destructor of \c window is called. + + But now consider what happens if we swap the order of construction, as + shown in this second snippet: + + \snippet doc/src/snippets/code/doc_src_objecttrees.cpp 1 + + In this case, the order of destruction causes a problem. The parent's + destructor is called first because it was created last. It then calls + the destructor of its child, \c quit, which is incorrect because \c + quit is a local variable. When \c quit subsequently goes out of scope, + its destructor is called again, this time correctly, but the damage has + already been done. +*/ diff --git a/doc/src/core/objectmodel/properties.qdoc b/doc/src/core/objectmodel/properties.qdoc new file mode 100644 index 0000000000..befbde190b --- /dev/null +++ b/doc/src/core/objectmodel/properties.qdoc @@ -0,0 +1,273 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** 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. +** +** 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$ +** +****************************************************************************/ + +/*! + \page properties.html + \title The Property System + \brief An overview of Qt's property system. + + \ingroup qt-basic-concepts + \target Qt's Property System + + Qt provides a sophisticated property system similar to the ones + supplied by some compiler vendors. However, as a compiler- and + platform-independent library, Qt does not rely on non-standard + compiler features like \c __property or \c [property]. The Qt + solution works with \e any standard C++ compiler on every platform + Qt supports. It is based on the \l {Meta-Object System} that also + provides inter-object communication via \l{signals and slots}. + + \section1 Requirements for Declaring Properties + + To declare a property, use the \l {Q_PROPERTY()} {Q_PROPERTY()} + macro in a class that inherits QObject. + + \snippet doc/src/snippets/code/doc_src_properties.cpp 0 + + Here are some typical examples of property declarations taken from + class QWidget. + + \snippet doc/src/snippets/code/doc_src_properties.cpp 1 + + A property behaves like a class data member, but it has additional + features accessible through the \l {Meta-Object System}. + + \list + + \o 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 + 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 + 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, + QWidget::unsetCursor(), since no call to QWidget::setCursor() can + 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 + 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 + 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 + 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 + 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 + 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 + (default true), but e.g., QWidget::minimumWidth() has \c STORED + 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 + 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 + 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 + 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. + + \endlist + + The \c READ, \c WRITE, and \c RESET functions can be inherited. + They can also be virtual. When they are inherited in classes where + multiple inheritance is used, they must come from the first + inherited class. + + The property type can be any type supported by QVariant, or it can + be a user-defined type. In this example, class QDate is considered + to be a user-defined type. + + \snippet doc/src/snippets/code/doc_src_properties.cpp 2 + + Because QDate is user-defined, you must include the \c{<QDate>} + header file with the property declaration. + + For QMap, QList, and QValueList properties, the property value is + a QVariant whose value is the entire list or map. Note that the + Q_PROPERTY string cannot contain commas, because commas separate + macro arguments. Therefore, you must use \c QMap as the property + type instead of \c QMap<QString,QVariant>. For consistency, also + use \c QList and \c QValueList instead of \c QList<QVariant> and + \c QValueList<QVariant>. + + \section1 Reading and Writing Properties with the Meta-Object System + + A property can be read and written using the generic functions + QObject::property() and QObject::setProperty(), without knowing + anything about the owning class except the property's name. In + the code snippet below, the call to QAbstractButton::setDown() and + the call to QObject::setProperty() both set property "down". + + \snippet doc/src/snippets/code/doc_src_properties.cpp 3 + + Accessing a property through its \c WRITE accessor is the better + of the two, because it is faster and gives better diagnostics at + compile time, but setting the property this way requires that you + know about the class at compile time. Accessing properties by name + lets you access classes you don't know about at compile time. You + can \e discover a class's properties at run time by querying its + QObject, QMetaObject, and \l {QMetaProperty} {QMetaProperties}. + + \snippet doc/src/snippets/code/doc_src_properties.cpp 4 + + In the above snippet, QMetaObject::property() is used to get \l + {QMetaProperty} {metadata} about each property defined in some + unknown class. The property name is fetched from the metadata and + passed to QObject::property() to get the \l {QVariant} {value} of + the property in the current \l {QObject}{object}. + + \section1 A Simple Example + + Suppose we have a class MyClass, which is derived from QObject and + which uses the Q_OBJECT macro in its private section. We want to + declare a property in MyClass to keep track of a priorty + value. The name of the property will be \e priority, and its type + will be an enumeration type named \e Priority, which is defined in + MyClass. + + We declare the property with the Q_PROPERTY() macro in the private + section of the class. The required \c READ function is named \c + priority, and we include a \c WRITE function named \c setPriority. + The enumeration type must be registered with the \l {Meta-Object + System} using the Q_ENUMS() macro. Registering an enumeration type + makes the enumerator names available for use in calls to + QObject::setProperty(). We must also provide our own declarations + for the \c READ and \c WRITE functions. The declaration of MyClass + then might look like this: + + \snippet doc/src/snippets/code/doc_src_properties.cpp 5 + + The \c READ function is const and returns the property type. The + \c WRITE function returns void and has exactly one parameter of + the property type. The meta-object compiler enforces these + requirements. + + Given a pointer to an instance of MyClass or a pointer to a + QObject that is an instance of MyClass, we have two ways to set + its priority property: + + \snippet doc/src/snippets/code/doc_src_properties.cpp 6 + + In the example, the enumeration type that is the property type is + declared in MyClass and registered with the \l{Meta-Object System} + using the Q_ENUMS() macro. This makes the enumeration values + available as strings for use as in the call to setProperty(). Had + the enumeration type been declared in another class, its fully + qualified name (i.e., OtherClass::Priority) would be required, and + that other class would also have to inherit QObject and register + the enumeration type there using the Q_ENUMS() macro. + + A similar macro, Q_FLAGS(), is also available. Like Q_ENUMS(), it + registers an enumeration type, but it marks the type as being a + set of \e flags, i.e. values that can be OR'd together. An I/O + class might have enumeration values \c Read and \c Write and then + QObject::setProperty() could accept \c{Read | Write}. Q_FLAGS() + should be used to register this enumeration type. + + \section1 Dynamic Properties + + QObject::setProperty() can also be used to add \e new properties + to an instance of a class at runtime. When it is called with a + name and a value, if a property with the given name exists in the + QObject, and if the given value is compatible with the property's + type, the value is stored in the property, and true is returned. + If the value is \e not compatible with the property's type, the + property is \e not changed, and false is returned. But if the + property with the given name doesn't exist in the QObject (i.e., + if it wasn't declared with Q_PROPERTY(), a new property with the + given name and value is automatically added to the QObject, but + false is still returned. This means that a return of false can't + be used to determine whether a particular property was actually + set, unless you know in advance that the property already exists + in the QObject. + + Note that \e dynamic properties are added on a per instance basis, + i.e., they are added to QObject, not QMetaObject. A property can + be removed from an instance by passing the property name and an + invalid QVariant value to QObject::setProperty(). The default + constructor for QVariant constructs an invalid QVariant. + + Dynamic properties can be queried with QObject::property(), just + like properties declared at compile time with Q_PROPERTY(). + + \sa {Meta-Object System}, {Signals and Slots} + + \section1 Properties and Custom Types + + Custom types used by properties need to be registered using the + Q_DECLARE_METATYPE() macro so that their values can be stored in + QVariant objects. This makes them suitable for use with both + static properties declared using the Q_PROPERTY() macro in class + definitions and dynamic properties created at run-time. + + \sa Q_DECLARE_METATYPE(), QMetaType, QVariant + + \section1 Adding Additional Information to a Class + + Connected to the property system is an additional macro, + Q_CLASSINFO(), that can be used to attach additional + \e{name}--\e{value} pairs to a class's meta-object, for example: + + \snippet doc/src/snippets/code/doc_src_properties.cpp 7 + + Like other meta-data, class information is accessible at run-time + through the meta-object; see QMetaObject::classInfo() for details. +*/ diff --git a/doc/src/core/objectmodel/signalsandslots.qdoc b/doc/src/core/objectmodel/signalsandslots.qdoc new file mode 100644 index 0000000000..2f8646ea1c --- /dev/null +++ b/doc/src/core/objectmodel/signalsandslots.qdoc @@ -0,0 +1,451 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** 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. +** +** 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$ +** +****************************************************************************/ + +/*! + \page signalsandslots.html + \title Signals & Slots + \ingroup qt-basic-concepts + \brief An overview of Qt's signals and slots inter-object + communication mechanism. + + Signals and slots are used for communication between objects. The + signals and slots mechanism is a central feature of Qt and + probably the part that differs most from the features provided by + other frameworks. + + \tableofcontents + + \section1 Introduction + + In GUI programming, when we change one widget, we often want + another widget to be notified. More generally, we want objects of + any kind to be able to communicate with one another. For example, + if a user clicks a \gui{Close} button, we probably want the + window's \l{QWidget::close()}{close()} function to be called. + + Older toolkits achieve this kind of communication using + callbacks. A callback is a pointer to a function, so if you want + a processing function to notify you about some event you pass a + pointer to another function (the callback) to the processing + function. The processing function then calls the callback when + appropriate. Callbacks have two fundamental flaws: Firstly, they + are not type-safe. We can never be certain that the processing + function will call the callback with the correct arguments. + Secondly, the callback is strongly coupled to the processing + function since the processing function must know which callback + to call. + + \section1 Signals and Slots + + In Qt, we have an alternative to the callback technique: We use + signals and slots. A signal is emitted when a particular event + occurs. Qt's widgets have many predefined signals, but we can + always subclass widgets to add our own signals to them. A slot + is a function that is called in response to a particular signal. + Qt's widgets have many pre-defined slots, but it is common + practice to subclass widgets and add your own slots so that you + can handle the signals that you are interested in. + + \img abstract-connections.png + \omit + \caption An abstract view of some signals and slots connections + \endomit + + The signals and slots mechanism is type safe: The signature of a + signal must match the signature of the receiving slot. (In fact a + slot may have a shorter signature than the signal it receives + because it can ignore extra arguments.) Since the signatures are + compatible, the compiler can help us detect type mismatches. + Signals and slots are loosely coupled: A class which emits a + signal neither knows nor cares which slots receive the signal. + Qt's signals and slots mechanism ensures that if you connect a + signal to a slot, the slot will be called with the signal's + parameters at the right time. Signals and slots can take any + number of arguments of any type. They are completely type safe. + + All classes that inherit from QObject or one of its subclasses + (e.g., QWidget) can contain signals and slots. Signals are emitted by + objects when they change their state in a way that may be interesting + to other objects. This is all the object does to communicate. It + does not know or care whether anything is receiving the signals it + emits. This is true information encapsulation, and ensures that the + object can be used as a software component. + + Slots can be used for receiving signals, but they are also normal + member functions. Just as an object does not know if anything receives + its signals, a slot does not know if it has any signals connected to + it. This ensures that truly independent components can be created with + Qt. + + You can connect as many signals as you want to a single slot, and a + signal can be connected to as many slots as you need. It is even + possible to connect a signal directly to another signal. (This will + emit the second signal immediately whenever the first is emitted.) + + Together, signals and slots make up a powerful component programming + mechanism. + + \section1 A Small Example + + A minimal C++ class declaration might read: + + \snippet doc/src/snippets/signalsandslots/signalsandslots.h 0 + + A small QObject-based class might read: + + \snippet doc/src/snippets/signalsandslots/signalsandslots.h 1 + \codeline + \snippet doc/src/snippets/signalsandslots/signalsandslots.h 2 + \snippet doc/src/snippets/signalsandslots/signalsandslots.h 3 + + The QObject-based version has the same internal state, and provides + public methods to access the state, but in addition it has support + for component programming using signals and slots. This class can + tell the outside world that its state has changed by emitting a + signal, \c{valueChanged()}, and it has a slot which other objects + can send signals to. + + All classes that contain signals or slots must mention + Q_OBJECT at the top of their declaration. They must also derive + (directly or indirectly) from QObject. + + Slots are implemented by the application programmer. + Here is a possible implementation of the \c{Counter::setValue()} + slot: + + \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 0 + + The \c{emit} line emits the signal \c valueChanged() from the + object, with the new value as argument. + + In the following code snippet, we create two \c Counter objects + and connect the first object's \c valueChanged() signal to the + second object's \c setValue() slot using QObject::connect(): + + \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 1 + \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 2 + \codeline + \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 3 + \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 4 + + Calling \c{a.setValue(12)} makes \c{a} emit a + \c{valueChanged(12)} signal, which \c{b} will receive in its + \c{setValue()} slot, i.e. \c{b.setValue(12)} is called. Then + \c{b} emits the same \c{valueChanged()} signal, but since no slot + has been connected to \c{b}'s \c{valueChanged()} signal, the + signal is ignored. + + Note that the \c{setValue()} function sets the value and emits + the signal only if \c{value != m_value}. This prevents infinite + looping in the case of cyclic connections (e.g., if + \c{b.valueChanged()} were connected to \c{a.setValue()}). + + By default, for every connection you make, a signal is emitted; + two signals are emitted for duplicate connections. You can break + all of these connections with a single disconnect() call. + If you pass the Qt::UniqueConnection \a type, the connection will only + be made if it is not a duplicate. If there is already a duplicate + (exact same signal to the exact same slot on the same objects), + the connection will fail and connect will return false + + This example illustrates that objects can work together without needing to + know any information about each other. To enable this, the objects only + need to be connected together, and this can be achieved with some simple + QObject::connect() function calls, or with \c{uic}'s + \l{Using a Designer UI File in Your Application#Automatic Connections} + {automatic connections} feature. + + \section1 Building the Example + + The C++ preprocessor changes or removes the \c{signals}, + \c{slots}, and \c{emit} keywords so that the compiler is + presented with standard C++. + + By running the \l moc on class definitions that contain signals + or slots, a C++ source file is produced which should be compiled + and linked with the other object files for the application. If + you use \l qmake, the makefile rules to automatically invoke \c + moc will be added to your project's makefile. + + \section1 Signals + + Signals are emitted by an object when its internal state has changed + in some way that might be interesting to the object's client or owner. + Only the class that defines a signal and its subclasses can emit the + signal. + + When a signal is emitted, the slots connected to it are usually + executed immediately, just like a normal function call. When this + happens, the signals and slots mechanism is totally independent of + any GUI event loop. Execution of the code following the \c emit + statement will occur once all slots have returned. The situation is + slightly different when using \l{Qt::ConnectionType}{queued + connections}; in such a case, the code following the \c emit keyword + will continue immediately, and the slots will be executed later. + + If several slots are connected to one signal, the slots will be + executed one after the other, in the order they have been connected, + when the signal is emitted. + + Signals are automatically generated by the \l moc and must not be + implemented in the \c .cpp file. They can never have return types + (i.e. use \c void). + + A note about arguments: Our experience shows that signals and slots + are more reusable if they do not use special types. If + QScrollBar::valueChanged() were to use a special type such as the + hypothetical QScrollBar::Range, it could only be connected to + slots designed specifically for QScrollBar. Connecting different + input widgets together would be impossible. + + \section1 Slots + + A slot is called when a signal connected to it is emitted. Slots are + normal C++ functions and can be called normally; their only special + feature is that signals can be connected to them. + + Since slots are normal member functions, they follow the normal C++ + rules when called directly. However, as slots, they can be invoked + by any component, regardless of its access level, via a signal-slot + connection. This means that a signal emitted from an instance of an + arbitrary class can cause a private slot to be invoked in an instance + of an unrelated class. + + You can also define slots to be virtual, which we have found quite + useful in practice. + + Compared to callbacks, signals and slots are slightly slower + because of the increased flexibility they provide, although the + difference for real applications is insignificant. In general, + emitting a signal that is connected to some slots, is + approximately ten times slower than calling the receivers + directly, with non-virtual function calls. This is the overhead + required to locate the connection object, to safely iterate over + all connections (i.e. checking that subsequent receivers have not + been destroyed during the emission), and to marshall any + parameters in a generic fashion. While ten non-virtual function + calls may sound like a lot, it's much less overhead than any \c + new or \c delete operation, for example. As soon as you perform a + string, vector or list operation that behind the scene requires + \c new or \c delete, the signals and slots overhead is only + responsible for a very small proportion of the complete function + call costs. + + The same is true whenever you do a system call in a slot; or + indirectly call more than ten functions. On an i586-500, you can + emit around 2,000,000 signals per second connected to one + receiver, or around 1,200,000 per second connected to two + receivers. The simplicity and flexibility of the signals and + slots mechanism is well worth the overhead, which your users + won't even notice. + + Note that other libraries that define variables called \c signals + or \c slots may cause compiler warnings and errors when compiled + alongside a Qt-based application. To solve this problem, \c + #undef the offending preprocessor symbol. + + \section1 Meta-Object Information + + The meta-object compiler (\l moc) parses the class declaration in + a C++ file and generates C++ code that initializes the + meta-object. The meta-object contains the names of all the signal + and slot members, as well as pointers to these functions. + + The meta-object contains additional information such as the + object's \link QObject::className() class name\endlink. You can + also check if an object \link QObject::inherits() + inherits\endlink a specific class, for example: + + \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 5 + \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 6 + + The meta-object information is also used by qobject_cast<T>(), which + is similar to QObject::inherits() but is less error-prone: + + \snippet doc/src/snippets/signalsandslots/signalsandslots.cpp 7 + + See \l{Meta-Object System} for more information. + + \section1 A Real Example + + Here is a simple commented example of a widget. + + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 0 + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 1 + \codeline + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 2 + \codeline + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 3 + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 4 + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 5 + + \c LcdNumber inherits QObject, which has most of the signal-slot + knowledge, via QFrame and QWidget. It is somewhat similar to the + built-in QLCDNumber widget. + + The Q_OBJECT macro is expanded by the preprocessor to declare + several member functions that are implemented by the \c{moc}; if + you get compiler errors along the lines of "undefined reference + to vtable for \c{LcdNumber}", you have probably forgotten to + \l{moc}{run the moc} or to include the moc output in the link + command. + + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 6 + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 7 + + It's not obviously relevant to the moc, but if you inherit + QWidget you almost certainly want to have the \c parent argument + in your constructor and pass it to the base class's constructor. + + Some destructors and member functions are omitted here; the \c + moc ignores member functions. + + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 8 + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 9 + + \c LcdNumber emits a signal when it is asked to show an impossible + value. + + If you don't care about overflow, or you know that overflow + cannot occur, you can ignore the \c overflow() signal, i.e. don't + connect it to any slot. + + If on the other hand you want to call two different error + functions when the number overflows, simply connect the signal to + two different slots. Qt will call both (in the order they were connected). + + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 10 + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 11 + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 12 + \codeline + \snippet doc/src/snippets/signalsandslots/lcdnumber.h 13 + + A slot is a receiving function used to get information about + state changes in other widgets. \c LcdNumber uses it, as the code + above indicates, to set the displayed number. Since \c{display()} + is part of the class's interface with the rest of the program, + the slot is public. + + Several of the example programs connect the + \l{QScrollBar::valueChanged()}{valueChanged()} signal of a + QScrollBar to the \c display() slot, so the LCD number + continuously shows the value of the scroll bar. + + Note that \c display() is overloaded; Qt will select the + appropriate version when you connect a signal to the slot. With + callbacks, you'd have to find five different names and keep track + of the types yourself. + + Some irrelevant member functions have been omitted from this + example. + + \section1 Signals And Slots With Default Arguments + + The signatures of signals and slots may contain arguments, and the + arguments can have default values. Consider QObject::destroyed(): + + \code + void destroyed(QObject* = 0); + \endcode + + When a QObject is deleted, it emits this QObject::destroyed() + signal. We want to catch this signal, wherever we might have a + dangling reference to the deleted QObject, so we can clean it up. + A suitable slot signature might be: + + \code + void objectDestroyed(QObject* obj = 0); + \endcode + + To connect the signal to the slot, we use QObject::connect() and + the \c{SIGNAL()} and \c{SLOT()} macros. The rule about whether to + include arguments or not in the \c{SIGNAL()} and \c{SLOT()} + macros, if the arguments have default values, is that the + signature passed to the \c{SIGNAL()} macro must \e not have fewer + arguments than the signature passed to the \c{SLOT()} macro. + + All of these would work: + \code + connect(sender, SIGNAL(destroyed(QObject*)), this, SLOT(objectDestroyed(Qbject*))); + connect(sender, SIGNAL(destroyed(QObject*)), this, SLOT(objectDestroyed())); + connect(sender, SIGNAL(destroyed()), this, SLOT(objectDestroyed())); + \endcode + But this one won't work: + \code + connect(sender, SIGNAL(destroyed()), this, SLOT(objectDestroyed(QObject*))); + \endcode + + ...because the slot will be expecting a QObject that the signal + will not send. This connection will report a runtime error. + + \section1 Advanced Signals and Slots Usage + + For cases where you may require information on the sender of the + signal, Qt provides the QObject::sender() function, which returns + a pointer to the object that sent the signal. + + The QSignalMapper class is provided for situations where many + signals are connected to the same slot and the slot needs to + handle each signal differently. + + Suppose you have three push buttons that determine which file you + will open: "Tax File", "Accounts File", or "Report File". + + In order to open the correct file, you use QSignalMapper::setMapping() to + map all the clicked() signals to a QSignalMapper object. Then you connect + the file's QPushButton::clicked() signal to the QSignalMapper::map() slot. + + \snippet doc/src/snippets/signalmapper/filereader.cpp 0 + + Then, you connect the \l{QSignalMapper::}{mapped()} signal to + \c{readFile()} where a different file will be opened, depending on + which push button is pressed. + + \snippet doc/src/snippets/signalmapper/filereader.cpp 1 + + \note The following code will compile and run, but due to signature normalization, the code will be slower. + + \snippet doc/src/snippets/signalmapper/filereader.cpp 2 + + \sa {Meta-Object System}, {Qt's Property System} + + \target 3rd Party Signals and Slots + \section2 Using Qt with 3rd Party Signals and Slots + + It is possible to use Qt with a 3rd party signal/slot mechanism. + You can even use both mechanisms in the same project. Just add the + following line to your qmake project (.pro) file. + + \snippet doc/src/snippets/code/doc_src_containers.cpp 22 + + It tells Qt not to define the moc keywords \c{signals}, \c{slots}, + and \c{emit}, because these names will be used by a 3rd party + library, e.g. Boost. Then to continue using Qt signals and slots + with the \c{no_keywords} flag, simply replace all uses of the Qt + moc keywords in your sources with the corresponding Qt macros + Q_SIGNALS (or Q_SIGNAL), Q_SLOTS (or Q_SLOT), and Q_EMIT. +*/ diff --git a/doc/src/core/threads.qdoc b/doc/src/core/threads.qdoc new file mode 100644 index 0000000000..09707f5dfc --- /dev/null +++ b/doc/src/core/threads.qdoc @@ -0,0 +1,572 @@ +/**************************************************************************** +** +** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies). +** All rights reserved. +** Contact: Nokia Corporation (qt-info@nokia.com) +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** 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. +** +** 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$ +** +****************************************************************************/ + +/*! + \page thread-basics.html + \ingroup tutorials + \startpage {index.html}{Qt Reference Documentation} + + \title Threading Basics + \brief An introduction to threads + + \section1 What Are Threads? + + Threads are about doing things in parallel, just like processes. So how do + threads differ from processes? While you are making calculations on a + spreadsheet, there may also be a media player running on the same desktop + playing your favorite song. Here is an example of two processes working in + parallel: one running the spreadsheet program; one running a media player. + Multitasking is a well known term for this. A closer look at the media + player reveals that there are again things going on in parallel within one + single process. While the media player is sending music to the audio driver, + the user interface with all its bells and whistles is being constantly + updated. This is what threads are for \mdash concurrency within one single + process. + + So how is concurrency implemented? Parallel work on single core CPUs is an + illusion which is somewhat similar to the illusion of moving images in + cinema. + For processes, the illusion is produced by interrupting the processor's + work on one process after a very short time. Then the processor moves on to + the next process. In order to switch between processes, the current program + counter is saved and the next processor's program counter is loaded. This + is not sufficient because the same needs to be done with registers and + certain architecture and OS specific data. + + Just as one CPU can power two or more processes, it is also possible to let + the CPU run on two different code segments of one single process. When a + process starts, it always executes one code segment and therefore the + process is said to have one thread. However, the program may decide to + start a second thread. Then, two different code sequences are processed + simultaneously inside one process. Concurrency is achieved on single core + CPUs by repeatedly saving program counters and registers then loading the + next thread's program counters and registers. No cooperation from the + program is required to cycle between the active threads. A thread may be in + any state when the switch to the next thread occurs. + + The current trend in CPU design is to have several cores. A typical + single-threaded application can make use of only one core. However, a + program with multiple threads can be assigned to multiple cores, making + things happen in a truly concurrent way. As a result, distributing work + to more than one thread can make a program run much faster on multicore + CPUs because additional cores can be used. + + \section2 GUI Thread and Worker Thread + + As mentioned, each program has one thread when it is started. This thread + is called the "main thread" (also known as the "GUI thread" in Qt + applications). The Qt GUI must run in this thread. All widgets and several + related classes, for example QPixmap, don't work in secondary threads. + A secondary thread is commonly referred to as a "worker thread" because it + is used to offload processing work from the main thread. + + \section2 Simultaneous Access to Data + + Each thread has its own stack, which means each thread has its own call + history and local variables. Unlike processes, threads share the same + address space. The following diagram shows how the building blocks of + threads are located in memory. Program counter and registers of inactive + threads are typically kept in kernel space. There is a shared copy of the + code and a separate stack for each thread. + + \image threadvisual-example.png "Thread visualization" + + If two threads have a pointer to the same object, it is possible that both + threads will access that object at the same time and this can potentially + destroy the object's integrity. It's easy to imagine the many things that + can go wrong when two methods of the same object are executed + simultaneously. + + Sometimes it is necessary to access one object from different threads; + for example, when objects living in different threads need to communicate. + Since threads use the same address space, it is easier and faster for + threads to exchange data than it is for processes. Data does not have to be + serialized and copied. Passing pointers is possible, but there must be a + strict coordination of what thread touches which object. Simultaneous + execution of operations on one object must be prevented. There are several + ways of achieving this and some of them are described below. + + So what can be done safely? All objects created in a thread can be used + safely within that thread provided that other threads don't have references + to them and objects don't have implicit coupling with other threads. Such + implicit coupling may happen when data is shared between instances as with + static members, singletons or global data. Familiarize yourself with the + concept of \l{Reentrancy and Thread-Safety}{thread safe and reentrant} + classes and functions. + + \section1 Using Threads + + 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 + offloading long lasting processing or blocking calls to other threads. + \endlist + + \section2 When to Use Alternatives to Threads + + Developers need to be very careful with threads. It is easy to start other + threads, but very hard to ensure that all shared data remains consistent. + Problems are often hard to find because they may only show up once in a + while or only on specific hardware configurations. Before creating threads + to solve certain problems, possible alternatives should be considered. + + \table + \header + \o Alternative + \o Comment + \row + \o QEventLoop::processEvents() + \o 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 + 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 + 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 + threads. Reactive design is less error prone and energy efficient + than threading. In many cases there are also performance benefits. + \endtable + + In general, it is recommended to only use safe and tested paths and to + avoid introducing ad-hoc threading concepts. QtConcurrent provides an easy + interface for distributing work to all of the processor's cores. The + threading code is completely hidden in the QtConcurrent framework, so you + don't have to take care of the details. However, QtConcurrent can't be used + when communication with the running thread is needed, and it shouldn't be + used to handle blocking operations. + + \section2 Which Qt Thread Technology Should You Use? + + Sometimes you want to do more than just running a method in the context of + another thread. You may want to have an object which lives in another + thread that provides a service to the GUI thread. Maybe you want another + thread to stay alive forever to poll hardware ports and send a signal to + the GUI thread when something noteworthy has happened. Qt provides + different solutions for developing threaded applications. The right + solution depends on the purpose of the new thread as well as on the + thread's lifetime. + + \table + \header + \o Lifetime of thread + \o Development task + \o Solution + \row + \o One call + \o Run one method within another thread and quit the thread when the + method is finished. + \o 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 + pool with QThreadPool::globalInstance()->start() + \o 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. + 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 + 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 + course of processing, status information should be sent to the GUI + thread. + \o 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 + 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 + 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 + 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 + polling. However, the best solution for polling is to avoid it + completely. Sometimes using QSocketNotifier is an alternative. + \endtable + + + \section1 Qt Thread Basics + + QThread is a very convenient cross platform abstraction of native platform + threads. Starting a thread is very simple. Let us look at a short piece of + code that generates another thread which says hello in that thread and then + exits. + + \snippet examples/tutorials/threads/hellothread/hellothread.h 1 + + We derive a class from QThread and reimplement the \l{QThread::}{run()} + method. + + \snippet examples/tutorials/threads/hellothread/hellothread.cpp 1 + + The run method contains the code that will be run in a separate thread. In + this example, a message containing the thread ID will be printed. + QThread::start() will call the method in another thread. + + \snippet examples/tutorials/threads/hellothread/main.cpp 1 + + To start the thread, our thread object needs to be instantiated. The + \l{QThread::}{start()} method creates a new thread and calls the + reimplemented \l{QThread::}{run()} method in this new thread. Right after + \l{QThread::}{start()} is called, two program counters walk through the + program code. The main function starts with only the GUI thread running and + it should terminate with only the GUI thread running. Exiting the program + when another thread is still busy is a programming error, and therefore, + wait is called which blocks the calling thread until the + \l{QThread::}{run()} method has completed. + + This is the result of running the code: + + \badcode + hello from GUI thread 3079423696 + hello from worker thread 3076111216 + \endcode + + + \section2 QObject and Threads + + A QObject is said to have a \e{thread affinity} or, in other words, that it + lives in a certain thread. This means that, at creation time, QObject saves + a pointer to the current thread. This information becomes relevant when an + event is posted with \l{QCoreApplication::}{postEvent()}. The event will be + put in the corresponding thread's event loop. If the thread where the + QObject lives doesn't have an event loop, the event will never be delivered. + + To start an event loop, \l{QThread::}{exec()} must be called inside + \l{QThread::}{run()}. Thread affinity can be changed using + \l{QObject::}{moveToThread()}. + + As mentioned above, developers must always be careful when calling objects' + methods from other threads. Thread affinity does not change this situation. + Qt documentation marks several methods as thread-safe. + \l{QCoreApplication::}{postEvent()} is a noteworthy example. A thread-safe + method may be called from different threads simultaneously. + + In cases where there is usually no concurrent access to methods, calling + non-thread-safe methods of objects in other threads may work thousands + of times before a concurrent access occurs, causing unexpected behavior. + Writing test code does not entirely ensure thread correctness, but it is + still important. + On Linux, Valgrind and Helgrind can help detect threading errors. + + The anatomy of QThread is quite interesting: + + \list + \o 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 + 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 + \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 + 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, + the main thread should not touch the additional members anymore. After + the worker has terminated, the main thread can access the additional + members again. This is a convenient strategy for passing parameters to a + thread before it is started as well as for collecting the result once it + has terminated. + \endlist + + A QObject's parent must always be in the same thread. This has a surprising + consequence for objects generated within the \l{QThread::}{run()} method: + + \code + void HelloThread::run() + { + QObject *object1 = new QObject(this); //error, parent must be in the same thread + QObject object2; // OK + QSharedPointer <QObject> object3(new QObject); // OK + } + \endcode + + \section2 Using a Mutex to Protect the Integrity of Data + + A mutex is an object that has \l{QMutex::}{lock()} and \l{QMutex::}{unlock()} + methods and remembers if it is already locked. A mutex is designed to be + called from multiple threads. \l{QMutex::}{lock()} returns immediately if + the mutex is not locked. The next call from another thread will find the + mutex in a locked state and then \l{QMutex::}{lock()} will block the thread + until the other thread calls \l{QMutex::}{unlock()}. This functionality can + make sure that a code section will be executed by only one thread at a time. + + The following line sketches how a mutex can be used to make a method + thread-safe: + + \code + void Worker::work() + { + this->mutex.lock(); // first thread can pass, other threads will be blocked here + doWork(); + this->mutex.unlock(); + } + \endcode + + What happens if one thread does not unlock a mutex? The result can be a + frozen application. In the example above, an exception might be thrown and + \c{mutex.unlock()} will never be reached. To prevent problems like this, + QMutexLocker should be used. + + \code + void Worker::work() + { + QMutexLocker locker(&mutex); // Locks the mutex and unlocks when locker exits the scope + doWork(); + } + \endcode + + This looks easy, but mutexes introduce a new class of problems: deadlocks. + A deadlock happens when a thread waits for a mutex to become unlocked, but + the mutex remains locked because the owning thread is waiting for the first + thread to unlock it. The result is a frozen application. Mutexes can be + used to make a method thread safe. Most Qt methods aren't thread safe + because there is always a performance penalty when using mutexes. + + It isn't always possible to lock and unlock a mutex in a method. Sometimes + the need to lock spans several calls. For example, modifying a container + with an iterator requires a sequence of several calls which should not be + interrupted by other threads. In such a scenario, locking can be achieved + with a mutex that is kept outside of the object to be manipulated. With an + external mutex, the duration of locking can be adjusted to the needs of the + operation. One disadvantage is that external mutexes aid locking, but do + not enforce it because users of the object may forget to use it. + + \section2 Using the Event Loop to Prevent Data Corruption + + The event loops of Qt are a very valuable tool for inter-thread + communication. Every thread may have its own event loop. A safe way of + calling a slot in another thread is by placing that call in another + thread's event loop. This ensures that the target object finishes the + method that is currently running before another method is started. + + So how is it possible to put a method invocation in an event loop? Qt has + two ways of doing this. One way is via queued signal-slot connections; the + other way is to post an event with QCoreApplication::postEvent(). A queued + signal-slot connection is a signal slot connection that is executed + asynchronously. The internal implementation is based on posted events. The + arguments of the signal are put into the event loop and the signal method + returns immediately. + + The connected slot will be executed at a time which depends on what else is + in the event loop. + + Communication via the event loop eliminates the deadlock problem we face + when using mutexes. This is why we recommend using the event loop rather + than locking an object using a mutex. + + \section2 Dealing with Asynchronous Execution + + One way to obtain a worker thread's result is by waiting for the thread + to terminate. In many cases, however, a blocking wait isn't acceptable. The + alternative to a blocking wait are asynchronous result deliveries with + either posted events or queued signals and slots. This generates a certain + overhead because an operation's result does not appear on the next source + line, but in a slot located somewhere else in the source file. Qt + developers are used to working with this kind of asynchronous behavior + because it is much similar to the kind of event-driven programming used in + GUI applications. + + \section1 Examples + + This tutorial comes with examples for Qt's three basic ways of working with + threads. Two more examples show how to communicate with a running thread + and how a QObject can be placed in another thread, providing service to the + 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 + provides service to the main thread} + \endlist + + The following examples can all be compiled and run independently. The source can + be found in the examples directory: examples/tutorials/threads/ + + \section2 Example 1: Using the Thread Pool + + Creating and destroying threads frequently can be expensive. To avoid the + cost of thread creation, a thread pool can be used. A thread pool is a + place where threads can be parked and fetched. We can write the same + "hello thread" program as \l{Qt Thread Basics}{above} using the global + thread pool. We derive a class from QRunnable. The code we want to run in + another thread needs to be placed in the reimplemented QRunnable::run() + method. + + \snippet examples/tutorials/threads/hellothreadpool/hellothreadpool.cpp 1 + + We instantiate Work in main(), locate the global thread pool and use the + QThreadPool::start() method. Now the thread pool runs our worker in another + thread. Using the thread pool has a performance advantage because threads + are not destroyed after they have finished running. They are kept in a pool + and wait to be used again later. + + \section2 Example 2: Using QtConcurrent + + \snippet examples/tutorials/threads/helloconcurrent/helloconcurrent.cpp 1 + + We write a global function hello() to implement the work. QtConcurrent::run() + is used to run the function in another thread. The result is a QFuture. + QFuture provides a method called \l{QFuture::}{waitForFinished()}, which + blocks until the calculation is completed. The real power of QtConcurrent + becomes visible when data can be made available in a container. QtConcurrent + provides several functions that are able to process itemized data on all + available cores simultaneously. The use of QtConcurrent is very similar to + applying an STL algorithm to an STL container. + \l{examples-threadandconcurrent.html}{QtConcurrent Map} is a very short and + clear example about how a container of images can be scaled on all available + cores. The image scaling example uses the blocking variants of the functions + used. For every blocking function there is also a non-blocking, asynchronous + counterpart. Getting results asynchronously is implemented with QFuture and + QFutureWatcher. + + \section2 Example 3: Clock + + \image thread_clock.png "clock" + + We want to produce a clock application. The application has a GUI and a + worker thread. The worker thread checks every 10 milliseconds what time it + is. If the formatted time has changed, the result will be sent to the GUI + thread where it is displayed. + + Of course, this is an overly complicated way of designing a clock and, + actually, a separate thread is unnecessary. We would be better off placing + the timer in the main thread because the calculation made in the timer slot + is very short-lived. This example is purely for instructional use and shows + how to communicate from a worker thread to a GUI thread. Note that + communication in this direction is easy. We only need to add a signal + to QThread and make a queued signal/slot connection to the main thread. + Communication from the GUI to the worker thread is shown in the next + example. + + \snippet examples/tutorials/threads/clock/main.cpp 1 + + We've connected the \c clockThread with the label. The connection must be a + queued signal-slot connection because we want to put the call in the event + loop. + + \snippet examples/tutorials/threads/clock/clockthread.h 1 + + We have derived a class from QThread and declared the \c sendTime() signal. + + \snippet examples/tutorials/threads/clock/clockthread.cpp 1 + + The trickiest part of this example is that the timer is connected to its + slot via a direct connection. A default connection would produce a queued + signal-slot connection because the connected objects live in different + threads; remember that QThread does not live in the thread it creates. + + Still it is safe to access ClockThread::timerHit() from the worker thread + because ClockThread::timerHit() is private and only touches local variables + and a private member that isn't touched by public methods. + QDateTime::currentDateTime() isn't marked as thread-safe in Qt + documentation, however we can get away with using it in this small + example because we know that the QDateTime::currentDateTime() static + method isn't used in any other threads. + + \section2 Example 4: A Permanent Thread + + This example shows how it is possible to have a QObject in a worker thread + that accepts requests from the GUI thread, does polling using a timer and + continuously reports results back to the GUI thread. The actual work + including the polling must be implemented in a class derived from QObject. + We have called this class \c WorkerObject in the code shown below. The + thread-specific code is hidden in a class called \c Thread, derived from + QThread. + \c Thread has two additional public members. The \c launchWorker() member + takes the worker object and moves it to another thread with a started event + loop. + The call blocks for a very short moment until the thread creation operation + is completed, allowing the worker object to be used again on the next line. + The \c Thread class's code is short but somewhat involved, so we only show + how to use the class. + + \snippet examples/tutorials/threads/movedobject/main.cpp 1 + + QMetaObject::invokeMethod() calls a slot via the event loop. The worker + object's methods should not be called directly after the object has been + moved to another thread. We let the worker thread do some work and polling, + and use a timer to shut the application down after 3 seconds. Shutting the + worker down needs some care. We call \c{Thread::stop()} to exit the event + loop. We wait for the thread to terminate and, after this has occurred, we + delete the worker. + + \section1 Digging Deeper + + Threading is a very complicated subject. Qt offers more classes for + threading than we have presented in this tutorial. The following materials + 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 + from the \l{Training Day at Qt Developer Days 2009}. + \o The \l{Thread Support in Qt} document is a good starting point into + the reference documentation. + \o 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 + extensive coverage can be found in \e{Advanced Qt Programming} by Mark + Summerfield, Prentice Hall - roughly 70 of 500 pages cover QThread and + QtConcurrent. + \endlist +*/ |