1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \page exceptionsafety.html

    44     \title Exception Safety

    45     \ingroup best-practices

    46     \brief A guide to exception safety in Qt.

    47 

    48     \bold {Preliminary warning}: Exception safety is not feature complete!

    49     Common cases should work, but classes might still leak or even crash.

    50 

    51     Qt itself will not throw exceptions. Instead, error codes are used.

    52     In addition, some classes have user visible error messages, for example

    53     \l QIODevice::errorString() or \l QSqlQuery::lastError().

    54     This has historical and practical reasons - turning on exceptions

    55     can increase the library size by over 20%.

    56 

    57     The following sections describe Qt's behavior if exception support is

    58     enabled at compile time.

    59 

    60     \tableofcontents

    61 

    62     \section1 Exception safe modules

    63 

    64     \section2 Containers

    65     

    66     Qt's \l{container classes} are generally exception neutral. They pass any

    67     exception that happens within their contained type \c T to the user

    68     while keeping their internal state valid.

    69 

    70     Example:

    71 

    72     \code

    73     QList<QString> list;

    74     ...

    75     try {

    76         list.append("hello");

    77     } catch (...) {

    78     }

    79     // list is safe to use - the exception did not affect it.

    80     \endcode

    81 

    82     Exceptions to that rule are containers for types that can throw during assignment

    83     or copy constructions. For those types, functions that modify the container as well as

    84     returning a value, are unsafe to use:

    85 

    86     \code

    87     MyType s = list.takeAt(2);

    88     \endcode

    89 

    90     If an exception occurs during the assignment of \c s, the value at index 2 is already

    91     removed from the container, but hasn't been assigned to \c s yet. It is lost

    92     without chance of recovery.

    93 

    94     The correct way to write it:

    95 

    96     \code

    97     MyType s = list.at(2);

    98     list.removeAt(2);

    99     \endcode

   100 

   101     If the assignment throws, the container still contains the value, no data loss occured.

   102 

   103     Note that implicitly shared Qt classes will not throw in their assignment

   104     operators or copy constructors, so the limitation above does not apply.

   105 

   106     \section1 Out of Memory Handling

   107 

   108     Most desktop operating systems overcommit memory. This means that \c malloc()

   109     or \c{operator new} return a valid pointer, even though there is not enough

   110     memory available at allocation time. On such systems, no exception of type

   111     \c std::bad_alloc is thrown.

   112 

   113     On all other operating systems, Qt will throw an exception of type std::bad_alloc

   114     if any allocation fails. Allocations can fail if the system runs out of memory or

   115     doesn't have enough continuous memory to allocate the requested size.

   116 

   117     Exceptions to that rule are documented. As an example, \l QImage::create()

   118     returns false if not enough memory exists instead of throwing an exception.

   119 

   120     \section1 Recovering from exceptions

   121 

   122     Currently, the only supported use case for recovering from exceptions thrown

   123     within Qt (for example due to out of memory) is to exit the event loop and do 

   124     some cleanup before exiting the application.

   125 

   126     Typical use case:

   127 

   128     \code

   129     QApplication app(argc, argv);

   130     ...

   131     try {

   132         app.exec();

   133     } catch (const std::bad_alloc &) {

   134         // clean up here, e.g. save the session

   135         // and close all config files.

   136 

   137         return 0; // exit the application

   138     }

   139     \endcode

   140 

   141     After an exception is thrown, the connection to the windowing server

   142     might already be closed. It is not safe to call a GUI related function

   143     after catching an exception.

   144 

   145     \section1 Platform-Specific Exception Handling

   146 

   147     \section2 The Symbian platform

   148 

   149     The Symbian platform implements its own exception system that differs from the standard

   150     C++ mechanism. When using Qt for Symbian platform, and especially when writing code to 

   151     access Symbian functionality directly, it may be necessary to know about the underlying 

   152     implementation and how it interacts with Qt.

   153 

   154     The \l{Exception Safety with Symbian} document shows how to use the facilities provided

   155     by Qt to use exceptions as safely as possible.

   156 */