1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 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.78.1"> 7<link rel="home" href="../index.html" title="Chapter 1. Boost.Optional"> 8<link rel="up" href="../index.html" title="Chapter 1. Boost.Optional"> 9<link rel="prev" href="a_note_about_optional_bool_.html" title="A note about optional<bool>"> 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="a_note_about_optional_bool_.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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><h2 class="title" style="clear: both"> 27<a name="boost_optional.exception_safety_guarantees"></a><a class="link" href="exception_safety_guarantees.html" title="Exception Safety Guarantees">Exception Safety 28 Guarantees</a> 29</h2></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> <span class="special">)</span> <span class="keyword">noexcept</span></code> 42 </li> 43<li class="listitem"> 44 <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> 45 </li> 46</ul></div> 47<p> 48 In addition, the following constructors and the destructor never throw exceptions: 49 </p> 50<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 51<li class="listitem"> 52 <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> 53 <span class="keyword">noexcept</span></code> 54 </li> 55<li class="listitem"> 56 <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> <span class="identifier">none_t</span> <span class="special">)</span> <span class="keyword">noexcept</span></code> 57 </li> 58</ul></div> 59<p> 60 Regarding the following assignment functions: 61 </p> 62<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 63<li class="listitem"> 64 <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> 65 </li> 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">T</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="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> 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">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> 74 <span class="keyword">const</span><span class="special">&</span> 75 <span class="special">)</span></code> 76 </li> 77<li class="listitem"> 78 <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> 79 <span class="keyword">const</span><span class="special">&</span> 80 <span class="special">)</span> </code> 81 </li> 82<li class="listitem"> 83 <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> 84 </li> 85</ul></div> 86<p> 87 They forward calls to the corresponding <code class="computeroutput"><span class="identifier">T</span></code>'s 88 constructors or assignments (depending on whether the optional object is initialized 89 or not); so if both <code class="computeroutput"><span class="identifier">T</span></code>'s constructor 90 and the assignment provide strong exception safety guarantee, <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code>'s assignment 91 also provides strong exception safety guarantee; otherwise we only get the 92 basic guarantee. Additionally, if both involved <code class="computeroutput"><span class="identifier">T</span></code>'s 93 constructor and the assignment never throw, <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code>'s 94 assignment also never throws. 95 </p> 96<p> 97 Unless <code class="computeroutput"><span class="identifier">T</span></code>'s constructor or assignment 98 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> 99 do not throw anything else on its own. A throw during assignment never changes 100 the initialization state of any optional object involved: 101 </p> 102<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> 103<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> 104<span class="identifier">assert</span><span class="special">(</span><span class="identifier">opt1</span><span class="special">);</span> 105<span class="identifier">assert</span><span class="special">(</span><span class="identifier">opt2</span><span class="special">);</span> 106 107<span class="keyword">try</span> 108<span class="special">{</span> 109 <span class="identifier">opt1</span> <span class="special">=</span> <span class="identifier">opt2</span><span class="special">;</span> <span class="comment">// throws</span> 110<span class="special">}</span> 111<span class="keyword">catch</span><span class="special">(...)</span> 112<span class="special">{</span> 113 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">opt1</span><span class="special">);</span> 114 <span class="identifier">assert</span><span class="special">(</span><span class="identifier">opt2</span><span class="special">);</span> 115<span class="special">}</span> 116</pre> 117<p> 118 This also applies to move assignments/constructors. However, move operations 119 are made no-throw more often. 120 </p> 121<p> 122 Operation <code class="computeroutput"><span class="identifier">emplace</span></code> provides 123 basic exception safety guarantee. If it throws, the optional object becomes 124 uninitialized regardless of its initial state, and its previous contained value 125 (if any) is destroyed. It doesn't call any assignment or move/copy constructor 126 on <code class="computeroutput"><span class="identifier">T</span></code>. 127 </p> 128<h4> 129<a name="boost_optional.exception_safety_guarantees.h0"></a> 130 <span class="phrase"><a name="boost_optional.exception_safety_guarantees.swap"></a></span><a class="link" href="exception_safety_guarantees.html#boost_optional.exception_safety_guarantees.swap">Swap</a> 131 </h4> 132<p> 133 Unless <code class="computeroutput"><span class="identifier">swap</span></code> on optional is 134 customized, its primary implementation forwards calls to <code class="computeroutput"><span class="identifier">T</span></code>'s 135 <code class="computeroutput"><span class="identifier">swap</span></code> or move constructor (depending 136 on the initialization state of the optional objects). Thus, if both <code class="computeroutput"><span class="identifier">T</span></code>'s <code class="computeroutput"><span class="identifier">swap</span></code> 137 and move constructor never throw, <code class="computeroutput"><span class="identifier">swap</span></code> 138 on <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> never 139 throws. similarly, if both <code class="computeroutput"><span class="identifier">T</span></code>'s 140 <code class="computeroutput"><span class="identifier">swap</span></code> and move constructor offer 141 strong guarantee, <code class="computeroutput"><span class="identifier">swap</span></code> on 142 <code class="computeroutput"><span class="identifier">optional</span><span class="special"><</span><span class="identifier">T</span><span class="special">></span></code> also 143 offers a strong guarantee. 144 </p> 145<p> 146 In case <code class="computeroutput"><span class="identifier">swap</span></code> on optional is 147 customized, the call to <code class="computeroutput"><span class="identifier">T</span></code>'s 148 move constructor are replaced with the calls to <code class="computeroutput"><span class="identifier">T</span></code>'s 149 default constructor followed by <code class="computeroutput"><span class="identifier">swap</span></code>. 150 (This is more useful on older compilers that do not support move semantics, 151 when one wants to acheive stronger exception safety guarantees.) In this case 152 the exception safety guarantees for <code class="computeroutput"><span class="identifier">swap</span></code> 153 are reliant on the guarantees of <code class="computeroutput"><span class="identifier">T</span></code>'s 154 <code class="computeroutput"><span class="identifier">swap</span></code> and default constructor 155 </p> 156</div> 157<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 158<td align="left"></td> 159<td align="right"><div class="copyright-footer">Copyright © 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright © 2014 Andrzej Krzemieński<p> 160 Distributed under the Boost Software License, Version 1.0. (See accompanying 161 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>) 162 </p> 163</div></td> 164</tr></table> 165<hr> 166<div class="spirit-nav"> 167<a accesskey="p" href="a_note_about_optional_bool_.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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> 168</div> 169</body> 170</html> 171
