1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Changing the Policy Defaults</title> 5<link rel="stylesheet" href="../../math.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../../index.html" title="Math Toolkit 2.12.0"> 8<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial"> 9<link rel="prev" href="policy_usage.html" title="So How are Policies Used Anyway?"> 10<link rel="next" href="ad_hoc_dist_policies.html" title="Setting Policies for Distributions on an Ad Hoc Basis"> 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="policy_usage.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_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="ad_hoc_dist_policies.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="math_toolkit.pol_tutorial.changing_policy_defaults"></a><a class="link" href="changing_policy_defaults.html" title="Changing the Policy Defaults">Changing 28 the Policy Defaults</a> 29</h3></div></div></div> 30<p> 31 The default policies used by the library are changed by the usual configuration 32 macro method. 33 </p> 34<p> 35 For example, passing <code class="computeroutput"><span class="special">-</span><span class="identifier">DBOOST_MATH_DOMAIN_ERROR_POLICY</span><span class="special">=</span><span class="identifier">errno_on_error</span></code> 36 to your compiler will cause domain errors to set <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code> and return a <a href="http://en.wikipedia.org/wiki/NaN" target="_top">NaN</a> 37 rather than the usual default behaviour of throwing a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span></code> 38 exception. 39 </p> 40<div class="tip"><table border="0" summary="Tip"> 41<tr> 42<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td> 43<th align="left">Tip</th> 44</tr> 45<tr><td align="left" valign="top"> 46<p> 47 For Microsoft Visual Studio,you can add to the Project Property Page, C/C++, 48 Preprocessor, Preprocessor definitions like: 49 </p> 50<pre class="programlisting"><span class="identifier">BOOST_MATH_ASSERT_UNDEFINED_POLICY</span><span class="special">=</span><span class="number">0</span> 51<span class="identifier">BOOST_MATH_OVERFLOW_ERROR_POLICY</span><span class="special">=</span><span class="identifier">errno_on_error</span></pre> 52<p> 53 This may be helpful to avoid complications with pre-compiled headers that 54 may mean that the equivalent definitions in source code: 55 </p> 56<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_ASSERT_UNDEFINED_POLICY</span> <span class="keyword">false</span> 57<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_OVERFLOW_ERROR_POLICY</span> <span class="identifier">errno_on_error</span></pre> 58<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 59 may be ignored*. 60 </li></ul></div> 61<p> 62 The compiler command line shows: 63 </p> 64<pre class="programlisting"><span class="special">/</span><span class="identifier">D</span> <span class="string">"BOOST_MATH_ASSERT_UNDEFINED_POLICY=0"</span> 65<span class="special">/</span><span class="identifier">D</span> <span class="string">"BOOST_MATH_OVERFLOW_ERROR_POLICY=errno_on_error"</span></pre> 66</td></tr> 67</table></div> 68<p> 69 There is however a very important caveat to this: 70 </p> 71<div class="important"><table border="0" summary="Important"> 72<tr> 73<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../../doc/src/images/important.png"></td> 74<th align="left">Important</th> 75</tr> 76<tr><td align="left" valign="top"> 77<p> 78 <span class="bold"><strong><span class="emphasis"><em>Default policies changed by setting configuration 79 macros must be changed uniformly in every translation unit in the program.</em></span></strong></span> 80 </p> 81<p> 82 Failure to follow this rule may result in violations of the "One Definition 83 Rule (ODR)" and result in unpredictable program behaviour. 84 </p> 85</td></tr> 86</table></div> 87<p> 88 That means there are only two safe ways to use these macros: 89 </p> 90<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 91<li class="listitem"> 92 Edit them in <a href="../../../../../../boost/math/tools/user.hpp" target="_top">boost/math/tools/user.hpp</a>, 93 so that the defaults are set on an installation-wide basis. Unfortunately 94 this may not be convenient if you are using a pre-installed Boost distribution 95 (on Linux for example). 96 </li> 97<li class="listitem"> 98 Set the defines in your project's Makefile or build environment, so that 99 they are set uniformly across all translation units. 100 </li> 101</ul></div> 102<p> 103 What you should <span class="bold"><strong>not</strong></span> do is: 104 </p> 105<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 106 Set the defines in the source file using <code class="computeroutput"><span class="preprocessor">#define</span></code> 107 as doing so almost certainly will break your program, unless you're absolutely 108 certain that the program is restricted to a single translation unit. 109 </li></ul></div> 110<p> 111 And, yes, you will find examples in our test programs where we break this 112 rule: but only because we know there will always be a single translation 113 unit only: <span class="emphasis"><em>don't say that you weren't warned!</em></span> 114 </p> 115<p> 116 The following example demonstrates the effect of setting the macro BOOST_MATH_DOMAIN_ERROR_POLICY 117 when an invalid argument is encountered. For the purposes of this example, 118 we'll pass a negative degrees of freedom parameter to the student's t distribution. 119 </p> 120<p> 121 Since we know that this is a single file program we could just add: 122 </p> 123<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">ignore_error</span> 124</pre> 125<p> 126 to the top of the source file to change the default policy to one that simply 127 returns a NaN when a domain error occurs. Alternatively we could use: 128 </p> 129<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">errno_on_error</span> 130</pre> 131<p> 132 To ensure the <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code> 133 is set when a domain error occurs as well as returning a NaN. 134 </p> 135<p> 136 This is safe provided the program consists of a single translation unit 137 <span class="emphasis"><em>and</em></span> we place the define <span class="emphasis"><em>before</em></span> 138 any #includes. Note that should we add the define after the includes then 139 it will have no effect! A warning such as: 140 </p> 141<pre class="programlisting">warning C4005: 'BOOST_MATH_OVERFLOW_ERROR_POLICY' : macro redefinition</pre> 142<p> 143 is a certain sign that it will <span class="emphasis"><em>not</em></span> have the desired 144 effect. 145 </p> 146<p> 147 We'll begin our sample program with the needed includes: 148 </p> 149<pre class="programlisting"> <span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">ignore_error</span> 150 151<span class="comment">// Boost</span> 152<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">students_t</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 153 <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">students_t</span><span class="special">;</span> <span class="comment">// Probability of students_t(df, t).</span> 154 155<span class="comment">// std</span> 156<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 157 <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">;</span> 158 <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 159 160<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">stdexcept</span><span class="special">></span> 161 162 163<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cstddef</span><span class="special">></span> 164 <span class="comment">// using ::errno</span> 165</pre> 166<p> 167 Next we'll define the program's main() to call the student's t distribution 168 with an invalid degrees of freedom parameter, the program is set up to handle 169 either an exception or a NaN: 170 </p> 171<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span> 172<span class="special">{</span> 173 <span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Example error handling using Student's t function. "</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span> 174 <span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"BOOST_MATH_DOMAIN_ERROR_POLICY is set to: "</span> 175 <span class="special"><<</span> <span class="identifier">BOOST_STRINGIZE</span><span class="special">(</span><span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span> 176 177 <span class="keyword">double</span> <span class="identifier">degrees_of_freedom</span> <span class="special">=</span> <span class="special">-</span><span class="number">1</span><span class="special">;</span> <span class="comment">// A bad argument!</span> 178 <span class="keyword">double</span> <span class="identifier">t</span> <span class="special">=</span> <span class="number">10</span><span class="special">;</span> 179 180 <span class="keyword">try</span> 181 <span class="special">{</span> 182 <span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="comment">// Clear/reset.</span> 183 <span class="identifier">students_t</span> <span class="identifier">dist</span><span class="special">(</span><span class="identifier">degrees_of_freedom</span><span class="special">);</span> <span class="comment">// exception is thrown here if enabled.</span> 184 <span class="keyword">double</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">t</span><span class="special">);</span> 185 <span class="comment">// Test for error reported by other means:</span> 186 <span class="keyword">if</span><span class="special">((</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">isnan</span><span class="special">)(</span><span class="identifier">p</span><span class="special">))</span> 187 <span class="special">{</span> 188 <span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"cdf returned a NaN!"</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span> 189 <span class="keyword">if</span> <span class="special">(</span><span class="identifier">errno</span> <span class="special">!=</span> <span class="number">0</span><span class="special">)</span> 190 <span class="special">{</span> <span class="comment">// So errno has been set.</span> 191 <span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"errno is set to: "</span> <span class="special"><<</span> <span class="identifier">errno</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span> 192 <span class="special">}</span> 193 <span class="special">}</span> 194 <span class="keyword">else</span> 195 <span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Probability of Student's t is "</span> <span class="special"><<</span> <span class="identifier">p</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span> 196 <span class="special">}</span> 197 <span class="keyword">catch</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span><span class="special">&</span> <span class="identifier">e</span><span class="special">)</span> 198 <span class="special">{</span> 199 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> 200 <span class="string">"\n"</span><span class="string">"Message from thrown exception was:\n "</span> <span class="special"><<</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 201 <span class="special">}</span> 202 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 203<span class="special">}</span> <span class="comment">// int main()</span> 204</pre> 205<p> 206 Here's what the program output looks like with a default build (one that 207 <span class="bold"><strong>does throw exceptions</strong></span>): 208 </p> 209<pre class="programlisting">Example error handling using Student's t function. 210BOOST_MATH_DOMAIN_ERROR_POLICY is set to: throw_on_error 211 212Message from thrown exception was: 213 Error in function boost::math::students_t_distribution<double>::students_t_distribution: 214 Degrees of freedom argument is -1, but must be > 0 ! 215</pre> 216<p> 217 Alternatively let's build with: 218 </p> 219<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">ignore_error</span> 220</pre> 221<p> 222 Now the program output is: 223 </p> 224<pre class="programlisting">Example error handling using Student's t function. 225BOOST_MATH_DOMAIN_ERROR_POLICY is set to: ignore_error 226cdf returned a NaN! 227</pre> 228<p> 229 And finally let's build with: 230 </p> 231<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">errno_on_error</span> 232</pre> 233<p> 234 Which gives the output show errno: 235 </p> 236<pre class="programlisting">Example error handling using Student's t function. 237BOOST_MATH_DOMAIN_ERROR_POLICY is set to: errno_on_error 238cdf returned a NaN! 239errno is set to: 33 240</pre> 241</div> 242<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 243<td align="left"></td> 244<td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar 245 Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, 246 Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan 247 Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg, 248 Daryle Walker and Xiaogang Zhang<p> 249 Distributed under the Boost Software License, Version 1.0. (See accompanying 250 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>) 251 </p> 252</div></td> 253</tr></table> 254<hr> 255<div class="spirit-nav"> 256<a accesskey="p" href="policy_usage.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_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="ad_hoc_dist_policies.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 257</div> 258</body> 259</html> 260
