Added performance notes to documentation

doc/00_optional.qbk

@@ -85,6 +85,7 @@ This is how you solve it with `boost::optional`:
 [include 16_optional_bool.qbk]
 [include 17_exception_safety.qbk]
 [include 18_type_requirements.qbk]
+[include 19_on_performance.qbk]
 [endsect]
 [section Reference]
 [include 20_reference.qbk]

doc/19_on_performance.qbk

@@ -0,0 +1,131 @@
+
+[section Performance considerations]
+
+Technical details aside, the memory layout of `optional<T>` is more-less this:
+
+  template <typename T>
+  class optional
+  {
+    bool _initialized;
+    std::aligned_storage_t<sizeof(t), alignof(T)> _storage;
+  };
+  
+But for the purpose of this analysis, considering memory layouts, we can think of it as:
+
+  template <typename T>
+  class optional
+  {
+    bool _initialized;
+    T _storage;
+  };
+  
+Given type `optional<int>`, and assuming that `sizeof(int) == 4`, we will get `sizeof(optional<int>) == 8`. This is so because of the alignment rules, for our two members we get the following alignment:
+
+[$images/opt_align1.png]
+
+This means you can fit twice as many `int`s as `optional<int>`s into the same space of memory. Therefore, if the size of the objects is critical for your application (e.g., because you want to utilize your CPU cache in order to gain performance) and you have determined you are willing to trade the code clarity, it is recommended that you simply go with type `int` and use some 'magic value' to represent ['not-an-int].
+
+Even if you cannot spare any value of `int` to represent ['not-an-int] (e.g., because every value is useful, or you do want to signal ['not-an-int] explicitly), at least for `Trivial` types you should consider storing the value and the `bool` flag representing the ['null-state] separately. Consider the following class:
+
+  struct Record
+  {
+    optional<int> _min;
+    optional<int> _max;
+  };
+  
+Its memory layout can be depicted as follows:
+
+[$images/opt_align2.png]
+
+This is exactly the same as if we had the following members:
+
+  struct Record
+  {
+    bool _has_min;
+    int  _min;
+    bool _has_max;
+    int  _max;
+  };
+
+But when they are stored separately, we at least have an option to reorder them like this:
+
+  struct Record
+  {
+    bool _has_min;  
+    bool _has_max;
+    int  _min;
+    int  _max;
+  };
+
+Which gives us the following layout (and smaller total size):
+
+[$images/opt_align3.png]
+
+Sometimes it requires detailed consideration what data we make optional. In our case above, if we determine that both minimum and maximum value can be provided or not provided together, but one is never provided without the other, we can make only one optional memebr:
+
+  struct Limits
+  {
+    int  _min;
+    int  _max;
+  };
+  
+  struct Record
+  {
+    optional<Limits> _limits;  
+  };
+  
+This would give us the following layout:
+
+[$images/opt_align4.png]
+
+[heading Optional function parameters]
+
+Having function parameters of type `const optional<T>&` may incur certain unexpected run-time cost connected to copy construction of `T`. Consider the following code. 
+
+  void fun(const optional<Big>& v)
+  {
+    if (v) doSomethingWith(*v);
+    else   doSomethingElse();
+  }
+
+  int main()
+  {
+    optional<Big> ov;
+    Big v;
+    fun(none);
+    fun(ov); // no copy
+    fun(v);  // copy constructor of Big
+  }
+
+No copy elision or move semantics can save us from copying type `Big` here. Not that we need any copy, but this is how `optional` works. In order to avoid copying in this case, one could provide second overload of `fun`:
+
+  void fun(const Big& v)
+  {
+    doSomethingWith(v);
+  }
+
+  int main()
+  {
+    optional<Big> ov;
+    Big v;
+    fun(ov); // no copy
+    fun(v);  // no copy: second overload selected
+  }
+
+Alternatively, you could consider using an optional reference instead:
+
+  void fun(optional<const Big&> v) // note where the reference is
+  {
+    if (v) doSomethingWith(*v);
+    else   doSomethingElse();
+  }
+
+  int main()
+  {
+    optional<Big> ov;
+    Big v;
+    fun(none);
+    fun(ov); // doesn't compile
+    fun(v);  // no copy
+  }
+[endsect]

doc/html/boost_optional/tutorial/performance_considerations.html

@@ -0,0 +1,223 @@
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
+<title>Performance considerations</title>
+<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
+<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
+<link rel="home" href="../../index.html" title="Boost.Optional">
+<link rel="up" href="../../optional/tutorial.html" title="Tutorial">
+<link rel="prev" href="type_requirements.html" title="Type requirements">
+<link rel="next" href="../../optional/reference.html" title="Reference">
+</head>
+<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
+<table cellpadding="2" width="100%"><tr>
+<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
+<td align="center"><a href="../../../../../../index.html">Home</a></td>
+<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
+<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
+<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
+<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="type_requirements.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="../../optional/reference.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+<div class="section">
+<div class="titlepage"><div><div><h3 class="title">
+<a name="boost_optional.tutorial.performance_considerations"></a><a class="link" href="performance_considerations.html" title="Performance considerations">Performance
+      considerations</a>
+</h3></div></div></div>
+<p>
+        Technical details aside, the memory layout of <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;</span></code>
+        is more-less this:
+      </p>
+<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">optional</span>
+<span class="special">{</span>
+  <span class="keyword">bool</span> <span class="identifier">_initialized</span><span class="special">;</span>
+  <span class="identifier">std</span><span class="special">::</span><span class="identifier">aligned_storage_t</span><span class="special">&lt;</span><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">t</span><span class="special">),</span> <span class="keyword">alignof</span><span class="special">(</span><span class="identifier">T</span><span class="special">)&gt;</span> <span class="identifier">_storage</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+        But for the purpose of this analysis, considering memory layouts, we can
+        think of it as:
+      </p>
+<pre class="programlisting"><span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">typename</span> <span class="identifier">T</span><span class="special">&gt;</span>
+<span class="keyword">class</span> <span class="identifier">optional</span>
+<span class="special">{</span>
+  <span class="keyword">bool</span> <span class="identifier">_initialized</span><span class="special">;</span>
+  <span class="identifier">T</span> <span class="identifier">_storage</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+        Given type <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span></code>, and
+        assuming that <code class="computeroutput"><span class="keyword">sizeof</span><span class="special">(</span><span class="keyword">int</span><span class="special">)</span> <span class="special">==</span>
+        <span class="number">4</span></code>, we will get <code class="computeroutput"><span class="keyword">sizeof</span><span class="special">(</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;)</span>
+        <span class="special">==</span> <span class="number">8</span></code>.
+        This is so because of the alignment rules, for our two members we get the
+        following alignment:
+      </p>
+<p>
+        <span class="inlinemediaobject"><img src="../../images/opt_align1.png" alt="opt_align1"></span>
+      </p>
+<p>
+        This means you can fit twice as many <code class="computeroutput"><span class="keyword">int</span></code>s
+        as <code class="computeroutput"><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span></code>s into
+        the same space of memory. Therefore, if the size of the objects is critical
+        for your application (e.g., because you want to utilize your CPU cache in
+        order to gain performance) and you have determined you are willing to trade
+        the code clarity, it is recommended that you simply go with type <code class="computeroutput"><span class="keyword">int</span></code> and use some 'magic value' to represent
+        <span class="emphasis"><em>not-an-int</em></span>.
+      </p>
+<p>
+        Even if you cannot spare any value of <code class="computeroutput"><span class="keyword">int</span></code>
+        to represent <span class="emphasis"><em>not-an-int</em></span> (e.g., because every value is
+        useful, or you do want to signal <span class="emphasis"><em>not-an-int</em></span> explicitly),
+        at least for <code class="computeroutput"><span class="identifier">Trivial</span></code> types
+        you should consider storing the value and the <code class="computeroutput"><span class="keyword">bool</span></code>
+        flag representing the <span class="emphasis"><em>null-state</em></span> separately. Consider
+        the following class:
+      </p>
+<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">Record</span>
+<span class="special">{</span>
+  <span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">_min</span><span class="special">;</span>
+  <span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">_max</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+        Its memory layout can be depicted as follows:
+      </p>
+<p>
+        <span class="inlinemediaobject"><img src="../../images/opt_align2.png" alt="opt_align2"></span>
+      </p>
+<p>
+        This is exactly the same as if we had the following members:
+      </p>
+<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">Record</span>
+<span class="special">{</span>
+  <span class="keyword">bool</span> <span class="identifier">_has_min</span><span class="special">;</span>
+  <span class="keyword">int</span>  <span class="identifier">_min</span><span class="special">;</span>
+  <span class="keyword">bool</span> <span class="identifier">_has_max</span><span class="special">;</span>
+  <span class="keyword">int</span>  <span class="identifier">_max</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+        But when they are stored separately, we at least have an option to reorder
+        them like this:
+      </p>
+<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">Record</span>
+<span class="special">{</span>
+  <span class="keyword">bool</span> <span class="identifier">_has_min</span><span class="special">;</span>
+  <span class="keyword">bool</span> <span class="identifier">_has_max</span><span class="special">;</span>
+  <span class="keyword">int</span>  <span class="identifier">_min</span><span class="special">;</span>
+  <span class="keyword">int</span>  <span class="identifier">_max</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+        Which gives us the following layout (and smaller total size):
+      </p>
+<p>
+        <span class="inlinemediaobject"><img src="../../images/opt_align3.png" alt="opt_align3"></span>
+      </p>
+<p>
+        Sometimes it requires detailed consideration what data we make optional.
+        In our case above, if we determine that both minimum and maximum value can
+        be provided or not provided together, but one is never provided without the
+        other, we can make only one optional memebr:
+      </p>
+<pre class="programlisting"><span class="keyword">struct</span> <span class="identifier">Limits</span>
+<span class="special">{</span>
+  <span class="keyword">int</span>  <span class="identifier">_min</span><span class="special">;</span>
+  <span class="keyword">int</span>  <span class="identifier">_max</span><span class="special">;</span>
+<span class="special">};</span>
+
+<span class="keyword">struct</span> <span class="identifier">Record</span>
+<span class="special">{</span>
+  <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">Limits</span><span class="special">&gt;</span> <span class="identifier">_limits</span><span class="special">;</span>
+<span class="special">};</span>
+</pre>
+<p>
+        This would give us the following layout:
+      </p>
+<p>
+        <span class="inlinemediaobject"><img src="../../images/opt_align4.png" alt="opt_align4"></span>
+      </p>
+<h5>
+<a name="boost_optional.tutorial.performance_considerations.h0"></a>
+        <span class="phrase"><a name="boost_optional.tutorial.performance_considerations.optional_function_parameters"></a></span><a class="link" href="performance_considerations.html#boost_optional.tutorial.performance_considerations.optional_function_parameters">Optional
+        function parameters</a>
+      </h5>
+<p>
+        Having function parameters of type <code class="computeroutput"><span class="keyword">const</span>
+        <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">T</span><span class="special">&gt;&amp;</span></code>
+        may incur certain unexpected run-time cost connected to copy construction
+        of <code class="computeroutput"><span class="identifier">T</span></code>. Consider the following
+        code.
+      </p>
+<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">fun</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">Big</span><span class="special">&gt;&amp;</span> <span class="identifier">v</span><span class="special">)</span>
+<span class="special">{</span>
+  <span class="keyword">if</span> <span class="special">(</span><span class="identifier">v</span><span class="special">)</span> <span class="identifier">doSomethingWith</span><span class="special">(*</span><span class="identifier">v</span><span class="special">);</span>
+  <span class="keyword">else</span>   <span class="identifier">doSomethingElse</span><span class="special">();</span>
+<span class="special">}</span>
+
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+  <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">Big</span><span class="special">&gt;</span> <span class="identifier">ov</span><span class="special">;</span>
+  <span class="identifier">Big</span> <span class="identifier">v</span><span class="special">;</span>
+  <span class="identifier">fun</span><span class="special">(</span><span class="identifier">none</span><span class="special">);</span>
+  <span class="identifier">fun</span><span class="special">(</span><span class="identifier">ov</span><span class="special">);</span> <span class="comment">// no copy</span>
+  <span class="identifier">fun</span><span class="special">(</span><span class="identifier">v</span><span class="special">);</span>  <span class="comment">// copy constructor of Big</span>
+<span class="special">}</span>
+</pre>
+<p>
+        No copy elision or move semantics can save us from copying type <code class="computeroutput"><span class="identifier">Big</span></code> here. Not that we need any copy, but
+        this is how <code class="computeroutput"><span class="identifier">optional</span></code> works.
+        In order to avoid copying in this case, one could provide second overload
+        of <code class="computeroutput"><span class="identifier">fun</span></code>:
+      </p>
+<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">fun</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">Big</span><span class="special">&amp;</span> <span class="identifier">v</span><span class="special">)</span>
+<span class="special">{</span>
+  <span class="identifier">doSomethingWith</span><span class="special">(</span><span class="identifier">v</span><span class="special">);</span>
+<span class="special">}</span>
+
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+  <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">Big</span><span class="special">&gt;</span> <span class="identifier">ov</span><span class="special">;</span>
+  <span class="identifier">Big</span> <span class="identifier">v</span><span class="special">;</span>
+  <span class="identifier">fun</span><span class="special">(</span><span class="identifier">ov</span><span class="special">);</span> <span class="comment">// no copy</span>
+  <span class="identifier">fun</span><span class="special">(</span><span class="identifier">v</span><span class="special">);</span>  <span class="comment">// no copy: second overload selected</span>
+<span class="special">}</span>
+</pre>
+<p>
+        Alternatively, you could consider using an optional reference instead:
+      </p>
+<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">fun</span><span class="special">(</span><span class="identifier">optional</span><span class="special">&lt;</span><span class="keyword">const</span> <span class="identifier">Big</span><span class="special">&amp;&gt;</span> <span class="identifier">v</span><span class="special">)</span> <span class="comment">// note where the reference is</span>
+<span class="special">{</span>
+  <span class="keyword">if</span> <span class="special">(</span><span class="identifier">v</span><span class="special">)</span> <span class="identifier">doSomethingWith</span><span class="special">(*</span><span class="identifier">v</span><span class="special">);</span>
+  <span class="keyword">else</span>   <span class="identifier">doSomethingElse</span><span class="special">();</span>
+<span class="special">}</span>
+
+<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
+<span class="special">{</span>
+  <span class="identifier">optional</span><span class="special">&lt;</span><span class="identifier">Big</span><span class="special">&gt;</span> <span class="identifier">ov</span><span class="special">;</span>
+  <span class="identifier">Big</span> <span class="identifier">v</span><span class="special">;</span>
+  <span class="identifier">fun</span><span class="special">(</span><span class="identifier">none</span><span class="special">);</span>
+  <span class="identifier">fun</span><span class="special">(</span><span class="identifier">ov</span><span class="special">);</span> <span class="comment">// doesn't compile</span>
+  <span class="identifier">fun</span><span class="special">(</span><span class="identifier">v</span><span class="special">);</span>  <span class="comment">// no copy</span>
+<span class="special">}</span>
+</pre>
+</div>
+<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
+<td align="left"></td>
+<td align="right"><div class="copyright-footer">Copyright &#169; 2003-2007 Fernando Luis Cacciola Carballal<br>Copyright &#169; 2014 Andrzej Krzemie&#324;ski<p>
+        Distributed under the Boost Software License, Version 1.0. (See accompanying
+        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>)
+      </p>
+</div></td>
+</tr></table>
+<hr>
+<div class="spirit-nav">
+<a accesskey="p" href="type_requirements.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="../../optional/reference.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
+</div>
+</body>
+</html>

doc/html/boost_optional/tutorial/type_requirements.html

@@ -7,7 +7,7 @@
 <link rel="home" href="../../index.html" title="Boost.Optional">
 <link rel="up" href="../../optional/tutorial.html" title="Tutorial">
 <link rel="prev" href="exception_safety_guarantees.html" title="Exception Safety Guarantees">
-<link rel="next" href="../../optional/reference.html" title="Reference">
+<link rel="next" href="performance_considerations.html" title="Performance considerations">
 </head>
 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
 <table cellpadding="2" width="100%"><tr>
@@ -20,7 +20,7 @@
 </tr></table>
 <hr>
 <div class="spirit-nav">
-<a accesskey="p" href="exception_safety_guarantees.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="../../optional/reference.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="exception_safety_guarantees.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="performance_considerations.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 </div>
 <div class="section">
 <div class="titlepage"><div><div><h3 class="title">
@@ -103,7 +103,7 @@
 </tr></table>
 <hr>
 <div class="spirit-nav">
-<a accesskey="p" href="exception_safety_guarantees.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="../../optional/reference.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="exception_safety_guarantees.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="performance_considerations.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
 </div>
 </body>
 </html>

doc/html/index.html

@@ -70,6 +70,8 @@
 <dt><span class="section"><a href="boost_optional/tutorial/exception_safety_guarantees.html">Exception
       Safety Guarantees</a></span></dt>
 <dt><span class="section"><a href="boost_optional/tutorial/type_requirements.html">Type requirements</a></span></dt>
+<dt><span class="section"><a href="boost_optional/tutorial/performance_considerations.html">Performance
+      considerations</a></span></dt>
 </dl></dd>
 <dt><span class="section"><a href="optional/reference.html">Reference</a></span></dt>
 <dd><dl>
@@ -134,7 +136,7 @@
 </div>
 </div>
 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><p><small>Last revised: November 21, 2014 at 23:32:40 GMT</small></p></td>
+<td align="left"><p><small>Last revised: December 06, 2014 at 18:09:45 GMT</small></p></td>
 <td align="right"><div class="copyright-footer"></div></td>
 </tr></table>
 <hr>

doc/html/optional/reference.html

@@ -6,7 +6,7 @@
 <meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
 <link rel="home" href="../index.html" title="Boost.Optional">
 <link rel="up" href="../index.html" title="Boost.Optional">
-<link rel="prev" href="../boost_optional/tutorial/type_requirements.html" title="Type requirements">
+<link rel="prev" href="../boost_optional/tutorial/performance_considerations.html" title="Performance considerations">
 <link rel="next" href="../boost_optional/reference/detailed_semantics.html" title="Detailed Semantics">
 </head>
 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
@@ -20,7 +20,7 @@
 </tr></table>
 <hr>
 <div class="spirit-nav">
-<a accesskey="p" href="../boost_optional/tutorial/type_requirements.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="../boost_optional/reference/detailed_semantics.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="../boost_optional/tutorial/performance_considerations.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="../boost_optional/reference/detailed_semantics.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 </div>
 <div class="section">
 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
@@ -181,7 +181,7 @@
 </tr></table>
 <hr>
 <div class="spirit-nav">
-<a accesskey="p" href="../boost_optional/tutorial/type_requirements.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="../boost_optional/reference/detailed_semantics.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
+<a accesskey="p" href="../boost_optional/tutorial/performance_considerations.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="../boost_optional/reference/detailed_semantics.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 </div>
 </body>
 </html>

doc/html/optional/tutorial.html

@@ -44,6 +44,8 @@
 <dt><span class="section"><a href="../boost_optional/tutorial/exception_safety_guarantees.html">Exception
       Safety Guarantees</a></span></dt>
 <dt><span class="section"><a href="../boost_optional/tutorial/type_requirements.html">Type requirements</a></span></dt>
+<dt><span class="section"><a href="../boost_optional/tutorial/performance_considerations.html">Performance
+      considerations</a></span></dt>
 </dl></div>
 <div class="section">
 <div class="titlepage"><div><div><h3 class="title">