Update copyright headers
[qt:qt.git] / doc / src / howtos / exceptionsafety.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \page exceptionsafety.html
30     \title Exception Safety
31     \ingroup best-practices
32     \brief A guide to exception safety in Qt.
33
34     \bold {Preliminary warning}: Exception safety is not feature complete!
35     Common cases should work, but classes might still leak or even crash.
36
37     Qt itself will not throw exceptions. Instead, error codes are used.
38     In addition, some classes have user visible error messages, for example
39     \l QIODevice::errorString() or \l QSqlQuery::lastError().
40     This has historical and practical reasons - turning on exceptions
41     can increase the library size by over 20%.
42
43     The following sections describe Qt's behavior if exception support is
44     enabled at compile time.
45
46     \tableofcontents
47
48     \section1 Exception safe modules
49
50     \section2 Containers
51     
52     Qt's \l{container classes} are generally exception neutral. They pass any
53     exception that happens within their contained type \c T to the user
54     while keeping their internal state valid.
55
56     Example:
57
58     \code
59     QList<QString> list;
60     ...
61     try {
62         list.append("hello");
63     } catch (...) {
64     }
65     // list is safe to use - the exception did not affect it.
66     \endcode
67
68     Exceptions to that rule are containers for types that can throw during assignment
69     or copy constructions. For those types, functions that modify the container as well as
70     returning a value, are unsafe to use:
71
72     \code
73     MyType s = list.takeAt(2);
74     \endcode
75
76     If an exception occurs during the assignment of \c s, the value at index 2 is already
77     removed from the container, but hasn't been assigned to \c s yet. It is lost
78     without chance of recovery.
79
80     The correct way to write it:
81
82     \code
83     MyType s = list.at(2);
84     list.removeAt(2);
85     \endcode
86
87     If the assignment throws, the container still contains the value, no data loss occured.
88
89     Note that implicitly shared Qt classes will not throw in their assignment
90     operators or copy constructors, so the limitation above does not apply.
91
92     \section1 Out of Memory Handling
93
94     Most desktop operating systems overcommit memory. This means that \c malloc()
95     or \c{operator new} return a valid pointer, even though there is not enough
96     memory available at allocation time. On such systems, no exception of type
97     \c std::bad_alloc is thrown.
98
99     On all other operating systems, Qt will throw an exception of type std::bad_alloc
100     if any allocation fails. Allocations can fail if the system runs out of memory or
101     doesn't have enough continuous memory to allocate the requested size.
102
103     Exceptions to that rule are documented. As an example, QImage constructors will
104     create a \l{QImage::isNull()}{null} image if not enough memory exists instead
105     of throwing an exception.
106
107     \section1 Recovering from exceptions
108
109     Currently, the only supported use case for recovering from exceptions thrown
110     within Qt (for example due to out of memory) is to exit the event loop and do 
111     some cleanup before exiting the application.
112
113     Typical use case:
114
115     \code
116     QApplication app(argc, argv);
117     ...
118     try {
119         app.exec();
120     } catch (const std::bad_alloc &) {
121         // clean up here, e.g. save the session
122         // and close all config files.
123
124         return 0; // exit the application
125     }
126     \endcode
127
128     After an exception is thrown, the connection to the windowing server
129     might already be closed. It is not safe to call a GUI related function
130     after catching an exception.
131
132     \section1 Platform-Specific Exception Handling
133
134     \section2 The Symbian platform
135
136     The Symbian platform implements its own exception system that differs from the standard
137     C++ mechanism. When using Qt for the Symbian platform, and especially when writing code to 
138     access Symbian functionality directly, it may be necessary to know about the underlying 
139     implementation and how it interacts with Qt.
140
141     The \l{Exception Safety with Symbian} document shows how to use the facilities provided
142     by Qt to use exceptions as safely as possible.
143 */