2014-07-15-exceptions-error-codes-assertions-c++.html

---
layout: default
title: Exceptions, error codes, and assertions in C++
description: "An overview of the various error reporting mechanisms in C++ and a policy for deciding when each is appropriate."
tag: C++
---
<p>It can often be difficult to decide between the various methods of error reporting in C++. For example, some common advice is that exceptions should only be thrown in exceptional circumstances. Needless to say, this isn't particularly helpful. What exactly is an exceptional circumstance? An exception to what? If we throw assertions into the mix, this can become even more complicated.</p>
<p>In general, functions express a contract to the calling code. They promise to perform some operation and give a particular result according to the given inputs. A member function can be considered to take an additional parameter, <code>this</code>, which is the object it's acting on. When a member function is not <code>const</code>, its <code>this</code> parameter is also an output. Error reporting is how we handle when there is a problem with meeting this contract and ensure that the relevant parties have been informed.</p>
<p>Error reporting can occur at compile-time, in which case the compiler emits the error, or at run-time. Detecting a problem at compile-time is usually much better, as the program simply will not build until it is fixed and there will be no run-time cost. However, run-time error reporting is necessary for problems that cannot be statically detected or for when the error can be considered part of the normal execution of the program as long as it is handled appropriately.</p>
<section>
	<h1>Function design</h1>
	<p>The ultimate way to prevent misuse of a function is to design its interface so that it simply cannot be misused. This means choosing parameter and return types that accurately represent what the user should be able to pass to and receive from the function. For example, <a href="{% post_url articles/2014-06-19-avoiding-ambiguity-raw-pointers %}">raw pointers often do not sufficiently express the function's intent and there are almost always better alternatives</a>. It also means ensuring that your functions behave responsibly - no hidden side effects, no hidden dependencies, <a href="http://stackoverflow.com/a/1853769/150634">proper exception safety</a>, and so on. With later versions of C++, it will also mean using concepts (<a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4040.pdf">draft N4040</a>) appropriately to constrain template arguments.</p>
	<p>The more expressive your function interfaces are with built in language features, the more the user can trust your functions and be confident that they will not screw anything up.</p>
</section>
<section>
	<h1>Static assertions</h1>
	<p>The next best thing is to introduce your own static error checking with <a href="http://en.cppreference.com/w/cpp/language/static_assert"><code>static_assert</code></a>. Using <a href="http://en.cppreference.com/w/cpp/types">type traits</a> and constant expressions, we can form conditions that can be evaluated and checked at compile-time. For example, while we do not yet have concepts, it is easy to enforce that a template function should only be instantiated for an integral type:</p>

{% highlight cpp %}
template <typename T>
void foo(T arg) {
  static_assert(std::is_integral<T>::value, "T must be an integral type");
  // ...
}
{% endhighlight %}

	<p>Static assertions can only evaluate constant expressions, so you won't be able to check anything that isn't known until run-time. For example, if you receive input from the user, you cannot check the value of this input with a <code>static_assert</code>. For that you need run-time error reporting.</p>
</section>
<section>
	<h1>Exceptions</h1>
	<p>When a problem cannot be detected at compile-time or when an error should reported to the calling code, the above approaches are not appropriate. Instead, we look to exceptions, error codes, and run-time assertions.</p>
	<p>Exceptions can sometimes be quite difficult to decide when to use. What exactly constitute an exceptional circumstance? I prefer to think of it this way: a function should throw an exception if it is unable to fulfil the promise that it made to the calling code. To figure out what that promise is, summarize your function in one simple sentence (with no conjunctions). What does the function do? Look at the name of the function, the parameters it takes, and the objects it returns and write down what it promises. If you can't do this, perhaps your function should be simplified or split up into multiple functions.</p>
	<p>Once you have a simple description of the function's behavior, it's easy to determine when an exception should be thrown. If it can't fulfil its promise, it should throw. It might be because the user gave it some arguments that were unsuitable or because some internal problem occurs - either way, throw an exception. As an example, consider the following function declaration:</p>

{% highlight cpp %}
image load_image(boost::filesystem::path image_file_path);
{% endhighlight %}

	<p>It should be clear what this function promises to do. It says "I will load an image from the given file path." If it is unable to perform this job, perhaps because the file does not exist or there is some other I/O problem, it should throw an exception. In fact, what else would it do in these situations? If it returns, it has to return an <code>image</code> object after all. You could have a special value of <code>image</code> that represents that an error has occurred, but I strongly advise against that. Exceptions allow the function to break out early and not have to care about returning an object of the correct type.</p>
	<p>The only issue with exceptions is that you have to be careful. With the lack of useful exception specifications in C++, it is important to check the documentation for a function to see if it throws. Always try to write <a href="http://stackoverflow.com/a/1853769/150634">exception safe code</a>.</p>
	<p>A common fallacy is that exceptions are slow. In fact, modern exception implementations have <a href="http://stackoverflow.com/a/13836329/150634">no cost when the exception is not thrown</a> (unlike an explicit check with <code>if</code>). There is some cost when throwing an exception, but you should find that they are not thrown often, so this cost can largely be ignored. Regardless, favor code readability and safety over performance until you measure that exceptions are a bottleneck in your code.</p>
</section>
<section>
	<h1>Error codes</h1>
	<p>Error codes have much less reason to be used in modern C++. They come in two flavors: an output object dedicated to expressing error conditions, or a special value of an output object that represents the error condition. Output parameters (that is, non-<code>const</code> reference or pointer parameters) are not typically a good idea and return objects should be preferred. This means that with the first flavor, the error codes must either be the sole output of a function or returned as part of a <a href="http://en.cppreference.com/w/cpp/utility/tuple"><code>std::tuple</code></a> or <a href="http://en.cppreference.com/w/cpp/utility/pair"><code>std::pair</code></a>. This may be an acceptable use of error codes. However, using a special value is not likely to be acceptable. In the above example, an image that failed to load should not be a valid <code>image</code> object. Doing so introduces special cases to your code and ruins any uniformity.</p>
	<p>The important thing about error codes is that, unlike exceptions, they are part of the promise that a function makes. If the simple description of your function states that it provides error codes as part of its normal functionality, then an error code is okay. An obvious example for this is a function that is used specifically to report errors from some state (such as <a href="https://www.opengl.org/sdk/docs/man/docbook4/xhtml/glGetError.xml"><code>glGetError</code></a>). In this way, an error code shouldn't really represent a problem with the operation of the function, since returning an error code is actually successful operation.</p>
	<p>Some gray areas arise when we look at functions that really do have a special case result. Consider a function like <a href="http://en.cppreference.com/w/cpp/algorithm/find"><code>std::find</code></a> that tries to find an element in a container. If it doesn't find the element, is that an exception? I would suggest it is not because the item not existing is a perfectly reasonable response to being asked to find it. Isn't the past-the-end iterator returned by <code>std::find</code> in this case an example of a special return value? Perhaps, but it provides a certain uniformity that allows it to be used in conjuction with other algorithms. An alternative interface might return a <a href="http://www.boost.org/doc/libs/1_55_0/libs/optional/doc/html/index.html"><code>boost::optional</code></a> with an optional iterator (in C++17, <code>std::optional</code>).</p>
</section>
<section>
	<h1>Run-time assertions</h1>
	<p>The <a href="http://en.cppreference.com/w/cpp/error/assert"><code>assert</code></a> macro from the <code>&lt;cassert&gt;</code> header, also known as a C assert, is able to check run-time conditions and abort execution if the condition is not met. It doesn't report the problem to the calling function. Since your program immediately ends when these assertions fail, they probably shouldn't make it into production builds. In fact, <code>assert</code> is defined such that you can turn it off by defining the macro name <code>NDEBUG</code>, so that it will only be triggered in debug builds.</p>
	<p>Due to these properties, <code>assert</code> is most useful for sanity checks. That is, use <code>assert</code> internally to ensure that your code is doing what you expect it to do. It means "I know that this should be true in all cases, so if it's not, something is terribly wrong." For example, if you write a function that performs some complex calculation and you know that the result should always be greater than a certain value, otherwise the calculation has been implemented incorrectly, use <code>assert</code> to check this. Then when you run your debug build and a call to this function occurs that causes the assertion to fail, you'll know immediately that there's a problem and can start debugging the issue.</p>
</section>
<section>
	<h1>Summary</h1>
	<p>In summary, the different forms of error reporting should be used as follows:</p>
	<dl>
		<dt>Static assertions</dt><dd>To prevent invalid instantiations of templates and to check other compile-time conditions.</dd>
		<dt>Exceptions</dt><dd>To let some calling code know that a function was unable to fulfil its contract due to some run-time problems.</dd>
		<dt>Error codes</dt><dd>To report run-time conditions that are part of a function's contract and considered normal behavior.</dd>
		<dt>Run-time assertions</dt><dd>To perform sanity checks on internal operations at run-time and ensure that major bugs do not enter production builds.</dd>
	</dl>
	<p>Remember that carefully designing your functions can avoid the need for many of these checks by preventing the user from misusing them in the first place.</p>
</section>