coral
A C++ library for distributed co-simulation
Classes | Namespaces | Macros | Enumerations | Functions
error.hpp File Reference

Main header file for coral::error. More...

#include <sstream>
#include <stdexcept>
#include <string>
#include <system_error>
#include "coral/config.h"

Go to the source code of this file.

Classes

class  coral::error::ProtocolViolationException
 Exception thrown when communication fails due to a protocol violation. More...
 
class  coral::error::ProtocolNotSupported
 Exception thrown on an attempt to use an unsupported protocol. More...
 
class  coral::error::PreconditionViolation
 An exception which is used to signal that one or more of a function's preconditions were not met. More...
 

Namespaces

 coral::error
 Exception types and error handling facilities.
 
 std
 STL namespace.
 

Macros

#define CORAL_INPUT_CHECK(test)
 Checks the value of one or more function input parameters, and throws an std::invalid_argument if they do not fulfill the given requirements. More...
 
#define CORAL_PRECONDITION_CHECK(test)
 Throws a coral::error::PreconditionViolation if the given boolean expression evaluates to false. More...
 

Enumerations

Functions

std::string coral::error::ErrnoMessage (const std::string &msg, int errnoValue) CORAL_NOEXCEPT
 Constructs an error message by combining a user-defined message and a standard system error message. More...
 
const std::error_categorycoral::error::generic_category () CORAL_NOEXCEPT
 Error category for generic errors.
 
const std::error_categorycoral::error::sim_category () CORAL_NOEXCEPT
 Error category for simulation errors.
 

Detailed Description

Main header file for coral::error.

Macro Definition Documentation

#define CORAL_INPUT_CHECK (   test)

Checks the value of one or more function input parameters, and throws an std::invalid_argument if they do not fulfill the given requirements.

Example:

void Foo(int x)
{
    SFH_INPUT_CHECK(x > 0);
    ...
}

If the above fails, i.e. if x <= 0, an exception will be thrown with the following error message:

Foo: Input requirement not satisfied: x > 0

This obviates the need to type redundant and tedious stuff like

if (x <= 0) throw std::invalid_argument("x must be greater than zero");

To ensure consistent, clear and understandable exceptions, the following guidelines should be observed when using this macro:

  • The test expression should only include input parameters of the function/method in question, as well as literals and user-accessible symbols. (For example, a requirement that x > m_foo is rather difficult for the user to comply with if m_foo is a private member variable.)
  • Since std::invalid_argument is a subclass of std::logic_error, this macro should only be used to catch logic errors, i.e. errors that are avoidable by design. (For example, !fileName.empty() is probably OK, but exists(fileName) is not, since the latter can only be verified at runtime.)
  • Use descriptive parameter names (e.g. name instead of n).
  • Use the same parameter names in the header and in the implementation.
  • Keep test expressions simple. Complicated expressions can often be written as separate tests.

If, for some reason, any of the above is not possible, consider writing your own specialised if/throw clause.

In general, it is important to keep in mind who is the target audience for the exception and its accompanying error message: namely, other developers who will be using your function, and who will be using the exception to debug their code.

Parameters
[in]testAn expression which can be implicitly converted to bool.
#define CORAL_PRECONDITION_CHECK (   test)

Throws a coral::error::PreconditionViolation if the given boolean expression evaluates to false.

This macro may be used to verify that a function's preconditions hold. For example, say that you have a class File that looks like this:

class File
{
public:
void Open(const std::string& filename);
void Close();
bool IsOpen() const;
};

A reasonable implementation of the Open method could then start like this:

void File::Open()
{
CORAL_INPUT_CHECK(!filename.empty());
...
}

If the first test fails (i.e., if a file has already been opened), an exception of type coral::error::PreconditionViolation will be thrown, with an error message similar to the following:

File::Open: Precondition not satisfied: !IsOpen()

To ensure consistent, clear and understandable exceptions, the test expression should be formulated so that it is possible for a user, who does not know the internals of your class or function, to understand what is going on and how to fix it.

Parameters
[in]testAn expression which can be implicitly converted to bool.