Merge lp:~michihenning/unity-api/add-ExceptionImplBase into lp:unity-api

[Michi Henning]

Removed unity::internal::ExceptionImpl and replaced it with unity::ExceptionImplBase.
This allows clients of unity-api to derive their own exceptions for unity::Exception without exposing any implementation details (so the ABI won't break) and still take advantage of implementation inheritance without having to reimplement all the functionality of the base class

Removed unity::internal::ExceptionImpl and replaced it with unity::ExceptionImplBase.
This allows clients of unity-api to derive their own exceptions for unity::Exception without exposing any implementation details (so the ABI won't break) and still take advantage of implementation inheritance without having to reimplement all the functionality of the base class.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:56
http://jenkins.qa.ubuntu.com/job/unity-api-ci/74/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-saucy-armhf-ci/31
        deb: http://jenkins.qa.ubuntu.com/job/unity-api-saucy-armhf-ci/31/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-saucy-i386-ci/32

Click here to trigger a rebuild:
http://s-jenkins:8080/job/unity-api-ci/74/rebuild

review: Approve (continuous-integration)

[Jussi Pakkanen (jpakkane)]

LGTM.

Under what circumstances would clients want to derive our exceptions, though? For their internal use they would probably use their own types. The only reason I can think of if they need to inject exceptions back to us and expect us to act on them in some way. Which seems a bit weird.

review: Approve

[Michi Henning (michihenning)]

> LGTM.
>
> Under what circumstances would clients want to derive our exceptions, though?

For example, unity-scopes-api is a client of unity-api. I need a MiddlewareException so I can catch a specific group of exceptions from the middleware layer selectively. I want to derive that exception from unity::Exception, so *all* exceptions ultimately are unity::exception or std::exception (which is a base for unity::exception). But that means I have to be able to derive form unity::exception without using the unity::internal namespace. (The previous design made that impossible.)

> For their internal use they would probably use their own types.

Yes, clients are free to do whatever they want with their own exceptions. But it's really nice to be able to say "catch any scope exception" or "catch any Unity API exception" for structured error handling.

And the functionality in unity::exception is kind of neat. Especially the nesting mechanism that preserves the original exception when an exception is re-thrown as something else is nice. It has zero API footprint and does the work quietly behind the scenes.

> The only
> reason I can think of if they need to inject exceptions back to us and expect
> us to act on them in some way. Which seems a bit weird.

There might a few places where we may expect scope to tell us something specific, in which case we can tell the author "you must throw X, if Y happens." But I don't expect there to many such cases, if any.

[PS Jenkins bot (ps-jenkins)]

FAILED: Autolanding.
More details in the following jenkins job:
http://jenkins.qa.ubuntu.com/job/unity-api-autolanding/26/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/unity-api-saucy-armhf-autolanding/9/console
    FAILURE: http://jenkins.qa.ubuntu.com/job/unity-api-saucy-i386-autolanding/9/console

review: Needs Fixing (continuous-integration)

[lp:~michihenning/unity-api/add-ExceptionImplBase]

57. By Michi Henning on 2013-06-17

Merged trunk.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:57
http://jenkins.qa.ubuntu.com/job/unity-api-ci/75/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-saucy-armhf-ci/32
        deb: http://jenkins.qa.ubuntu.com/job/unity-api-saucy-armhf-ci/32/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-api-saucy-i386-ci/33

Click here to trigger a rebuild:
http://s-jenkins:8080/job/unity-api-ci/75/rebuild

review: Approve (continuous-integration)

[Michi Henning (michihenning)]

Jenkins is happy with this now. Can someone top-approve please?

=== modified file 'include/unity/Exception.h'
--- include/unity/Exception.h	2013-06-12 22:07:05 +0000
+++ include/unity/Exception.h	2013-06-17 04:58:28 +0000
@@ -20,6 +20,7 @@
 #define UNITY_EXCEPTION_H
 
 #include <unity/SymbolExport.h>
+#include <unity/util/NonCopyable.h>
 
 #include <exception>
 #include <string>
@@ -28,15 +29,7 @@
 namespace unity
 {
 
-namespace internal
-{
-class ExceptionImpl;
-}
-
-// TODO: It probably would be best to split this into a base and ImplBase, with the derived part in the internal
-//       namespace and declaring self(), the constructor, and pimpl(). That's because the Impl for the exception
-//       is in the internal namespace, so public API clients can use Exception instances, but they cannot
-//       create new derived exceptions because the Impl classes are internal to Unity.
+class ExceptionImplBase;
 
 /**
 \brief Abstract base class for all Unity exceptions.
@@ -126,14 +119,6 @@
     */
     virtual char const* what() const noexcept = 0;
 
-    virtual std::string reason() const;
-
-    virtual std::string to_string(std::string const& indent = "    ") const;
-    virtual std::string to_string(int indent_level, std::string const& indent) const;
-
-    std::exception_ptr remember(std::exception_ptr earlier_exception);
-    std::exception_ptr get_earlier() const noexcept;
-
     /**
     \brief Returns a <code>std::exception_ptr</code> to <code>this</code>.
 
@@ -142,15 +127,22 @@
     */
     virtual std::exception_ptr self() const = 0;
 
+    std::string reason() const;
+
+    std::string to_string(std::string const& indent = "    ") const;
+    std::string to_string(int indent_level, std::string const& indent) const;
+
+    std::exception_ptr remember(std::exception_ptr earlier_exception);
+    std::exception_ptr get_earlier() const noexcept;
+
 protected:
     //! @cond
-    Exception(std::shared_ptr<internal::ExceptionImpl> const& derived);
-    internal::ExceptionImpl* pimpl() const noexcept;     // No need to reimplement in derived
+    Exception(std::shared_ptr<ExceptionImplBase> const& derived);
     //! @endcond
+    ExceptionImplBase* pimpl() const noexcept;
 
 private:
-    std::shared_ptr<internal::ExceptionImpl> p_;         // shared_ptr instead of unique_ptr because
-                                                         // exceptions must be copyable
+    std::shared_ptr<ExceptionImplBase> p_;    // shared_ptr instead of unique_ptr because exceptions must be copyable
 };
 
 } // namespace unity

=== added file 'include/unity/ExceptionImplBase.h'
--- include/unity/ExceptionImplBase.h	1970-01-01 00:00:00 +0000
+++ include/unity/ExceptionImplBase.h	2013-06-17 04:58:28 +0000
@@ -0,0 +1,65 @@
+/*
+ * Copyright (C) 2013 Canonical Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 3 as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Authored by: Michi Henning <[e-mail]>
+ */
+
+#ifndef UNITY_EXCEPTIONIMPLBASE_H
+#define UNITY_EXCEPTIONIMPLBASE_H
+
+#include <unity/SymbolExport.h>
+#include <unity/util/NonCopyable.h>
+
+#include <exception>
+#include <string>
+#include <memory>
+
+namespace unity
+{
+
+namespace internal
+{
+class ExceptionData;
+}
+
+class Exception;
+
+/**
+\brief Implementation base exception class for API clients to derive new pimpl'd exception types from.
+\sa unity::Exception
+*/
+
+class UNITY_API ExceptionImplBase : public util::NonCopyable
+{
+public:
+    explicit ExceptionImplBase(Exception const* owner, std::string const& reason);
+    //! @cond
+    virtual ~ExceptionImplBase() noexcept;
+    //! @endcond
+
+    std::string reason() const;
+
+    std::string to_string(std::nested_exception const* nested, int indent_level, std::string const& indent) const;
+
+    std::exception_ptr set_earlier(std::exception_ptr earlier_exception);
+    std::exception_ptr get_earlier() const noexcept;
+
+private:
+    std::shared_ptr<internal::ExceptionData> p_;  // shared_ptr (not unique_ptr) because ExceptionData is incomplete
+};
+
+} // namespace unity
+
+#endif

=== modified file 'include/unity/UnityExceptions.h'
--- include/unity/UnityExceptions.h	2013-06-12 22:07:05 +0000
+++ include/unity/UnityExceptions.h	2013-06-17 04:58:28 +0000
@@ -24,11 +24,6 @@
 namespace unity
 {
 
-namespace internal
-{
-class InvalidArgumentExceptionImpl;
-}
-
 /**
 \brief Exception to indicate that an invalid argument was passed to a function, such as passing <code>nullptr</code>
        when the function expects the argument to be non-null.
@@ -59,11 +54,6 @@
     virtual std::exception_ptr self() const override;
 };
 
-namespace internal
-{
-class LogicExceptionImpl;
-}
-
 /**
 \brief Exception to indicate a logic error, such as driving the API incorrectly, such as calling methods
        in the wrong worder.
@@ -94,11 +84,6 @@
     virtual std::exception_ptr self() const override;
 };
 
-namespace internal
-{
-class ShutdownExceptionImpl;
-}
-
 /**
 \brief Exception to indicate errors during shutdown.
 
@@ -174,6 +159,9 @@
     \return Returns the error number that was passed to the constructor.
     */
     int error() const noexcept;
+
+private:
+    std::shared_ptr<internal::FileExceptionImpl> p_;
 };
 
 namespace internal
@@ -217,13 +205,11 @@
     \return Returns the error number that was passed to the constructor.
     */
     int error() const noexcept;
+
+private:
+    //std::shared_ptr<internal::SyscallExceptionImpl> p_;
 };
 
-namespace internal
-{
-class ResourceExceptionImpl;
-}
-
 /**
 \brief Exception for miscellaneous errors, such as failure of a third-party library or hitting resource limitations.
 */
@@ -235,7 +221,7 @@
     \brief Constructs the exception.
     \param reason Further details about the cause of the exception.
     */
-    ResourceException(std::string const& reason);
+    explicit ResourceException(std::string const& reason);
     //! @cond
     ResourceException(ResourceException const&);
     ResourceException& operator=(ResourceException const&);

=== removed file 'include/unity/internal/ExceptionImpl.h'
--- include/unity/internal/ExceptionImpl.h	2013-06-12 22:07:05 +0000
+++ include/unity/internal/ExceptionImpl.h	1970-01-01 00:00:00 +0000
@@ -1,60 +0,0 @@
-/*
- * Copyright (C) 2013 Canonical Ltd
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the Lesser GNU General Public License version 3 as
- * published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * Lesser GNU General Public License for more details.
- *
- * You should have received a copy of the Lesser GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * Authored by: Michi Henning <[e-mail]>
- */
-
-#ifndef UNITY_INTERNAL_EXCEPTIONIMPL_H
-#define UNITY_INTERNAL_EXCEPTIONIMPL_H
-
-#include <unity/util/NonCopyable.h>
-
-#include <string>
-#include <exception>
-
-namespace unity
-{
-
-class Exception;
-
-namespace internal
-{
-
-class ExceptionImpl : private util::NonCopyable
-{
-public:
-    explicit ExceptionImpl(std::string const& reason);
-
-    virtual char const* what() const noexcept = 0;
-    virtual std::string reason() const;
-    virtual std::string to_string(std::nested_exception const& nested, int indent_level, std::string const& indent) const;
-
-    std::exception_ptr remember(unity::Exception const* env, std::exception_ptr earlier_exception);
-    std::exception_ptr remember(unity::Exception const* env, Exception const& earlier_exception);
-    std::exception_ptr get_earlier() const noexcept;
-
-protected:
-    virtual ~ExceptionImpl() noexcept;
-
-private:
-    std::string const reason_;
-    std::exception_ptr previous_;
-};
-
-} // namespace internal
-
-} // namespace unity
-
-#endif

=== removed file 'include/unity/internal/UnityExceptionsImpl.h'
--- include/unity/internal/UnityExceptionsImpl.h	2013-06-12 22:07:05 +0000
+++ include/unity/internal/UnityExceptionsImpl.h	1970-01-01 00:00:00 +0000
@@ -1,95 +0,0 @@
-/*
- * Copyright (C) 2012 Canonical Ltd
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the Lesser GNU General Public License version 3 as
- * published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * Lesser GNU General Public License for more details.
- *
- * You should have received a copy of the Lesser GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * Authored by: Michi Henning <[e-mail]>
- */
-
-#ifndef UNITY_INTERNAL_UNITYEXCEPTIONSIMPL_H
-#define UNITY_INTERNAL_UNITYEXCEPTIONSIMPL_H
-
-#include <unity/internal/ExceptionImpl.h>
-
-#include <string>
-#include <exception>
-
-namespace unity
-{
-
-class Exception;
-
-namespace internal
-{
-
-class InvalidArgumentExceptionImpl : public ExceptionImpl
-{
-public:
-    InvalidArgumentExceptionImpl(std::string const& reason);
-
-    virtual char const* what() const noexcept override;
-};
-
-class LogicExceptionImpl : public ExceptionImpl
-{
-public:
-    LogicExceptionImpl(std::string const& reason);
-
-    virtual char const* what() const noexcept override;
-};
-
-class ShutdownExceptionImpl : public ExceptionImpl
-{
-public:
-    ShutdownExceptionImpl(std::string const& reason);
-
-    virtual char const* what() const noexcept override;
-};
-
-class FileExceptionImpl : public ExceptionImpl
-{
-public:
-    FileExceptionImpl(std::string const& reason, int err);
-
-    virtual char const* what() const noexcept override;
-    int error() const noexcept;
-
-private:
-    int errno_;
-};
-
-class SyscallExceptionImpl : public ExceptionImpl
-{
-public:
-    SyscallExceptionImpl(std::string const& reason, int err);
-
-    virtual char const* what() const noexcept override;
-    int error() const noexcept;
-
-private:
-    int const errno_;
-};
-
-class ResourceExceptionImpl : public ExceptionImpl
-{
-public:
-    ResourceExceptionImpl(std::string const& reason);
-
-    virtual char const* what() const noexcept override;
-};
-
-} // namespace internal
-
-} // namespace unity
-
-#endif

=== modified file 'src/unity/CMakeLists.txt'
--- src/unity/CMakeLists.txt	2013-05-13 11:39:49 +0000
+++ src/unity/CMakeLists.txt	2013-06-17 04:58:28 +0000
@@ -4,6 +4,7 @@
 
 set(UNITY_SRC
     ${CMAKE_CURRENT_SOURCE_DIR}/Exception.cpp
+    ${CMAKE_CURRENT_SOURCE_DIR}/ExceptionImplBase.cpp
     ${CMAKE_CURRENT_SOURCE_DIR}/UnityExceptions.cpp
 )
 

=== modified file 'src/unity/Exception.cpp'
--- src/unity/Exception.cpp	2013-06-12 22:07:05 +0000
+++ src/unity/Exception.cpp	2013-06-17 04:58:28 +0000
@@ -17,7 +17,7 @@
  */
 
 #include <unity/Exception.h>
-#include <unity/internal/ExceptionImpl.h>
+#include <unity/ExceptionImplBase.h>
 
 using namespace std;
 
@@ -27,7 +27,7 @@
 //! @cond
 
 Exception::
-Exception(shared_ptr<internal::ExceptionImpl> const& derived)
+Exception(shared_ptr<ExceptionImplBase> const& derived)
     : p_(derived)
 {
 }
@@ -59,7 +59,7 @@
 }
 
 /**
-Returns a string describing the exception, including any exceptions that were nested or chained.
+\brief Returns a string describing the exception, including any exceptions that were nested or chained.
 
 Nested exceptions are indented according to their nesting level. If the exception contains chained
 exceptions, these are shown in oldest-to-newest order.
@@ -74,11 +74,11 @@
 Exception::
 to_string(std::string const& indent) const
 {
-    return p_->to_string(*this, 0, indent);
+    return p_->to_string(this, 0, indent);
 }
 
 /**
-Returns a string describing the exception, including any exceptions that were nested or chained.
+\brief Returns a string describing the exception, including any exceptions that were nested or chained.
 
 Nested exceptions are indented according to their nesting level. If the exception contains chained
 exceptions, these are shown in oldest-to-newest order.
@@ -97,11 +97,11 @@
 Exception::
 to_string(int indent_level, std::string const& indent) const
 {
-    return p_->to_string(*this, indent_level, indent);
+    return p_->to_string(this, indent_level, indent);
 }
 
 /**
-Adds an exception to the exception history chain.
+\brief Adds an exception to the exception history chain.
 
 \param earlier_exception The parameter must be a <code>nullptr</code> or a <code>std::exception_ptr</code>
 to an exception that was remembered earlier. This allows a sequence of exceptions to be remembered without
@@ -116,11 +116,11 @@
 Exception::
 remember(exception_ptr earlier_exception)
 {
-    return p_->remember(this, earlier_exception);
+    return p_->set_earlier(earlier_exception);
 }
 
 /**
-Returns the previous exception.
+\brief Returns the previous exception.
 \return Returns the next-older remembered exception, or <code>nullptr</code>, if none.
 */
 
@@ -131,15 +131,15 @@
     return p_->get_earlier();
 }
 
-//! @cond
+/**
+\brief Returns a pointer to to the implementation instance.
+*/
 
-internal::ExceptionImpl*
+ExceptionImplBase*
 Exception::
 pimpl() const noexcept
 {
     return p_.get();
 }
 
-//! @endcond
-
 } // namespace unity

=== added file 'src/unity/ExceptionImplBase.cpp'
--- src/unity/ExceptionImplBase.cpp	1970-01-01 00:00:00 +0000
+++ src/unity/ExceptionImplBase.cpp	2013-06-17 04:58:28 +0000
@@ -0,0 +1,310 @@
+/*
+ * Copyright (C) 2012 Canonical Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 3 as
+ * published by the Free Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ * Authored by: Michi Henning <[e-mail]>
+ */
+
+#include <unity/ExceptionImplBase.h>
+#include <unity/Exception.h>
+
+using namespace std;
+
+namespace unity
+{
+
+namespace internal
+{
+
+class ExceptionData
+{
+public:
+    ExceptionData(Exception const* owner, string const& reason)
+        : owner_(owner)
+        , reason_(reason)
+        , earlier_(nullptr)
+    {
+    }
+
+    ExceptionData(ExceptionData const&) = delete;
+    ExceptionData& operator=(ExceptionData const&) = delete;
+
+    Exception const* owner_;
+    string reason_;
+    std::exception_ptr earlier_;
+};
+
+}
+
+/**
+\brief Instantiates an implementation instance for a unity::Exception.
+\param owner This must be set to the `this` pointer of the exception that owns this implementation.
+\param reason Further details about the cause of the exception.
+*/
+
+ExceptionImplBase::
+ExceptionImplBase(Exception const* owner, string const& reason)
+    : p_(make_shared<internal::ExceptionData>(owner, reason))
+{
+}
+
+//! @cond
+
+ExceptionImplBase::
+~ExceptionImplBase() noexcept = default;
+
+namespace
+{
+
+//
+// Return the margin string for the indent level and indent.
+//
+
+string
+get_margin(int indent_level, string const& indent)
+{
+    string margin;
+    for (int i = 0; i < indent_level; ++i)
+    {
+        margin += indent;
+    }
+    return margin;
+}
+
+//
+// Follow the nested exceptions that were rethrown along the call stack, printing them into s.
+//
+
+void
+print_name_and_reason(string& s, nested_exception const* nested)
+{
+    // Add the what() string if this is a std::exception.
+
+    std::exception const* std_exception = dynamic_cast<std::exception const*>(nested);
+    if (std_exception)
+    {
+        s += std_exception->what();
+    }
+
+    // Add the reason if this is a unity::Exception.
+
+    unity::Exception const* unity_exception = dynamic_cast<unity::Exception const*>(nested);
+    if (unity_exception)
+    {
+        string reason = unity_exception->reason();
+        if (!reason.empty())
+        {
+            s += ": " + reason;
+        }
+    }
+
+    // Append info about unknown std::exception and std::nested_exception.
+
+    if (!unity_exception)
+    {
+        if (std_exception)
+        {
+            s += " (derived from std::exception and std::nested_exception)";
+        }
+        else
+        {
+            s += "std::nested_exception";
+        }
+    }
+}
+
+void
+follow_nested(string& s, nested_exception const* nested, int indent_level, std::string const& indent)
+{
+    if (nested->nested_ptr())
+    {
+        string margin = get_margin(indent_level, indent);
+
+        s += ":\n";
+        try
+        {
+            nested->rethrow_nested();
+        }
+        catch (std::nested_exception const& e)
+        {
+            unity::Exception const* ge = dynamic_cast<unity::Exception const*>(&e);
+            if (ge)
+            {
+                s += ge->to_string(indent_level + 1, indent);
+            }
+            else
+            {
+                s += margin + indent;
+                print_name_and_reason(s, &e);
+                follow_nested(s, &e, indent_level + 1, indent);
+            }
+        }
+        catch (std::exception const& e)
+        {
+            s += margin + indent;
+            s += e.what();                                    // Can show only what() for std::exception.
+        }
+        catch (...)
+        {
+            s += margin + indent;
+            s += "unknown exception";                         // Best we can do for an exception whose type we don't know.
+        }
+    }
+}
+
+//
+// Follow the history chain and print each exception in the chain.
+//
+
+void
+follow_history(string& s, int& count, unity::Exception const* e, int indent_level, std::string const& indent)
+{
+    if (!e->get_earlier())
+    {
+        count = 1;  // We have reached the oldest exception; set exception generation count and terminate recursion.
+    }
+    else
+    {
+        try
+        {
+            rethrow_exception(e->get_earlier());
+        }
+        catch (unity::Exception const& e)
+        {
+            // Recurse along the chain until we hit the end, then, as we pop back up the levels, we increment the
+            // count and print it as a generation number for the exception information.
+            // A bit like the "kicks" in "Inception", except that the deepest level is level 1...
+
+            follow_history(s, count, &e, indent_level, indent);
+        }
+        ++count;
+    }
+
+    // Show info for this exception.
+
+    s += "\n" + get_margin(indent_level, indent) + "Exception #";
+    s += to_string(count) + ":\n";
+    s += get_margin(indent_level, indent) + indent;
+    print_name_and_reason(s, e);
+    follow_nested(s, e, indent_level + 1, indent);
+}
+
+} // namespace
+
+//! @endcond
+
+/**
+\brief Returns the reason set by the derived class's constructor (empty string if none).
+
+Derived classes should include any other state information, such as the value of data members or
+other relevant detail in the <code>reason</code> string they pass to the protected constructor.
+*/
+
+string
+ExceptionImplBase::
+reason() const
+{
+    return p_->reason_;
+}
+
+/**
+\brief Returns a string describing the exception, including any exceptions that were nested or chained.
+
+Nested exceptions are indented according to their nesting level. If the exception contains chained
+exceptions, these are shown in oldest-to-newest order.
+
+\param nested This must be set to the `this` pointer of the exception that owns this implementation.
+
+\param indent_level This controls the indent level. The value <code>0</code> indicates
+       the outermost level (no indent).
+\param indent This controls the amount of indenting per level. The default indent is four spaces.
+\return The string describing the exception.
+*/
+
+string
+ExceptionImplBase::
+to_string(nested_exception const* nested, int indent_level, string const& indent) const
+{
+    string margin = get_margin(indent_level, indent);
+    string s = margin;
+    s += dynamic_cast<const std::exception*>(nested)->what();
+
+    string r = reason();
+    if (!r.empty())
+    {
+        s += ": " + r;
+    }
+
+    // Check whether there is an exception history and print each exception in the history.
+
+    unity::Exception const* unity_exception(dynamic_cast<unity::Exception const*>(nested));
+    if (unity_exception && unity_exception->get_earlier())
+    {
+        s += "\n" + margin + indent + "Exception history:";
+        try
+        {
+            rethrow_exception(unity_exception->get_earlier());
+        }
+        catch (unity::Exception const& e)
+        {
+            int count;
+            follow_history(s, count, &e, indent_level + 2, indent);
+        }
+    }
+
+    // Print this and any nested exceptions.
+
+    follow_nested(s, nested, indent_level, indent);
+
+    return s;
+}
+
+/**
+\brief Adds an exception to the exception history chain.
+
+\param earlier_exception The parameter must be a <code>nullptr</code> or a <code>std::exception_ptr</code>
+to an exception that was remembered earlier. This allows a sequence of exceptions to be remembered without
+having to throw them and is useful for example, in shutdown scenarios where any one of a sequence of steps
+can fail, but we want to continue and try all the following steps and only throw after all of them have been
+tried. In this case, each step that fails can add itself to the sequence of remembered exceptions, and finally
+throw something like <code>ShutdownException</code>.
+\return A <code>std::exception_ptr</code> to <code>this</code>.
+*/
+
+exception_ptr
+ExceptionImplBase::
+set_earlier(exception_ptr earlier_exception)
+{
+    // Doesn't prevent loops, but protects against accidental self-assignment.
+
+    if (p_->earlier_ != earlier_exception)
+    {
+        p_->earlier_ = earlier_exception;
+    }
+    return p_->owner_->self();
+}
+
+/**
+\brief Returns the previous exception.
+\return Returns the next-older remembered exception, or <code>nullptr</code>, if none.
+*/
+
+exception_ptr
+ExceptionImplBase::
+get_earlier() const noexcept
+{
+    return p_->earlier_;
+}
+
+} // namespace unity

=== modified file 'src/unity/UnityExceptions.cpp'
--- src/unity/UnityExceptions.cpp	2013-06-12 22:07:05 +0000
+++ src/unity/UnityExceptions.cpp	2013-06-17 04:58:28 +0000
@@ -17,7 +17,7 @@
  */
 
 #include <unity/UnityExceptions.h>
-#include <unity/internal/UnityExceptionsImpl.h>
+#include <unity/ExceptionImplBase.h>
 
 using namespace std;
 
@@ -26,7 +26,7 @@
 
 InvalidArgumentException::
 InvalidArgumentException(string const& reason)
-    : Exception(make_shared<internal::InvalidArgumentExceptionImpl>(reason))
+    : Exception(make_shared<ExceptionImplBase>(this, reason))
 {
 }
 
@@ -49,7 +49,7 @@
 InvalidArgumentException::
 what() const noexcept
 {
-    return dynamic_cast<internal::InvalidArgumentExceptionImpl*>(pimpl())->what();
+    return "unity::InvalidArgumentException";
 }
 
 exception_ptr
@@ -61,7 +61,7 @@
 
 LogicException::
 LogicException(string const& reason)
-    : Exception(make_shared<internal::LogicExceptionImpl>(reason))
+    : Exception(make_shared<ExceptionImplBase>(this, reason))
 {
 }
 
@@ -83,7 +83,7 @@
 LogicException::
 what() const noexcept
 {
-    return dynamic_cast<internal::LogicExceptionImpl*>(pimpl())->what();
+    return "unity::LogicException";
 }
 
 exception_ptr
@@ -95,7 +95,7 @@
 
 ShutdownException::
 ShutdownException(string const& reason)
-    : Exception(make_shared<internal::ShutdownExceptionImpl>(reason))
+    : Exception(make_shared<ExceptionImplBase>(this, reason))
 {
 }
 
@@ -117,7 +117,7 @@
 ShutdownException::
 what() const noexcept
 {
-    return dynamic_cast<internal::ShutdownExceptionImpl*>(pimpl())->what();
+    return "unity::ShutdownException";
 }
 
 exception_ptr
@@ -127,9 +127,25 @@
     return make_exception_ptr(*this);
 }
 
+namespace internal
+{
+
+class FileExceptionImpl : public unity::ExceptionImplBase
+{
+public:
+    FileExceptionImpl(FileException const* owner, string const& reason, int err)
+        : ExceptionImplBase(owner, reason + (err == 0 ? "" : " (errno = " + std::to_string(err) + ")"))
+        , err_(err)
+    {
+    }
+    int err_;
+};
+
+}
+
 FileException::
 FileException(string const& reason, int err)
-    : Exception(make_shared<internal::FileExceptionImpl>(reason, err))
+    : Exception(make_shared<internal::FileExceptionImpl>(this, reason, err))
 {
 }
 
@@ -151,14 +167,14 @@
 FileException::
 what() const noexcept
 {
-    return dynamic_cast<internal::FileExceptionImpl*>(pimpl())->what();
+    return "unity::FileException";
 }
 
 int
 FileException::
 error() const noexcept
 {
-    return dynamic_cast<internal::FileExceptionImpl*>(pimpl())->error();
+    return dynamic_cast<const internal::FileExceptionImpl*>(pimpl())->err_;
 }
 
 exception_ptr
@@ -168,9 +184,25 @@
     return make_exception_ptr(*this);
 }
 
+namespace internal
+{
+
+class SyscallExceptionImpl : public unity::ExceptionImplBase
+{
+public:
+    SyscallExceptionImpl(SyscallException const* owner, string const& reason, int err)
+        : ExceptionImplBase(owner, reason + (reason.empty() ? "" : " ") + "(errno = " + std::to_string(err) + ")")
+        , err_(err)
+    {
+    }
+    int err_;
+};
+
+}
+
 SyscallException::
 SyscallException(string const& reason, int err)
-    : Exception(make_shared<internal::SyscallExceptionImpl>(reason, err))
+    : Exception(make_shared<internal::SyscallExceptionImpl>(this, reason, err))
 {
 }
 
@@ -192,14 +224,14 @@
 SyscallException::
 what() const noexcept
 {
-    return dynamic_cast<internal::SyscallExceptionImpl*>(pimpl())->what();
+    return "unity::SyscallException";
 }
 
 int
 SyscallException::
 error() const noexcept
 {
-    return dynamic_cast<internal::SyscallExceptionImpl*>(pimpl())->error();
+    return dynamic_cast<const internal::SyscallExceptionImpl*>(pimpl())->err_;
 }
 
 exception_ptr
@@ -211,7 +243,7 @@
 
 ResourceException::
 ResourceException(string const& reason)
-    : Exception(make_shared<internal::ResourceExceptionImpl>(reason))
+    : Exception(make_shared<ExceptionImplBase>(this, reason))
 {
 }
 
@@ -233,7 +265,7 @@
 ResourceException::
 what() const noexcept
 {
-    return dynamic_cast<internal::ResourceExceptionImpl*>(pimpl())->what();
+    return "unity::ResourceException";
 }
 
 exception_ptr

=== modified file 'src/unity/internal/CMakeLists.txt'
--- src/unity/internal/CMakeLists.txt	2013-05-13 11:39:49 +0000
+++ src/unity/internal/CMakeLists.txt	2013-06-17 04:58:28 +0000
@@ -1,6 +1,4 @@
 set(UNITY_INTERNAL_SRC
-    ${CMAKE_CURRENT_SOURCE_DIR}/ExceptionImpl.cpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/UnityExceptionsImpl.cpp
 )
 
 set(UNITY_API_LIB_SRC ${UNITY_API_LIB_SRC} ${UNITY_INTERNAL_SRC} PARENT_SCOPE)

=== removed file 'src/unity/internal/ExceptionImpl.cpp'
--- src/unity/internal/ExceptionImpl.cpp	2013-06-12 22:07:05 +0000
+++ src/unity/internal/ExceptionImpl.cpp	1970-01-01 00:00:00 +0000
@@ -1,244 +0,0 @@
-/*
- * Copyright (C) 2013 Canonical Ltd
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the Lesser GNU General Public License version 3 as
- * published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * Lesser GNU General Public License for more details.
- *
- * You should have received a copy of the Lesser GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * Authored by: Michi Henning <[e-mail]>
- */
-
-#include <unity/internal/ExceptionImpl.h>
-#include <unity/Exception.h>
-
-using namespace std;
-
-namespace unity
-{
-
-namespace internal
-{
-
-ExceptionImpl::
-ExceptionImpl(string const& reason)
-    : reason_(reason)
-{
-}
-
-ExceptionImpl::
-~ExceptionImpl() noexcept = default;
-
-string
-ExceptionImpl::
-reason() const
-{
-    return reason_;
-}
-
-namespace
-{
-
-//
-// Return the margin string for the indent level and indent.
-//
-
-string
-get_margin(int indent_level, string const& indent)
-{
-    string margin;
-    for (int i = 0; i < indent_level; ++i)
-    {
-        margin += indent;
-    }
-    return margin;
-}
-
-//
-// Follow the nested exceptions that were rethrown along the call stack, printing them into s.
-//
-
-void
-print_name_and_reason(string& s, nested_exception const& nested)
-{
-    // Add the what() string if this is a std::exception.
-
-    std::exception const* std_exception = dynamic_cast<std::exception const*>(&nested);
-    if (std_exception)
-    {
-        s += std_exception->what();
-    }
-
-    // Add the reason if this is a unity::Exception.
-
-    unity::Exception const* unity_exception = dynamic_cast<unity::Exception const*>(&nested);
-    if (unity_exception)
-    {
-        string reason = unity_exception->reason();
-        if (!reason.empty())
-        {
-            s += ": " + reason;
-        }
-    }
-
-    // Append info about unknown std::exception and std::nested_exception.
-
-    if (!unity_exception)
-    {
-        if (std_exception)
-        {
-            s += " (derived from std::exception and std::nested_exception)";
-        }
-        else
-        {
-            s += "std::nested_exception";
-        }
-    }
-}
-
-void
-follow_nested(string& s, nested_exception const& nested, int indent_level, std::string const& indent)
-{
-    if (nested.nested_ptr())
-    {
-        string margin = get_margin(indent_level, indent);
-
-        s += ":\n";
-        try
-        {
-            nested.rethrow_nested();
-        }
-        catch (std::nested_exception const& e)
-        {
-            unity::Exception const* ge = dynamic_cast<unity::Exception const*>(&e);
-            if (ge)
-            {
-                s += ge->to_string(indent_level + 1, indent);
-            }
-            else
-            {
-                s += margin + indent;
-                print_name_and_reason(s, e);
-                follow_nested(s, e, indent_level + 1, indent);
-            }
-        }
-        catch (std::exception const& e)
-        {
-            s += margin + indent;
-            s += e.what();                                    // Can show only what() for std::exception.
-        }
-        catch (...)
-        {
-            s += margin + indent;
-            s += "unknown exception";                         // Best we can do for an exception whose type we don't know.
-        }
-    }
-}
-
-//
-// Follow the history chain and print each exception in the chain.
-//
-
-void
-follow_history(string& s, int& count, unity::Exception const& e, int indent_level, std::string const& indent)
-{
-    if (!e.get_earlier())
-    {
-        count = 1;  // We have reached the oldest exception; set exception generation count and terminate recursion.
-    }
-    else
-    {
-        try
-        {
-            rethrow_exception(e.get_earlier());
-        }
-        catch (unity::Exception const& e)
-        {
-            // Recurse along the chain until we hit the end, then, as we pop back up the levels, we increment the
-            // count and print it as a generation number for the exception information.
-            // A bit like the "kicks" in "Inception", except that the deepest level is level 1...
-
-            follow_history(s, count, e, indent_level, indent);
-        }
-        ++count;
-    }
-
-    // Show info for this exception.
-
-    s += "\n" + get_margin(indent_level, indent) + "Exception #";
-    s += to_string(count) + ":\n";
-    s += get_margin(indent_level, indent) + indent;
-    print_name_and_reason(s, e);
-    follow_nested(s, e, indent_level + 1, indent);
-}
-
-} // namespace
-
-string
-ExceptionImpl::
-to_string(nested_exception const& nested, int indent_level, string const& indent) const
-{
-    string margin = get_margin(indent_level, indent);
-    string s = margin;
-    s += what();
-
-    string r = reason();
-    if (!r.empty())
-    {
-        s += ": " + r;
-    }
-
-    // Check whether there is an exception history and print each exception in the history.
-
-    unity::Exception const* unity_exception(dynamic_cast<unity::Exception const*>(&nested));
-    if (unity_exception && unity_exception->get_earlier())
-    {
-        s += "\n" + margin + indent + "Exception history:";
-        try
-        {
-            rethrow_exception(unity_exception->get_earlier());
-        }
-        catch (unity::Exception const& e)
-        {
-            int count;
-            follow_history(s, count, e, indent_level + 2, indent);
-        }
-    }
-
-    // Print this and any nested exceptions.
-
-    follow_nested(s, nested, indent_level, indent);
-
-    return s;
-}
-
-exception_ptr
-ExceptionImpl::
-remember(Exception const* env, exception_ptr earlier_exception)
-{
-    // Doesn't prevent loops, but protects against accidental self-assignment.
-
-    if (previous_ != earlier_exception)
-    {
-        previous_ = earlier_exception;
-    }
-    return env->self();
-}
-
-exception_ptr
-ExceptionImpl::
-get_earlier() const noexcept
-{
-    return previous_;
-}
-
-} // namespace internal
-
-} // namespace unity

=== removed file 'src/unity/internal/UnityExceptionsImpl.cpp'
--- src/unity/internal/UnityExceptionsImpl.cpp	2013-06-12 22:07:05 +0000
+++ src/unity/internal/UnityExceptionsImpl.cpp	1970-01-01 00:00:00 +0000
@@ -1,126 +0,0 @@
-/*
- * Copyright (C) 2012 Canonical Ltd
- *
- * This program is free software: you can redistribute it and/or modify
- * it under the terms of the Lesser GNU General Public License version 3 as
- * published by the Free Software Foundation.
- *
- * This program is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * Lesser GNU General Public License for more details.
- *
- * You should have received a copy of the Lesser GNU General Public License
- * along with this program.  If not, see <http://www.gnu.org/licenses/>.
- *
- * Authored by: Michi Henning <[e-mail]>
- */
-
-#include <unity/internal/UnityExceptionsImpl.h>
-
-using namespace std;
-
-namespace unity
-{
-
-namespace internal
-{
-
-InvalidArgumentExceptionImpl::
-InvalidArgumentExceptionImpl(string const& reason)
-    : ExceptionImpl(reason)
-{
-}
-
-char const*
-InvalidArgumentExceptionImpl::
-what() const noexcept
-{
-    return "unity::InvalidArgumentException";
-}
-
-LogicExceptionImpl::
-LogicExceptionImpl(string const& reason)
-    : ExceptionImpl(reason)
-{
-}
-
-char const*
-LogicExceptionImpl::
-what() const noexcept
-{
-    return "unity::LogicException";
-}
-
-ShutdownExceptionImpl::
-ShutdownExceptionImpl(string const& reason)
-    : ExceptionImpl(reason)
-{
-}
-
-char const*
-ShutdownExceptionImpl::
-what() const noexcept
-{
-    return "unity::ShutdownException";
-}
-
-FileExceptionImpl::
-FileExceptionImpl(string const& reason, int err)
-    : ExceptionImpl(reason + (err == 0 ? "" : " (errno = " + std::to_string(err) + ")"))
-    , errno_(err)
-{
-}
-
-char const*
-FileExceptionImpl::
-what() const noexcept
-{
-    return "unity::FileException";
-}
-
-int
-FileExceptionImpl::
-error() const noexcept
-{
-    return errno_;
-}
-
-SyscallExceptionImpl::
-SyscallExceptionImpl(string const& reason, int err)
-    : ExceptionImpl(reason + (reason.empty() ? "" : " ") + "(errno = " + std::to_string(err) + ")")
-    , errno_(err)
-{
-}
-
-char const*
-SyscallExceptionImpl::
-what() const noexcept
-{
-    return "unity::SyscallException";
-}
-
-int
-SyscallExceptionImpl::
-error() const noexcept
-{
-    return errno_;
-}
-
-ResourceExceptionImpl::
-ResourceExceptionImpl(string const& reason)
-    : ExceptionImpl(reason)
-{
-}
-
-char const*
-ResourceExceptionImpl::
-what() const noexcept
-{
-    return "unity::ResourceException";
-}
-
-
-} // namespace internal
-
-} // namespace unity

=== modified file 'src/unity/util/Daemon.cpp'
--- src/unity/util/Daemon.cpp	2013-06-12 22:07:05 +0000
+++ src/unity/util/Daemon.cpp	2013-06-17 04:58:28 +0000
@@ -34,6 +34,11 @@
     return UPtr(new Daemon());
 }
 
+// This is covered by tests, but only when we are not building for coverage.
+// (Closing all file descriptors interferes with the coverage reporting.)
+
+// LCOV_EXCL_START
+
 void
 Daemon::
 close_fds() noexcept
@@ -41,6 +46,8 @@
     p_->close_fds();
 }
 
+// LCOV_EXCL_STOP
+
 void
 Daemon::
 reset_signals() noexcept

=== modified file 'test/gtest/unity/Exceptions_test.cpp'
--- test/gtest/unity/Exceptions_test.cpp	2013-06-12 22:07:05 +0000
+++ test/gtest/unity/Exceptions_test.cpp	2013-06-17 04:58:28 +0000
@@ -17,7 +17,7 @@
  */
 
 #include <unity/UnityExceptions.h>
-#include <unity/internal/UnityExceptionsImpl.h>
+#include <unity/ExceptionImplBase.h>
 
 #include <gtest/gtest.h>
 
@@ -47,6 +47,15 @@
     EXPECT_EQ("unity::SyscallException: blah (errno = 0)", e3.to_string(0, "    "));
     EXPECT_EQ("        unity::SyscallException: blah (errno = 0)", e3.to_string(1, "        "));
     EXPECT_EQ("                unity::SyscallException: blah (errno = 0)", e3.to_string(2, "        "));
+
+    try
+    {
+        throw e;
+    }
+    catch (Exception& e)
+    {
+        EXPECT_STREQ("unity::SyscallException", e.what());
+    }
 }
 
 TEST(Exception, empty_reason)
@@ -250,19 +259,9 @@
         exception_ptr ep = make_exception_ptr(e);
 
         InvalidArgumentException e2("");
-        exception_ptr ep2 = e2.remember(ep);
-        EXPECT_EQ(e2.get_earlier(), ep);
-    }
-
-    {
-        InvalidArgumentException e("");
-        exception_ptr ep = make_exception_ptr(e);
-
-        InvalidArgumentException e2("");
-        exception_ptr ep2 = e2.remember(ep);
-        EXPECT_EQ(e2.get_earlier(), ep);
-    }
-
+        e2.remember(ep);
+        EXPECT_EQ(e2.get_earlier(), ep);
+    }
 
     // Check that we are following the history chain.
 
@@ -297,7 +296,6 @@
         }
     }
 
-
     // Same test, but this time with nested exceptions in the history.
 
     {
@@ -534,3 +532,105 @@
         delete ep;
     }
 }
+
+class StatelessException : public unity::Exception
+{
+public:
+    explicit StatelessException(std::string const& reason)
+        : Exception(make_shared<ExceptionImplBase>(this, reason))
+    {
+    }
+    explicit StatelessException(std::shared_ptr<ExceptionImplBase> const& derived)
+        : Exception(derived)
+    {
+    }
+    StatelessException(StatelessException const&) = default;
+    StatelessException& operator=(StatelessException const&) = default;
+    virtual ~StatelessException() noexcept {}
+
+    virtual char const* what() const noexcept override
+    {
+        return "StatelessException";
+    }
+
+    virtual std::exception_ptr self() const override
+    {
+        return make_exception_ptr(*this);
+    }
+
+};
+
+TEST(Derivation, stateless_derivation)
+{
+    StatelessException e("test");
+    EXPECT_EQ("test", e.reason());
+    EXPECT_STREQ("StatelessException", e.what());
+}
+
+namespace Impl
+{
+class StatefulExceptionImpl;
+}
+
+class StatefulException : public unity::Exception
+{
+public:
+    StatefulException(std::string const& reason, int state);
+    StatefulException(std::shared_ptr<ExceptionImplBase> const& derived)
+        : Exception(derived)
+    {
+    }
+    StatefulException(StatefulException const&) = default;
+    StatefulException& operator=(StatefulException const&) = default;
+    virtual ~StatefulException() noexcept {}
+
+    virtual char const* what() const noexcept override
+    {
+        return "StatefulException";
+    }
+
+    virtual std::exception_ptr self() const override
+    {
+        return make_exception_ptr(*this);
+    }
+
+};
+
+namespace Impl
+{
+
+class StatefulExceptionImpl : public unity::ExceptionImplBase
+{
+public:
+    StatefulExceptionImpl(StatefulException const* owner, string const& reason, int state)
+        : ExceptionImplBase(owner, reason + " state = " + std::to_string(state))
+        , state_(state)
+    {
+    }
+    int state_;
+};
+
+}
+
+StatefulException::
+StatefulException(std::string const& reason, int state)
+    : Exception(make_shared<Impl::StatefulExceptionImpl>(this, reason, state))
+{
+}
+
+TEST(Derivation, stateful_derivation)
+{
+    StatefulException e("test", 99);
+    EXPECT_EQ("test state = 99", e.reason());
+    EXPECT_STREQ("StatefulException", e.what());
+}
+
+#if 0
+
+TEST(Derivation, two_level_derivation)
+{
+    StatefulException e("test", 99);
+    EXPECT_EQ("test state = 99", e.reason());
+    EXPECT_STREQ("StatefulException", e.what());
+}
+#endif