DEV Community: Helio Nunes Santos

How I am handling errors in a freestanding environment

Helio Nunes Santos — Thu, 05 May 2022 23:22:03 +0000

Introduction

Hi guys!

It has been a good while since I have written anything (well, I actually have written an article just once), but as I have gotten inspiration from a myriad of things recently, I have decided to start writing more, to showcase what I am working on and receive feedback on my code.

I will tell you guys a small story and then we can proceed to the meat. If you want, you can skip the next part.

The story behind it

I have recently discovered the RISC-V ISA, which is an open instruction set architecture. With the RISC-V ISA if you want to develop a new CPU that supports the architecture. you don't have to pay royalties to anyone and, for me at least, it sounds amazing! It can also open doors to endless possibilities if the architecture succeeds and is widely adopted and produced, given that not paying royalties could be another factor in decreasing the cost of CPUs, which in turn can encourage more innovation (not that we are not facing any currently).

Given my interest in the architecture and its proposed benefits, I have decided to take my time to develop a small kernel for it. I am not being the first one to do so, but I have decided to do this as a challenge to myself, given that developing a kernel is not an easy task and it is going to make me get a good grasp of a lot of Computer Science concepts. As the architecture doesn't have to be compatible with anything developed more than 40 years ago (cough cough x86), it is easier to have it as a target for a brand new kernel.

Right at the beginning of developing the kernel, I had to figure out a way of dealing with errors. Given that my kernel gets the address of the Device Tree (a structure used to describe the system's physical hardware) from the arguments that are passed to its start function, I have to read the arguments and parse the value which contains the address in hexadecimal for the Flattened Device Tree.

Given that I am in a freestanding environment, I have to implement from scratch almost everything, which includes a routine to parse a string that contains (or not) a value in hexadecimal.

Now, how can I handle errors? An example would be when the user supplies garbage instead of an hexadecimal value.

In a freestanding environment, there are no exceptions, so using them is ruled out.

One idea would be to determine certain values as errors, which is how a lot of softwares developed in C do. But I would have to say that it is not the ideal solution, given that, for example, if I get 0 as the value to indicate an error, how can I be sure that the user really didn't give 0 as an argument? Surely, for the address of the Device Tree, 0 wouldn't be a valid value, but I will be reusing the routine to parse hexadecimals in other cases as well, and 0 might be a valid value. Of course, when applicable, I could simply check if it is a value that represent an error, but this would demand developing a different logic for errors each time, which can be tiresome and bug prone.

I could also use retrieve errors from global variables, but I am planning to support multi-threading in the future, so this option would add unnecessary complexity to my code.

As this small case has given me food for thought, I remembered of a talk I have seen a while ago and decided to go with the idea presented. We are using a multi-paradigm programming language, so why not take advantage of this?
We can simply have a safe union that indicates whether we have a value or an error and contains either of both. Doing like this, we don't have to reserve a value to indicate an error, and it helps us to handle the error logic separately, given that we have a whole range of values to use as error values!

How I am doing it

So, for handling errors, I am using a small class that I called ValueOrError. It has a simple interface which allows the user to know if what it holds is either a value or an error value and get what it holds accordingly.

To make it more expressive and easier for the user, I had to define a class called GenericWrapper, which is a wrapper over a value.

Here is the preamble of the header file which contains the class ValueOrError. This preamble contains a few declarations (that will be explained later) and the definition of the class GenericWrapper.

#include <utility>
#include <type_traits>

namespace hls {

    template<typename, typename>
    class ValueOrError;

    template<typename T, int x>
    class GenericWrapper;

    template<typename T>
    using ErrorType = GenericWrapper<T, 0>;

    template<typename T>
    using ValueType = GenericWrapper<T, 1>;

    template<typename T, int x>
    class GenericWrapper {
        T v;
        GenericWrapper(T&& a) : v(std::forward<T>(a)) {};
        GenericWrapper(const T& a) : v(a) {};
        GenericWrapper(const GenericWrapper&) = default;
        GenericWrapper(GenericWrapper&&) = default;
    public:
        ~GenericWrapper() = default;

        template<typename, typename>
        friend class ValueOrError;

        template<typename U>
        friend auto error(U&& error) -> ErrorType<std::remove_cvref_t<U>>;

        template<typename U>
        friend auto value(U&& value) -> GenericWrapper<std::remove_cvref_t<U>, 1>;

    };

    // Remaining of the file...
}

Have you seen the declaration of those two friend functions at the bottom? These two are the ones that will help giving more expressiveness to the code! Have you also seen the using declarations for ErrorType and ValueType? I will be taking advantage of the C++ type system to conform with DRY (Don't repeat yourself).

Whenever a user wants to return a value or an error, they can simply do:

#define ERROR_FOR_REASON_X 10
ValueOrError<int, int> my_function(int input_value) {
    // Do stuff based on input_value
    // Nice, we didn't get an error
    if(all_good)
        return hls::value(10);
    // Oh no, we got an error
    else 
        return hls::error(ERROR_FOR_REASON_X);
}

Have you seen that we used the same value for the return value and for the reason of the error? That is where our class ValueOrError comes. Here is the remaining of the file:

    template<typename T>
    auto error(T&& error) -> ErrorType<std::remove_cvref_t<T>> {
        return {std::forward<T>(error)};
    }

    template<typename T>
    auto value(T&& value) -> ValueType<std::remove_cvref_t<T>> {
        return {std::forward<T>(value)};
    }

        template<typename T, typename ErrorT = int>
    class ValueOrError {
        using Type = std::remove_cvref_t<T>;
        using Error = std::remove_cvref_t<ErrorT>;

        union {
            Type value;
            Error error;
        } m_stored;
        bool m_is_error = false;
    public:

        template<typename U>
        requires (std::is_same_v<std::remove_cvref_t<std::remove_pointer_t<U>>, std::remove_cvref_t<std::remove_pointer_t<T>>>)
        ValueOrError(ValueType<U>&& value) {
            new(&m_stored.value)T(std::move(value.v));
        }

        template<typename U>
        requires (std::is_same_v<std::remove_cvref_t<std::remove_pointer_t<U>>, std::remove_cvref_t<std::remove_pointer_t<ErrorT>>>)
        ValueOrError(ErrorType<U>&& error) {
            m_is_error = true;
            new(&m_stored.error)ErrorT(std::move(error.v));
        }

        ~ValueOrError() {
            if(is_error())
                m_stored.error.~ErrorT();
            else
                m_stored.value.~T();
        }

        ValueOrError(const ValueOrError& other) {
            if(other.is_error()) {
                m_is_error = true;
                m_stored.error = other.get_error();
            }
            else {
                m_stored.value = other.get_value();
            } 
        }

        ValueOrError(ValueOrError&& other) {
            if(other.is_error()) {
                m_is_error = true;
                m_stored.error = std::move(other.get_error());
            }
            else {
                m_stored.value = std::move(other.get_value());
            }
        }

        bool is_error() const {
            return m_is_error;
        }

        bool is_value() const {
            return !is_error();
        }

        T& get_value() {
            const auto& as_const = *this;
            return const_cast<T&>(as_const.get_value());
        }

        const T& get_value() const {
            return m_stored.value;
        }

        ErrorT& get_error() {
            const auto& as_const = *this;
            return const_cast<ErrorT&>(as_const.get_error());
        }

        const ErrorT& get_error() const {
            return m_stored.error;
        }
    };

}

As you can see, the class ValueOrError takes advantage of the fact that using a different value for the template argument creates a different type, which causes the compiler to call the proper constructor. Note also that we have the requires clause as to disallow unintentional type conversion. Without it, you could say hls::value(10.0f) instead of hls::value(10) and it would work. If this is desired, a cast then should be used.

Note that the classes take advantage of move semantics, so the compiler should be able to optimize all of it.

Last but not least, I will be producing a small example with the usage of it:

#include <iostream>
#include <iomanip>
#include "valerror.hpp"

// When not specified, a enum defaults to an int
enum ERROR_CODE {
    INVALID_STRING,
    NOT_AN_HEX_VALUE,
    VALUE_TOO_LARGE
};

hls::ValueOrError<int, ERROR_CODE> hex_to_int(const char* hex_string) {
    if(hex_string == nullptr)
        return hls::error(INVALID_STRING);

    bool is_hex_value;
    // Code that checks if is an hex value
    // ...
    if(!is_hex_value)  
        return hls::error(NOT_AN_HEX_VALUE);

    int required_bit_size;
    // Code that checks if the hex value fits in an int
    // ...
    if(required_bit_size > 32) 
        return hls::error(VALUE_TOO_LARGE);

    int result;
    // Code that converts it to an int
    return hls::value(result); 
};


int main() {

    while(true) {
        std::cout << "Please, provide an hex value that fits in a 32 bits integer: \n";
        std::string user_input;

        std::cin >> user_input;

        auto result = hex_to_int(user_input.c_str());

        if(result.is_error()) {
            switch(result.get_error()) {
                case INVALID_STRING:
                    std::cout << "The pointer to the string was nullptr\n";
                    break;
                case NOT_AN_HEX_VALUE:
                    std::cout << "The user input was not an hex value\n";
                    break;
                case VALUE_TOO_LARGE:
                    std::cout << "The value the user has given doesn't fit in a 32 bit integer.\n";
                    break;
            }
        }
        else {
            std::cout << "The user input was: " << std::setbase(16) << result.get_value() << "\n";
            break;
        }    

    }   
}

And that is it guys. I hope everything was clear. I would also like to have your feedback on improvement and suggestions, be it on my code or my writing. Thank you and see you soon!

If you want to get in touch with me, add me on LinkedIn:
https://www.linkedin.com/in/heliobatimarqui/

Compile time type id with templates (C++)

Helio Nunes Santos — Mon, 28 Dec 2020 02:17:38 +0000

The issue:

Another day while developing my game engine I had to handle events (which inherited from a common interface). The problem was that handling different event types with RTTI is not good in this case, as it is expensive. If-else statements were quite convoluted, so switch statement to the rescue.

The problem is that a switch statement requires all values to be known at compile time. Enums could be a solution, but IMO they are messy and have a wide margin for errors.

I ended up with a solution that uses TypeLists and CRTP to attribute different ids for the listed types.

A solution:

First, let's define our TypeList (create a file called TypeList.h):



//Typelist.h
#include <cstddef>
using id_type = int;
template <typename... Ts> class TypeList;

template <> class TypeList<> {
public:
    //This will be useful later
    static constexpr id_type id = -1; // -1 means invalid 
    template <typename T> static constexpr id_type index_of() { return id; }
};

template <typename T, typename... Ts> class TypeList<T, Ts...> {
    using remaining_types = TypeList<Ts...>;  
    static constexpr id_type id = sizeof...(Ts);

    template<typename U, bool dummy> 
    struct Helper {
        static constexpr id_type value = remaining_types::template index_of<U>();  
    };

    template<bool dummy>
    struct Helper<T, dummy> {
        static constexpr id_type value = id;
    };

public:

  // Returns -1 when the type is not found
  template <typename F> static constexpr id_type index_of() {
      return Helper<F, true>::value;
  };

};

We leverage variadic templates here. The empty parameter specialization is easy (and will prove useful later). An empty type list can't return a valid id for a type as it doesn't list anything.

The second specialization is not complicated either. A type id is the count of the remaining parameters. The trick here is in the function index_of(). When F and T are of the same type, the specialized struct Helper will be instantiated, thus it's value will be equal to the current type id. When different, it will query the next level for the type id. If not found, the last level is our empty specialization, which returns an invalid id.

The standard doesn't allow full specialization of class templates inside other classes, but allows partial specialization, hence the use of the dummy bool parameter.

It's crucial that all values and expressions are available at compile time, thus the use of constexpr (it also allows us to define the value inside the class).

A nice thing about templates is that we can offer some guarantees for the user. One that I find useful is guaranteeing one id per type. If the user tries to insert the same type twice, static_assert will be triggered.

Let's implement our "parameter checker" helper:



//Typelist.h
/* Headers included before */
#include <type_traits>
/* ... declarations ... */

template <typename... Ts> class HasRepeatedParameter;

template <typename T, typename... Ts> class HasRepeatedParameter<T, T, Ts...> {
public:
  static constexpr bool value = true;
};

template <typename T1, typename T2, typename... Ts> class HasRepeatedParameter<T1, T2, Ts...> {
public:
  static constexpr bool value = HasRepeatedParameter<T1, Ts...>::value || HasRepeatedParameter<T2, Ts...>::value;
};

template <typename T> class HasRepeatedParameter<T> {
public:
  static constexpr bool value = false;
};

It works by instantiating recursively itself and the specializations do the job for us.

Notice that it doesn't check against a qualified (const, volatile) types. It's out of the scope of this article and would add unnecessary complexity for our goal. Maybe the reader can try to tweak it to check for qualified types as an exercise.

Back to our TypeList class:



//Typelist.h
/* ... Headers and declarations/definitions... */

template <typename T, typename... Ts> class TypeList<T, Ts...> {
    // Here we have our check
    static_assert(!HasRepeatedParameter<T, Ts...>::value, "TypeList can't have repeated parameters");
    /* ... Definition ...*/
};

I mentioned that I have used it on my game engine Event system, so the example I'll give will be in the same line.

Let's define our Event classes (create a file called Events.h):



//Events.h
#include <iostream>
#include "TypeList.h"

class MouseEvent;
class KeyboardEvent;
class JoystickEvent;

using EngineEvents = TypeList<MouseEvent, KeyboardEvent, JoystickEvent>;

Nothing too special. We just defined our TypeList. The forward declarations above are required, but they come with something cool. If you ever need to erase one type you can substitute it for a mock type and the other ones after it will still have the same id.

Still on the same file:



//Events.h
/* ... */
// Our interface

class IEvent {
  protected:
  IEvent() = default;
  public:
  virtual ~IEvent() = default;
  virtual const id_type get_id() const = 0;
};

// Here is where the magic happens.
template<typename Event>
class EngineEvent : public IEvent {
  static_assert(EngineEvents::index_of<Event>() != -1, "Event not at the EngineEvents list");
  EngineEvent() = default;
  virtual ~EngineEvent() = default;

// Incorrect inheritance will cause the compilation to fail, thus avoiding two events with the same id.
  friend Event;
public:

  const id_type get_id() const override {
    return id;
  }

  static constexpr id_type id = EngineEvents::index_of<Event>();
};

//Our different Events.
class MouseEvent : public EngineEvent<MouseEvent> {
  public:
  void do_mouse_event_stuff() const {
    std::cout << "Doing MouseEvent stuff\n";
  };
};

class KeyboardEvent : public EngineEvent<KeyboardEvent> {
  public:
  void do_keyboard_event_stuff() const {
    std::cout << "Doing KeyboardEvent stuff\n";
  };
};

class JoystickEvent : public EngineEvent<JoystickEvent> {
  public:
  void do_joystick_event_stuff() const {
    std::cout << "Doing JoystickEvent stuff\n";
  };
};

The class IEvent is the interface. A const reference to a IEvent is what our handler function will have as a parameter, thus not knowing anything beforehand about the object.

The template class EngineEvent is where the magic happens. It defines an id value which is simply the index of our Event type on the EngineEvents list. This value will be available on our Event classes, as they will inherit from it. Note that in case a given event is not listed on the EngineEvents list a static_assert will be triggered, failing compilation.

The remaining classes are our Event classes. They simply inherit from EngineEvent giving themselves as a template parameter (CRTP).

Usage:

Now define a file called main.cpp with the following content:



#include "Events.h"

void handle_event(const IEvent& e) {
  switch(e.get_id()) {
    case MouseEvent::id:
      static_cast<const MouseEvent&>(e).do_mouse_event_stuff();
      break;
    case KeyboardEvent::id:
      static_cast<const KeyboardEvent&>(e).do_keyboard_event_stuff();
      break;
    case JoystickEvent::id:
      static_cast<const JoystickEvent&>(e).do_joystick_event_stuff();
      break;
    default:
      std::cout << "Event not recognized.\n";
  }
}

int main() {
  MouseEvent m;
  KeyboardEvent k;
  JoystickEvent j;

  handle_event(m);
  handle_event(k);
  handle_event(j);

  return 0;
}

If you did everything right you should have the following output:

Conclusion:

This is just one of the many possible solutions for the given problem. I like it because it is simple, doesn't introduce dependencies and is less prone to errors than Enums (different values for the same type being the main one).

The full code is available at GitHub.

It's worthy noting that I tested it on G++ version 10.2.1 with the option -std=c++11.

I hope you that you enjoyed it and learned something today. This is my first time posting something related to programming, so any feedback (positive or negative) would be really appreciated. Thank you!