<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en_US" lang="en_US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- exceptionsafety.qdoc -->
<title>Qt 4.8: Exception Safety</title>
<link rel="stylesheet" type="text/css" href="style/style.css" />
<script src="scripts/jquery.js" type="text/javascript"></script>
<script src="scripts/functions.js" type="text/javascript"></script>
<link rel="stylesheet" type="text/css" href="style/superfish.css" />
<link rel="stylesheet" type="text/css" href="style/narrow.css" />
<!--[if IE]>
<meta name="MSSmartTagsPreventParsing" content="true">
<meta http-equiv="imagetoolbar" content="no">
<![endif]-->
<!--[if lt IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie6.css">
<![endif]-->
<!--[if IE 7]>
<link rel="stylesheet" type="text/css" href="style/style_ie7.css">
<![endif]-->
<!--[if IE 8]>
<link rel="stylesheet" type="text/css" href="style/style_ie8.css">
<![endif]-->
<script src="scripts/superfish.js" type="text/javascript"></script>
<script src="scripts/narrow.js" type="text/javascript"></script>
</head>
<body class="" onload="CheckEmptyAndLoadList();">
<div class="header" id="qtdocheader">
<div class="content">
<div id="nav-logo">
<a href="index.html">Home</a></div>
<a href="index.html" class="qtref"><span>Qt Reference Documentation</span></a>
<div id="narrowsearch"></div>
<div id="nav-topright">
<ul>
<li class="nav-topright-home"><a href="http://qt.digia.com/">Qt HOME</a></li>
<li class="nav-topright-dev"><a href="http://qt-project.org/">DEV</a></li>
<li class="nav-topright-doc nav-topright-doc-active"><a href="http://qt-project.org/doc/">
DOC</a></li>
<li class="nav-topright-blog"><a href="http://blog.qt.digia.com/">BLOG</a></li>
</ul>
</div>
<div id="shortCut">
<ul>
<li class="shortCut-topleft-inactive"><span><a href="index.html">Qt 4.8</a></span></li>
<li class="shortCut-topleft-active"><a href="http://qt-project.org/doc/">ALL VERSIONS </a></li>
</ul>
</div>
<ul class="sf-menu" id="narrowmenu">
<li><a href="#">API Lookup</a>
<ul>
<li><a href="classes.html">Class index</a></li>
<li><a href="functions.html">Function index</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="namespaces.html">Namespaces</a></li>
<li><a href="qtglobal.html">Global Declarations</a></li>
<li><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</li>
<li><a href="#">Qt Topics</a>
<ul>
<li><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li><a href="supported-platforms.html">Supported Platforms</a></li>
<li><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</li>
<li><a href="#">Examples</a>
<ul>
<li><a href="all-examples.html">Examples</a></li>
<li><a href="tutorials.html">Tutorials</a></li>
<li><a href="demos.html">Demos</a></li>
<li><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</li>
</ul>
</div>
</div>
<div class="wrapper">
<div class="hd">
<span></span>
</div>
<div class="bd group">
<div class="sidebar">
<div class="searchlabel">
Search index:</div>
<div class="search" id="sidebarsearch">
<form id="qtdocsearch" action="" onsubmit="return false;">
<fieldset>
<input type="text" name="searchstring" id="pageType" value="" />
<div id="resultdialog">
<a href="#" id="resultclose">Close</a>
<p id="resultlinks" class="all"><a href="#" id="showallresults">All</a> | <a href="#" id="showapiresults">API</a> | <a href="#" id="showarticleresults">Articles</a> | <a href="#" id="showexampleresults">Examples</a></p>
<p id="searchcount" class="all"><span id="resultcount"></span><span id="apicount"></span><span id="articlecount"></span><span id="examplecount"></span> results:</p>
<ul id="resultlist" class="all">
</ul>
</div>
</fieldset>
</form>
</div>
<div class="box first bottombar" id="lookup">
<h2 title="API Lookup"><span></span>
API Lookup</h2>
<div id="list001" class="list">
<ul id="ul001" >
<li class="defaultLink"><a href="classes.html">Class index</a></li>
<li class="defaultLink"><a href="functions.html">Function index</a></li>
<li class="defaultLink"><a href="modules.html">Modules</a></li>
<li class="defaultLink"><a href="namespaces.html">Namespaces</a></li>
<li class="defaultLink"><a href="qtglobal.html">Global Declarations</a></li>
<li class="defaultLink"><a href="qdeclarativeelements.html">QML elements</a></li>
</ul>
</div>
</div>
<div class="box bottombar" id="topics">
<h2 title="Qt Topics"><span></span>
Qt Topics</h2>
<div id="list002" class="list">
<ul id="ul002" >
<li class="defaultLink"><a href="qt-basic-concepts.html">Programming with Qt</a></li>
<li class="defaultLink"><a href="qtquick.html">Device UIs & Qt Quick</a></li>
<li class="defaultLink"><a href="qt-gui-concepts.html">UI Design with Qt</a></li>
<li class="defaultLink"><a href="supported-platforms.html">Supported Platforms</a></li>
<li class="defaultLink"><a href="technology-apis.html">Qt and Key Technologies</a></li>
<li class="defaultLink"><a href="best-practices.html">How-To's and Best Practices</a></li>
</ul>
</div>
</div>
<div class="box" id="examples">
<h2 title="Examples"><span></span>
Examples</h2>
<div id="list003" class="list">
<ul id="ul003">
<li class="defaultLink"><a href="all-examples.html">Examples</a></li>
<li class="defaultLink"><a href="tutorials.html">Tutorials</a></li>
<li class="defaultLink"><a href="demos.html">Demos</a></li>
<li class="defaultLink"><a href="qdeclarativeexamples.html">QML Examples</a></li>
</ul>
</div>
</div>
</div>
<div class="wrap">
<div class="toolbar">
<div class="breadcrumb toolblock">
<ul>
<li class="first"><a href="index.html">Home</a></li>
<!-- Breadcrumbs go here -->
<li>Exception Safety</li>
</ul>
</div>
<div class="toolbuttons toolblock">
<ul>
<li id="smallA" class="t_button">A</li>
<li id="medA" class="t_button active">A</li>
<li id="bigA" class="t_button">A</li>
<li id="print" class="t_button"><a href="javascript:this.print();">
<span>Print</span></a></li>
</ul>
</div>
</div>
<div class="content mainContent">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#exception-safe-modules">Exception safe modules</a></li>
<li class="level2"><a href="#containers">Containers</a></li>
<li class="level1"><a href="#out-of-memory-handling">Out of Memory Handling</a></li>
<li class="level1"><a href="#recovering-from-exceptions">Recovering from exceptions</a></li>
<li class="level1"><a href="#platform-specific-exception-handling">Platform-Specific Exception Handling</a></li>
<li class="level2"><a href="#the-symbian-platform">The Symbian platform</a></li>
</ul>
</div>
<h1 class="title">Exception Safety</h1>
<span class="subtitle"></span>
<!-- $$$exceptionsafety.html-description -->
<div class="descr"> <a name="details"></a>
<p><b>Preliminary warning</b>: Exception safety is not feature complete! Common cases should work, but classes might still leak or even crash.</p>
<p>Qt itself will not throw exceptions. Instead, error codes are used. In addition, some classes have user visible error messages, for example <a href="qiodevice.html#errorString">QIODevice::errorString</a>() or <a href="qsqlquery.html#lastError">QSqlQuery::lastError</a>(). This has historical and practical reasons - turning on exceptions can increase the library size by over 20%.</p>
<p>The following sections describe Qt's behavior if exception support is enabled at compile time.</p>
<a name="exception-safe-modules"></a>
<h2>Exception safe modules</h2>
<a name="containers"></a>
<h3>Containers</h3>
<p>Qt's <a href="containers.html">container classes</a> are generally exception neutral. They pass any exception that happens within their contained type <tt>T</tt> to the user while keeping their internal state valid.</p>
<p>Example:</p>
<pre class="cpp"> <span class="type"><a href="qlist.html">QList</a></span><span class="operator"><</span><span class="type"><a href="qstring.html">QString</a></span><span class="operator">></span> list;
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="keyword">try</span> {
list<span class="operator">.</span>append(<span class="string">"hello"</span>);
} <span class="keyword">catch</span> (<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>) {
}
<span class="comment">// list is safe to use - the exception did not affect it.</span></pre>
<p>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:</p>
<pre class="cpp"> MyType s <span class="operator">=</span> list<span class="operator">.</span>takeAt(<span class="number">2</span>);</pre>
<p>If an exception occurs during the assignment of <tt>s</tt>, the value at index 2 is already removed from the container, but hasn't been assigned to <tt>s</tt> yet. It is lost without chance of recovery.</p>
<p>The correct way to write it:</p>
<pre class="cpp"> MyType s <span class="operator">=</span> list<span class="operator">.</span>at(<span class="number">2</span>);
list<span class="operator">.</span>removeAt(<span class="number">2</span>);</pre>
<p>If the assignment throws, the container still contains the value, no data loss occured.</p>
<p>Note that implicitly shared Qt classes will not throw in their assignment operators or copy constructors, so the limitation above does not apply.</p>
<a name="out-of-memory-handling"></a>
<h2>Out of Memory Handling</h2>
<p>Most desktop operating systems overcommit memory. This means that <tt>malloc()</tt> or <tt>operator new</tt> return a valid pointer, even though there is not enough memory available at allocation time. On such systems, no exception of type <tt>std::bad_alloc</tt> is thrown.</p>
<p>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.</p>
<p>Exceptions to that rule are documented. As an example, <a href="qimage.html">QImage</a> constructors will create a <a href="qimage.html#isNull">null</a> image if not enough memory exists instead of throwing an exception.</p>
<a name="recovering-from-exceptions"></a>
<h2>Recovering from exceptions</h2>
<p>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.</p>
<p>Typical use case:</p>
<pre class="cpp"> <span class="type"><a href="qapplication.html">QApplication</a></span> app(argc<span class="operator">,</span> argv);
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="keyword">try</span> {
app<span class="operator">.</span>exec();
} <span class="keyword">catch</span> (<span class="keyword">const</span> std<span class="operator">::</span>bad_alloc <span class="operator">&</span>) {
<span class="comment">// clean up here, e.g. save the session</span>
<span class="comment">// and close all config files.</span>
<span class="keyword">return</span> <span class="number">0</span>; <span class="comment">// exit the application</span>
}</pre>
<p>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.</p>
<a name="platform-specific-exception-handling"></a>
<h2>Platform-Specific Exception Handling</h2>
<a name="the-symbian-platform"></a>
<h3>The Symbian platform</h3>
<p>The Symbian platform implements its own exception system that differs from the standard C++ mechanism. When using Qt for the Symbian platform, 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.</p>
<p>The <a href="symbianexceptionsafety.html">Exception Safety with Symbian</a> document shows how to use the facilities provided by Qt to use exceptions as safely as possible.</p>
</div>
<!-- @@@exceptionsafety.html -->
</div>
</div>
</div>
<div class="ft">
<span></span>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.</p>
<br />
<p>
The documentation provided herein is licensed under the terms of the
<a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation
License version 1.3</a> as published by the Free Software Foundation.</p>
<p>
Documentation sources may be obtained from <a href="http://www.qt-project.org">
www.qt-project.org</a>.</p>
<br />
<p>
Qt and respective logos are trademarks of The Qt Company Ltd
in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. <a title="Privacy Policy"
href="http://en.gitorious.org/privacy_policy/">Privacy Policy</a></p>
</div>
<script src="scripts/functions.js" type="text/javascript"></script>
</body>
</html>
