ExternalArray.hpp

Go to the documentation of this file.

// ======================================================================
// \file   ExternalArray.hpp
// \author bocchino
// \brief  A bounds-checked array with external memory
// ======================================================================

#ifndef Fw_ExternalArray_HPP
#define Fw_ExternalArray_HPP

#include <cstdint>
#include <new>
#include <type_traits>

#include "Fw/FPrimeBasicTypes.hpp"
#include "Fw/Types/Assert.hpp"
#include "Fw/Types/ByteArray.hpp"

namespace Fw {

template <typename T>
class ExternalArray final {
    // ----------------------------------------------------------------------
    // Static assertions
    // ----------------------------------------------------------------------

    static_assert(std::is_assignable<T&, T>::value, "T must be assignable to T&");

  public:
    // ----------------------------------------------------------------------
    // Public constructors and destructors
    // ----------------------------------------------------------------------

    ExternalArray() {}

    ExternalArray(T* elements,     
                  FwSizeType size  
                  )
        : m_elements(elements), m_size(size) {}

    ExternalArray(ByteArray data,  
                  FwSizeType size  
    ) {
        this->setStorage(data, size);
    }

    ExternalArray(const ExternalArray<T>& a) : m_elements(a.m_elements), m_size(a.m_size) {}

    ~ExternalArray() { this->releaseStorage(); }

  public:
    // ----------------------------------------------------------------------
    // Public member functions
    // ----------------------------------------------------------------------

    T& operator[](const FwSizeType i  
    ) {
        FW_ASSERT(this->m_elements != nullptr);
        FW_ASSERT(i < this->m_size, static_cast<FwAssertArgType>(i));
        return this->m_elements[i];
    }

    const T& operator[](const FwSizeType i  
    ) const {
        FW_ASSERT(this->m_elements != nullptr);
        FW_ASSERT(i < this->m_size, static_cast<FwAssertArgType>(i));
        return this->m_elements[i];
    }

    ExternalArray<T>& operator=(const ExternalArray<T>& a) {
        if (&a != this) {
            this->setStorage(a.m_elements, a.m_size);
        }
        return *this;
    }

    void copyDataFrom(const ExternalArray<T>& a) {
        const FwSizeType size = FW_MIN(this->m_size, a.m_size);
        for (FwSizeType i = 0; i < size; i++) {
            (*this)[i] = a[i];
        }
    }

    T* getElements() { return this->m_elements; }

    const T* getElements() const { return this->m_elements; }

    FwSizeType getSize() const { return this->m_size; }

    void setStorage(T* elements,     
                    FwSizeType size  
    ) {
        // Check that elements is not null if the array is nonempty
        FW_ASSERT((elements != nullptr) || (size == 0), static_cast<FwAssertArgType>(size));
        if (elements == this->m_elements) {
            // The incoming pointer aliases the existing storage, so do not
            // release the storage or change the ownership flag
            this->m_size = size;
        } else {
            this->releaseStorage();
            this->m_elements = elements;
            this->m_size = size;
            this->m_destroyElementsOnRelease = false;
        }
    }

    void setStorage(ByteArray data,  
                    FwSizeType size  
    ) {
        // Check that data.bytes is not null
        FW_ASSERT(data.bytes != nullptr);
        // Check that data.bytes is properly aligned
        FW_ASSERT(reinterpret_cast<uintptr_t>(data.bytes) % alignof(T) == 0);
        // Check that data.size is large enough to hold the array
        // The division form is used because size * sizeof(T) can overflow FwSizeType
        FW_ASSERT(size <= data.size / sizeof(T));
        // Release the backing storage
        this->releaseStorage();
        // Initialize the array members
        this->m_elements = reinterpret_cast<T*>(data.bytes);
        // Construct the array members in place
        // This step ensures that each array element holds a valid object
        // into which we can assign data
        for (FwSizeType i = 0; i < size; i++) {
            // This code trips an alignment check in clang-tidy
            // However the alignment has been checked by FW_ASSERT above
            (void)new (&this->m_elements[i]) T();  // NOLINT
        }
        // Set the size
        this->m_size = size;
        // Destroy elements on release of storage
        this->m_destroyElementsOnRelease = true;
    }

  public:
    // ----------------------------------------------------------------------
    // Public static functions
    // ----------------------------------------------------------------------

    static constexpr U8 getByteArrayAlignment() { return alignof(T); }

    static constexpr FwSizeType getByteArraySize(FwSizeType size  
    ) {
        return size * sizeof(T);
    }

  private:
    // ----------------------------------------------------------------------
    // Private member functions
    // ----------------------------------------------------------------------

    void releaseStorage() {
        if ((this->m_elements != nullptr) && this->m_destroyElementsOnRelease) {
            for (FwSizeType i = 0; i < this->m_size; i++) {
                this->m_elements[i].~T();
            }
            this->m_destroyElementsOnRelease = false;
        }
    }

  private:
    // ----------------------------------------------------------------------
    // Private member variables
    // ----------------------------------------------------------------------

    T* m_elements = nullptr;

    FwSizeType m_size = 0;

    bool m_destroyElementsOnRelease = false;
};

}  // namespace Fw

#endif