summaryrefslogtreecommitdiffstats
path: root/doc/src/exceptionsafety.qdoc
diff options
context:
space:
mode:
authorVolker Hilsheimer <volker.hilsheimer@nokia.com>2009-10-02 16:04:21 (GMT)
committerVolker Hilsheimer <volker.hilsheimer@nokia.com>2009-10-05 11:41:42 (GMT)
commit491a9879d349a67dbd5f00f1c0bb189fb92290e3 (patch)
tree24fe0d2a09b5b9060cc2e3bbc9b2d9195e86dfc2 /doc/src/exceptionsafety.qdoc
parentc5a8d26d2337c3ed01f66783b69c5090c515be38 (diff)
downloadQt-491a9879d349a67dbd5f00f1c0bb189fb92290e3.zip
Qt-491a9879d349a67dbd5f00f1c0bb189fb92290e3.tar.gz
Qt-491a9879d349a67dbd5f00f1c0bb189fb92290e3.tar.bz2
Doc: move new files into correct subdirectory.
Diffstat (limited to 'doc/src/exceptionsafety.qdoc')
-rw-r--r--doc/src/exceptionsafety.qdoc156
1 files changed, 0 insertions, 156 deletions
diff --git a/doc/src/exceptionsafety.qdoc b/doc/src/exceptionsafety.qdoc
deleted file mode 100644
index b70df6b..0000000
--- a/doc/src/exceptionsafety.qdoc
+++ /dev/null
@@ -1,156 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2009 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:LGPL$
-** No Commercial Usage
-** This file contains pre-release code and may not be distributed.
-** You may use this file in accordance with the terms and conditions
-** contained in the Technology Preview License Agreement accompanying
-** this package.
-**
-** GNU Lesser General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU Lesser
-** General Public License version 2.1 as published by the Free Software
-** Foundation and appearing in the file LICENSE.LGPL included in the
-** packaging of this file. Please review the following information to
-** ensure the GNU Lesser General Public License version 2.1 requirements
-** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
-**
-** In addition, as a special exception, Nokia gives you certain additional
-** rights. These rights are described in the Nokia Qt LGPL Exception
-** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
-**
-** If you have questions regarding the use of this file, please contact
-** Nokia at qt-info@nokia.com.
-**
-**
-**
-**
-**
-**
-**
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \page exceptionsafety.html
- \title Exception Safety
- \ingroup architecture
- \brief A guide to exception safety in Qt.
-
- \bold {Preliminary warning}: Exception safety is not feature complete!
- Common cases should work, but classes might still leak or even crash.
-
- Qt itself will not throw exceptions. Instead, error codes are used.
- In addition, some classes have user visible error messages, for example
- \l QIODevice::errorString() or \l QSqlQuery::lastError().
- This has historical and practical reasons - turning on exceptions
- can increase the library size by over 20%.
-
- The following sections describe Qt's behavior if exception support is
- enabled at compile time.
-
- \tableofcontents
-
- \section1 Exception safe modules
-
- \section2 Containers
-
- Qt's \l{container classes} are generally exception neutral. They pass any
- exception that happens within their contained type \c T to the user
- while keeping their internal state valid.
-
- Example:
-
- \code
- QList<QString> list;
- ...
- try {
- list.append("hello");
- } catch (...) {
- }
- // list is safe to use - the exception did not affect it.
- \endcode
-
- Exceptions to that rule are containers for types that can throw during assignment
- or copy constructions. For those types, functions that modify the container as well as
- returning a value, are unsafe to use:
-
- \code
- MyType s = list.takeAt(2);
- \endcode
-
- If an exception occurs during the assignment of \c s, the value at index 2 is already
- removed from the container, but hasn't been assigned to \c s yet. It is lost
- without chance of recovery.
-
- The correct way to write it:
-
- \code
- MyType s = list.at(2);
- list.removeAt(2);
- \endcode
-
- If the assignment throws, the container still contains the value, no data loss occured.
-
- Note that implicitly shared Qt classes will not throw in their assignment
- operators or copy constructors, so the limitation above does not apply.
-
- \section1 Out of Memory Handling
-
- Most desktop operating systems overcommit memory. This means that \c malloc()
- or \c{operator new} return a valid pointer, even though there is not enough
- memory available at allocation time. On such systems, no exception of type
- \c std::bad_alloc is thrown.
-
- On all other operating systems, Qt will throw an exception of type std::bad_alloc
- if any allocation fails. Allocations can fail if the system runs out of memory or
- doesn't have enough continuous memory to allocate the requested size.
-
- Exceptions to that rule are documented. As an example, \l QImage::create()
- returns false if not enough memory exists instead of throwing an exception.
-
- \section1 Recovering from exceptions
-
- Currently, the only supported use case for recovering from exceptions thrown
- within Qt (for example due to out of memory) is to exit the event loop and do
- some cleanup before exiting the application.
-
- Typical use case:
-
- \code
- QApplication app(argc, argv);
- ...
- try {
- app.exec();
- } catch (const std::bad_alloc &) {
- // clean up here, e.g. save the session
- // and close all config files.
-
- return 0; // exit the application
- }
- \endcode
-
- After an exception is thrown, the connection to the windowing server
- might already be closed. It is not safe to call a GUI related function
- after catching an exception.
-
- \section1 Platform-Specific Exception Handling
-
- \section2 Symbian (Qt for S60)
-
- The Symbian platform implements its own exception system that differs from the standard
- C++ mechanism. When using Qt for S60, and especially when writing code to access Symbian
- functionality directly, it may be necessary to know about the underlying implementation
- and how it interacts with Qt.
-
- The \l{Exception Safety with Symbian} document shows how to use the facilities provided
- by Qt to use exceptions as safely as possible.
-*/