src/util/hei_flyweight.hpp

#pragma once

#include <stdint.h>
#include <algorithm>
#include <vector>

namespace libhei
{

/** @brief A generic flyweight factory for objects of type T. */
template <class T>
class Flyweight
{
  private: // This class cannot be instantiated. Use getSingleton() instead.

    /** @brief Default constructor. */
    Flyweight() = default;

    /** @brief Destructor. */
    ~Flyweight() { clear(); }

    /** @brief Default copy constructor. */
    Flyweight(const Flyweight &) = delete;

    /** @brief Default assignment operator. */
    Flyweight & operator=(const Flyweight &) = delete;

  public:

    /** @brief Provides access to a singleton instance of this object. */
    static Flyweight & getSingleton()
    {
        static Flyweight theFlyweight;
        return theFlyweight;
    }

    /**
     * @brief  Adds the given entry to the factory, if it does not already
     *         exist. Then returns a reference to that entry in the factory.
     * @param  The target entry.
     * @return A reference to this entry in the factory.
     */
    T & get(const T & i_entry)
    {
        // The index is sorted by the value of the T objects. Check to see if
        // this entry already exists in the factory.
        auto itr =
            std::lower_bound(iv_index.begin(), iv_index.end(), &i_entry,
                             [](const T * a, const T * b) { return *a < *b; });

        // std::lower_bound() will return the first element that does not
        // compare less than i_entry. So if an entry is found, we must make sure
        // it does not have the same value as i_entry.
        if (iv_index.end() == itr || !(i_entry == *(*itr)))
        {
            // Create a new entry and store the pointer in the sorted index.
            itr = iv_index.insert(itr, new T { i_entry });
        }

        // Return a reference to this entry in the factory.
        return *(*itr);
    }

    /**
     * @brief Deletes all entries in the factory.
     *
     * This is called in the destructor. So it cannot throw an exception.
     */
    void clear()
    {
        for (auto i : iv_index) { delete i; }
        iv_index.clear();
    }

    /**
     * @brief Shrinks the index capacity to eliminate unused memory space.
     *
     * The index is a vector where the capacity will grow as items are added to
     * it. Each time more capacity is needed, the vector will double the current
     * capacity to make room for new entries. The general use of this class is
     * expected that all needed entries will be added during the isolator
     * initialization. Afterwards, the extra capacity is not needed. So this
     * function will shrink the capacity to the size of the vector.
     */
    void compact() { iv_index.shrink_to_fit(); }

  private:

    /**
     * Each new T is allocated on the memory heap and a pointer to each of those
     * objects is stored in this vector. The vector will not contain duplicates
     * and is kept sorted by the value of the objects. Inserting a new element
     * is O(n). However, since the vector is sorted, searching for existing
     * entries is O(log n). Considering the expected use of this class,
     * insertion should only exist during initialization of the isolator, where
     * searching will be done at the time of isolation when performance is more
     * important.
     *
     * An alternative to this approach is to use std::set, where insertion and
     * searching are both O(log n). However, std::set is typically designed with
     * a red-black tree which carries a lot of extra memory overhead to maintain
     * the structure. Also, the Hostboot user application does not support
     * std::set at this time.
     */
    std::vector<T*> iv_index;
};

} // end namespace libhei