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 */