1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Exception Safety Guarantees</title> 5<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../../index.html" title="Boost.Optional"> 8<link rel="up" href="../../optional/tutorial.html" title="Tutorial"> 9<link rel="prev" href="gotchas/false_positive_with__wmaybe_uninitialized.html" title="False positive with -Wmaybe-uninitialized"> 10<link rel="next" href="type_requirements.html" title="Type requirements"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="gotchas/false_positive_with__wmaybe_uninitialized.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="type_requirements.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h3 class="title"> 27<a name="boost_optional.tutorial.exception_safety_guarantees"></a><a class="link" href="exception_safety_guarantees.html" title="Exception Safety Guarantees">Exception 28 Safety Guarantees</a> 29</h3></div></div></div> 30<p> 31 This library assumes that <code class="computeroutput"><span class="identifier">T</span></code>'s 32 destructor does not throw exceptions. If it does, the behaviour of many operations 33 on <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> is 34 undefined. 35 </p> 36<p> 37 The following mutating operations never throw exceptions: 38 </p> 39<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 40<li class="listitem"> 41 <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="keyword">operator</span><span class="special">=</span> <span class="special">(</span> <span class="identifier">none_t</span> 42 <span class="special">)</span> <span class="keyword">noexcept</span></code> 43 </li> 44<li class="listitem"> 45 <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">reset</span><span class="special">()</span> <span class="keyword">noexcept</span></code> 46 </li> 47</ul></div> 48<p> 49 In addition, the following constructors and the destructor never throw exceptions: 50 </p> 51<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 52<li class="listitem"> 53 <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">optional</span><span class="special">()</span> 54 <span class="keyword">noexcept</span></code> 55 </li> 56<li class="listitem"> 57 <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">optional</span><span class="special">(</span> 58 <span class="identifier">none_t</span> <span class="special">)</span> 59 <span class="keyword">noexcept</span></code> 60 </li> 61</ul></div> 62<p> 63 Regarding the following assignment functions: 64 </p> 65<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 66<li class="listitem"> 67 <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="keyword">operator</span><span class="special">=</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="special">)</span></code> 68 </li> 69<li class="listitem"> 70 <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="keyword">operator</span><span class="special">=</span> <span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="special">)</span></code> 71 </li> 72<li class="listitem"> 73 <code class="computeroutput"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">U</span><span class="special">></span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="keyword">operator</span><span class="special">=</span> <span class="special">(</span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">U</span><span class="special">></span> <span class="keyword">const</span><span class="special">&</span> <span class="special">)</span></code> 74 </li> 75<li class="listitem"> 76 <code class="computeroutput"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">InPlaceFactory</span><span class="special">></span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="keyword">operator</span><span class="special">=</span> <span class="special">(</span> <span class="identifier">InPlaceFactory</span> 77 <span class="keyword">const</span><span class="special">&</span> 78 <span class="special">)</span></code> 79 </li> 80<li class="listitem"> 81 <code class="computeroutput"><span class="keyword">template</span><span class="special"><</span><span class="keyword">class</span> <span class="identifier">TypedInPlaceFactory</span><span class="special">></span> <span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="keyword">operator</span><span class="special">=</span> <span class="special">(</span> <span class="identifier">TypedInPlaceFactory</span> 82 <span class="keyword">const</span><span class="special">&</span> 83 <span class="special">)</span> </code> 84 </li> 85<li class="listitem"> 86 <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">reset</span><span class="special">(</span> <span class="identifier">T</span> <span class="keyword">const</span><span class="special">&</span> <span class="special">)</span></code> 87 </li> 88</ul></div> 89<p> 90 They forward calls to the corresponding <code class="computeroutput"><span class="identifier">T</span></code>'s 91 constructors or assignments (depending on whether the optional object is 92 initialized or not); so if both <code class="computeroutput"><span class="identifier">T</span></code>'s 93 constructor and the assignment provide strong exception safety guarantee, 94 <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code>'s 95 assignment also provides strong exception safety guarantee; otherwise we 96 only get the basic guarantee. Additionally, if both involved <code class="computeroutput"><span class="identifier">T</span></code>'s constructor and the assignment never 97 throw, <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code>'s 98 assignment also never throws. 99 </p> 100<p> 101 Unless <code class="computeroutput"><span class="identifier">T</span></code>'s constructor or 102 assignment throws, assignments to <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> 103 do not throw anything else on its own. A throw during assignment never changes 104 the initialization state of any optional object involved: 105 </p> 106<pre class="programlisting"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="identifier">opt1</span><span class="special">(</span><span class="identifier">val1</span><span class="special">);</span> 107<span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span> <span class="identifier">opt2</span><span class="special">(</span><span class="identifier">val2</span><span class="special">);</span> 108<span class="identifier">assert</span><span class="special">(</span><span class="identifier">opt1</span><span class="special">);</span> 109<span class="identifier">assert</span><span class="special">(</span><span class="identifier">opt2</span><span class="special">);</span> 110 111<span class="keyword">try</span> 112<span class="special">{</span> 113 <span class="identifier">opt1</span> <span class="special">=</span> <span class="identifier">opt2</span><span class="special">;</span> <span class="comment">// throws</span> 114<span class="special">}</span> 115<span class="keyword">catch</span><span class="special">(...)</span> 116<span class="special">{</span> 117 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">opt1</span><span class="special">);</span> 118 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">opt2</span><span class="special">);</span> 119<span class="special">}</span> 120</pre> 121<p> 122 This also applies to move assignments/constructors. However, move operations 123 are made no-throw more often. 124 </p> 125<p> 126 Operation <code class="computeroutput"><span class="identifier">emplace</span></code> provides 127 basic exception safety guarantee. If it throws, the optional object becomes 128 uninitialized regardless of its initial state, and its previous contained 129 value (if any) is destroyed. It doesn't call any assignment or move/copy 130 constructor on <code class="computeroutput"><span class="identifier">T</span></code>. 131 </p> 132<h5> 133<a name="boost_optional.tutorial.exception_safety_guarantees.h0"></a> 134 <span class="phrase"><a name="boost_optional.tutorial.exception_safety_guarantees.swap"></a></span><a class="link" href="exception_safety_guarantees.html#boost_optional.tutorial.exception_safety_guarantees.swap">Swap</a> 135 </h5> 136<p> 137 Unless <code class="computeroutput"><span class="identifier">swap</span></code> on optional is 138 customized, its primary implementation forwards calls to <code class="computeroutput"><span class="identifier">T</span></code>'s 139 <code class="computeroutput"><span class="identifier">swap</span></code> or move constructor 140 (depending on the initialization state of the optional objects). Thus, if 141 both <code class="computeroutput"><span class="identifier">T</span></code>'s <code class="computeroutput"><span class="identifier">swap</span></code> 142 and move constructor never throw, <code class="computeroutput"><span class="identifier">swap</span></code> 143 on <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> never 144 throws. similarly, if both <code class="computeroutput"><span class="identifier">T</span></code>'s 145 <code class="computeroutput"><span class="identifier">swap</span></code> and move constructor 146 offer strong guarantee, <code class="computeroutput"><span class="identifier">swap</span></code> 147 on <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> also 148 offers a strong guarantee. 149 </p> 150<p> 151 In case <code class="computeroutput"><span class="identifier">swap</span></code> on optional 152 is customized, the call to <code class="computeroutput"><span class="identifier">T</span></code>'s 153 move constructor are replaced with the calls to <code class="computeroutput"><span class="identifier">T</span></code>'s 154 default constructor followed by <code class="computeroutput"><span class="identifier">swap</span></code>. 155 (This is more useful on older compilers that do not support move semantics, 156 when one wants to acheive stronger exception safety guarantees.) In this 157 case the exception safety guarantees for <code class="computeroutput"><span class="identifier">swap</span></code> 158 are reliant on the guarantees of <code class="computeroutput"><span class="identifier">T</span></code>'s 159 <code class="computeroutput"><span class="identifier">swap</span></code> and default constructor 160 </p> 161</div> 162<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 163<td align="left"></td> 164<td align="right"><div class="copyright-footer">Copyright © 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright © 2014-2018 Andrzej Krzemieński<p> 165 Distributed under the Boost Software License, Version 1.0. (See accompanying 166 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 167 </p> 168</div></td> 169</tr></table> 170<hr> 171<div class="spirit-nav"> 172<a accesskey="p" href="gotchas/false_positive_with__wmaybe_uninitialized.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../../optional/tutorial.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="type_requirements.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 173</div> 174</body> 175</html> 176
