DataIO.hpp

/******************************************************************************
* Copyright (c) ATTX LLC 2024. All Rights Reserved.
*
* This software and associated documentation (the "Software") are the 
* proprietary and confidential information of ATTX, LLC. The Software is 
* furnished under a license agreement between ATTX and the user organization 
* and may be used or copied only in accordance with the terms of the agreement.
* Refer to 'license/attx_license.adoc' for standard license terms.
*
* EXPORT CONTROL NOTICE: THIS SOFTWARE MAY INCLUDE CONTENT CONTROLLED UNDER THE
* INTERNATIONAL TRAFFIC IN ARMS REGULATIONS (ITAR) OR THE EXPORT ADMINISTRATION 
* REGULATIONS (EAR99). No part of the Software may be used, reproduced, or 
* transmitted in any form or by any means, for any purpose, without the express 
* written permission of ATTX, LLC.
******************************************************************************/
/*
Data IO Header File
 
Author: Alex Reynolds
*/
#ifndef DATA_IO_HPP
#define DATA_IO_HPP
 
#include <type_traits>
 
#include "DataIOBase.h"
#include "core/clockwerkerrors.h"
#include "logging/SimLogger.h"
 
namespace clockwerk {
 
    /// @brief   Class for inter-object communication
    /// 
    /// The data IO object is a flexible input/output object for interfacing 
    /// between models, tasks, events, and so on. It is templated to work
    /// with nearly any data type, provided that type can be passed and returned
    /// via function. 
    /// 
    /// DataIO operates by abstracting data using a pointer. It holds an internal
    /// value of type T, and a pointer to the data source to use. By default, that
    /// data source is itself, but it may point to another DataIO object if
    /// commanded to do so via the mapTo function. In that case, DataIO will 
    /// recursively call DataIO objects until it finds the root object, then return
    /// the value held by the root object.
    template <typename T>
    class DataIO : public DataIOBase {
    public:
        /// @brief   Constructor for the DataIO object
        /// @param   data_parent     Pointer to parent graph tree object
        /// @param   data_name       String name for the DataIO object
        /// @param   initial_value   The initial value of the data IO object
        /// @note    Constructor is overloaded -- object can be created from many
        ///          configurations but it is on the developer to ensure it is handled correctly
        DataIO(GraphTreeObject* data_parent, std::string data_name, T initial_value);
        DataIO(GraphTreeObject* data_parent, std::string data_name);
        DataIO(GraphTreeObject* data_parent);
        DataIO();
        ~DataIO() {};
 
        /// @brief Function to map the DataIO object to a pointer, rather than another of its kind
        /// @param data_source The pointer to which the DataIO will be mapped
        void mapToPointer(T* data_source) {_data_ptr = data_source; data = this; _writeAllowed = true; _root = true;}
 
        /// @brief   Function to set the value of the DataIO object
        /// @param   new_value   Value to set the dataIO object to
        /// @return  Error code according to success/failure
        int operator()(const T &new_value);
 
        /// @brief   Function to return a handle to the root data held in THIS object
        /// @return  A pointer to root data if write is allowed, nullptr if not
        /// @note    DANGER! This method bypasses a lot of safeties in the signal system and breaks
        ///          traceability on pointer. Using this could allow a write to the wrong location
        ///          or read from the wrong location. It should be not be used in models and should be
        ///          reserved exclusively for built-in functions.
        T* getRootDataPointer();
 
        /// @param   Function to break data mapping and reset object to its own internal data
        /// @note    Data will be reset to the value previously held by this signal prior to mapping
        /// @note    Resets write permission to true
        void resetMap() {_data_ptr = &_root_data; DataIOBase::resetMap();}
 
        /// @brief   Overloaded operator to return value of DataIO object
        /// @return  Value pointed to by data -- could be internal or external
        const T& operator()();
 
        /// @brief   Function to log data to a logger
        /// @param   logger  Pointer to logger
        /// @return  Error code corresponding to success/failure
        int log(void* logger);
 
        /// @brief   Function to pass headers for this object to the logger
        /// @param   logger  Pointer to logger
        /// @return  Error code corresponding to success/failure
        int header(void* logger);
    protected:
        /// Default data location pointed to by the DataIO object. Note that root
        /// data can change if DataIO is mapped to another dataIO object
        T _root_data;
 
        /// Temporary pointer to hold our stuff internally
        void* tmp_ptr;
    };
 
    template <typename T>
    int DataIO<T>::log(void* logger) {
        return ((SimLogger*)logger)->writeToBuffer(*getRootDataPointer());
    }
 
    template <typename T>
    int DataIO<T>::header(void* logger) {
        return ((SimLogger*)logger)->writeHeaders(*getRootDataPointer());
    }
 
    template <typename T>
    int DataIO<T>::operator()(const T &new_value) {
        /// Get a pointer to the data we're writing to
        tmp_ptr = writePtr();
 
        /// Now cast to our type and return the value
        if(tmp_ptr == nullptr) {
            return ERROR_WRITE_PERMISSION;
        }
        *(T*)tmp_ptr = new_value;
 
        return NO_ERROR;
    }
 
    template <typename T>
    const T& DataIO<T>::operator()() {
        return *(T*)read();
    }
 
    template <typename T>
    DataIO<T>::DataIO(GraphTreeObject* data_parent, std::string data_name, T initial_value)
        : _root_data(initial_value) {
 
        DataIOBase::_data_ptr = &_root_data;
 
        /// Assign parent to object
        DataIOBase::parent(data_parent);
        DataIOBase::name(data_name);
 
        /// Now identify our data type
        _typeID(_root_data);
 
        _loggable = true;
    }
 
    template <typename T>
    DataIO<T>::DataIO(GraphTreeObject* data_parent, std::string data_name)
        : _root_data() {
 
        DataIOBase::_data_ptr = &_root_data;
 
        /// Assign parent to object
        DataIOBase::parent(data_parent);
        DataIOBase::name(data_name);
 
        /// Now identify our data type
        _typeID(_root_data);
 
        _loggable = true;
    }
 
    template <typename T>
    DataIO<T>::DataIO(GraphTreeObject* data_parent)
        : _root_data() {
 
        DataIOBase::_data_ptr = &_root_data;
 
        /// Assign parent to object
        DataIOBase::parent(data_parent);
 
        /// Now identify our data type
        _typeID(_root_data);
 
        if(_type_id == POINTER || _type_id == UNDEFINED) {
            _loggable = true;
        } else {
            _loggable = true;
        }
    }
 
    template <typename T>
    DataIO<T>::DataIO()
        : _root_data() {
            DataIOBase::_data_ptr = &_root_data;
 
        /// Now identify our data type
        _typeID(_root_data);
 
        _loggable = true;
    }
 
    template <typename T>
    T* DataIO<T>::getRootDataPointer() {
        return (T*)DataIOBase::read();
    }
 
}
 
#endif