mtsStateTable.h

Go to the documentation of this file.

/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-    */
/* ex: set filetype=cpp softtabstop=4 shiftwidth=4 tabstop=4 cindent expandtab: */
 
/*
  Author(s):  Ankur Kapoor, Min Yang Jung, Peter Kazanzides
  Created on: 2004-04-30
 
  (C) Copyright 2004-2025 Johns Hopkins University (JHU), All Rights Reserved.
 
--- begin cisst license - do not edit ---
 
This software is provided "as is" under an open source license, with
no warranty.  The complete license can be found in license.txt and
http://www.cisst.org/cisst/license.txt.
 
--- end cisst license ---
*/
 

 
#ifndef _mtsStateTable_h
#define _mtsStateTable_h
 
#include <cisstCommon/cmnGenericObject.h>
#include <cisstCommon/cmnClassRegisterMacros.h>
#include <cisstMultiTask/mtsForwardDeclarations.h>
#include <cisstMultiTask/mtsStateArrayBase.h>
#include <cisstMultiTask/mtsStateArray.h>
#include <cisstMultiTask/mtsStateIndex.h>
#include <cisstMultiTask/mtsFunctionVoid.h>
#include <cisstMultiTask/mtsFunctionRead.h>
#include <cisstMultiTask/mtsFunctionWrite.h>
#include <cisstMultiTask/mtsIntervalStatistics.h>
 
 
#include <vector>
#include <iostream>
 
// Always include last
#include <cisstMultiTask/mtsExport.h>
 
// Forward declaration
class osaTimeServer;
 

typedef int mtsStateDataId;

class CISST_EXPORT mtsStateTable: public cmnGenericObject {
 
    CMN_DECLARE_SERVICES(CMN_NO_DYNAMIC_CREATION, CMN_LOG_ALLOW_DEFAULT);
 
    friend class mtsCollectorState;
    friend class mtsComponent;
    friend class mtsTaskTest;
    friend class mtsStateTableTest;
    friend class mtsCollectorBaseTest;
 
 public:
    class CISST_EXPORT IndexRange: public mtsGenericObject
    {
        CMN_DECLARE_SERVICES(CMN_DYNAMIC_CREATION, CMN_LOG_ALLOW_DEFAULT);
    public:
        mtsStateIndex First;
        mtsStateIndex Last;
 
        void ToStreamRaw(std::ostream & outputStream, const char delimiter = ' ',
                         bool headerOnly = false, const std::string & headerPrefix = "") const override;
    };

    class DataCollectionInfo {
    public:
        bool Collecting;

        double StartTime;

        double StopTime;

        mtsStateTable::IndexRange BatchRange;

        size_t BatchSize;

        size_t BatchCounter;

        size_t CounterForEvent;

        double TimeIntervalForProgressEvent;

        double TimeOfLastProgressEvent;

        mtsFunctionWrite BatchReady;

        mtsFunctionVoid CollectionStarted;

        mtsFunctionWrite CollectionStopped;

        mtsFunctionWrite Progress;

        inline DataCollectionInfo(void):
            Collecting(false),
            StartTime(0.0),
            StopTime(0.0),
            BatchSize(0),
            BatchCounter(0),
            CounterForEvent(0)
        {}
 
        inline ~DataCollectionInfo() {}
    };
 
public:
    class AccessorBase {
    protected:
        const mtsStateTable &Table;
        mtsStateDataId Id;   // Not currently used
    public:
        AccessorBase(const mtsStateTable &table, mtsStateDataId id): Table(table), Id(id) {}
        virtual ~AccessorBase() {}
        virtual void ToStream(std::ostream & outputStream, const mtsStateIndex & when) const = 0;
    };
 
    template <class _elementType>
    class Accessor : public AccessorBase {
        typedef typename mtsGenericTypes<_elementType>::FinalType value_type;
        typedef typename mtsGenericTypes<_elementType>::FinalRefType value_ref_type;
        typedef typename mtsStateTable::Accessor<_elementType> ThisType;
        const mtsStateArray<value_type> & History;
        value_ref_type * Current;
 
    public:
        Accessor(const mtsStateTable & table, mtsStateDataId id,
                 const mtsStateArray<value_type> * history, value_ref_type * data):
            AccessorBase(table, id), History(*history), Current(data) {}
 
        void ToStream(std::ostream & outputStream, const mtsStateIndex & when) const {
            History.Element(when.Index()).ToStream(outputStream);
        }
 
        bool Get(const mtsStateIndex & when, value_type & data) const {
            data = History.Element(when.Index());
            return Table.ValidateReadIndex(when);
        }
 
        //This should be used with caution because
        //the state table mechanism could override the data that the pointer is pointing to.
        const value_type * GetPointer(const mtsStateIndex & when) const {
            if (!Table.ValidateReadIndex(when))
                return 0;
            else
                return  &(History.Element(when.Index()));
        }
 
        bool Get(const mtsStateIndex & when, mtsGenericObject & data) const {
            value_type* pdata = dynamic_cast<value_type*>(&data);
            if (pdata) {
                return Get(when, *pdata);
            }
            value_ref_type* pref = dynamic_cast<value_ref_type*>(&data);
            if (pref) {
                return Get(when, *pref);
            }
            return false;
        }
 
        bool GetLatest(value_type & data) const {
            return Get(Table.GetIndexReader(), data);
        }
        bool GetLatest(mtsGenericObject & data) const {
            return Get(Table.GetIndexReader(), data);
        }
 
        bool GetDelayed(value_type & data) const {
            return Get(Table.GetIndexDelayed(), data);
        }
        bool GetDelayed(mtsGenericObject & data) const {
            return Get(Table.GetIndexDelayed(), data);
        }
        void SetCurrent(const value_type & data) {
            *Current = data;
        }
    };
 
 protected:

    bool mStarted;

    size_t HistoryLength;

    size_t IndexWriter;

    size_t IndexReader;

    size_t IndexDelayed;

    size_t Delay;

    bool AutomaticAdvanceFlag;

    std::vector<mtsStateArrayBase *> StateVector;

    std::vector<mtsGenericObject *> StateVectorElements;

    std::vector<std::string> StateVectorDataNames;

    std::vector<AccessorBase *> StateVectorAccessors;

    std::vector<mtsStateIndex::TimeTicksType> Ticks;

    mtsStateDataId TicId, TocId;
    mtsStateDataId PeriodId;

    const osaTimeServer * TimeServer;
 
public:
 
    /* The start/end times for the current row of data. */
    mtsDouble Tic, Toc;

    mtsDouble Period;

    mtsIntervalStatistics PeriodStats;
 
 protected:
    double SumOfPeriods;

    double AveragePeriod;

    std::string Name;

    DataCollectionInfo DataCollection;

    bool Write(mtsStateDataId id, const mtsGenericObject & obj);
 
 
 public:
    mtsStateTable(size_t size, const std::string & name);

    ~mtsStateTable();

    bool SetSize(const size_t size);

    mtsStateIndex GetIndexReader(void) const;
 
    inline void GetIndexReader(mtsStateIndex & timeIndex) const {
        timeIndex = GetIndexReader();
    }

    mtsStateIndex GetIndexDelayed(void) const;

    size_t SetDelay(size_t newDelay);

    inline bool ValidateReadIndex(const mtsStateIndex &timeIndex) const {
        return (Ticks[timeIndex.Index()] == timeIndex.Ticks());
    }

    inline const bool & AutomaticAdvance(void) const {
        return this->AutomaticAdvanceFlag;
    }

    inline void SetAutomaticAdvance(bool automaticAdvance) {
        this->AutomaticAdvanceFlag = automaticAdvance;
    }

    int GetStateVectorID(const std::string & dataName) const;

    template <class _elementType>
    mtsStateDataId NewElement(const std::string & name = "", _elementType * element = 0);

    template <class _elementType>
    void AddData(_elementType & element, const std::string & name = "") {
        NewElement(name, &element);
    }

    template <class _elementType>
    _elementType * GetStateDataElement(mtsStateDataId id) const {
        return StateVectorElements[id]; // WEIRD???
    }
 
 
    mtsGenericObject * GetStateVectorElement(size_t id) const {
        return StateVectorElements[id];
    }

    template<class _elementType>
    mtsStateTable::AccessorBase * GetAccessorByInstance(const _elementType & element) const;

    mtsStateTable::AccessorBase * GetAccessorByName(const std::string & name) const;
    mtsStateTable::AccessorBase * GetAccessorByName(const char * name) const;

    mtsStateTable::AccessorBase * GetAccessorById(const size_t id) const;
 
#ifndef SWIG
    template<class _elementType>
    CISST_DEPRECATED mtsStateTable::AccessorBase * GetAccessor(const _elementType & element) const {
        CMN_LOG_RUN_WARNING << "mtsStateTable::GetAccessor is deprecated, use GetAccessorBy{Instance,Name,Id}" << std::endl;
        return GetAccessorByInstance(element);
    }
    CISST_DEPRECATED mtsStateTable::AccessorBase * GetAccessor(const std::string & name) const {
        CMN_LOG_RUN_WARNING << "mtsStateTable::GetAccessor is deprecated, use GetAccessorBy{Instance,Name,Id}" << std::endl;
        return GetAccessorByName(name);
    }
    CISST_DEPRECATED mtsStateTable::AccessorBase * GetAccessor(const char * name) const {
        CMN_LOG_RUN_WARNING << "mtsStateTable::GetAccessor is deprecated, use GetAccessorBy{Instance,Name,Id}" << std::endl;
        return GetAccessorByName(name);
    }
    CISST_DEPRECATED mtsStateTable::AccessorBase * GetAccessor(const size_t id) const {
        CMN_LOG_RUN_WARNING << "mtsStateTable::GetAccessor is deprecated, use GetAccessorBy{Instance,Name,Id}" << std::endl;
        return GetAccessorById(id);
    }
#endif

    mtsStateIndex GetIndexWriter(void) const;

    void Start(void);

    void StartIfAutomatic(void);

    inline bool Started(void) const {
        return mStarted;
    }

    void Advance(void);

    void AdvanceIfAutomatic(void);

    bool ReplayAdvance(void);

    void Cleanup(void);
 
    inline double GetTic(void) const {
        return this->Tic.Data;
    }
 
    inline double GetToc(void) const {
        return this->Toc.Data;
    }
 
    inline size_t GetHistoryLength(void) const {
        return this->HistoryLength;
    }
 
    inline size_t GetNumberOfElements(void) const {
        return this->StateVector.size();
    }
 
    inline const std::vector<std::string> & GetDataNames(void) const {
        return StateVectorDataNames;
    }

    inline double GetAveragePeriod(void) const {
        return AveragePeriod;
    }

    void ToStream(std::ostream & out) const override;

    void Debug(std::ostream & out, unsigned int * listColumn, unsigned int number) const;

    void CSVWrite(std::ostream & out, bool nonZeroOnly = false);
    void CSVWrite(std::ostream & out, unsigned int * listColumn, unsigned int number, bool nonZeroOnly = false);
 
    void CSVWrite(std::ostream & out, mtsGenericObject ** listColumn, unsigned int number, bool nonZeroOnly = false);

    inline const std::string & GetName(void) const { return Name; }

    void DataCollectionEventTriggeringRatio(const mtsDouble & eventTriggeringRatio);

    void DataCollectionStart(const mtsDouble & delay);
    void DataCollectionStop(const mtsDouble & delay);
};
 
CMN_DECLARE_SERVICES_INSTANTIATION(mtsStateTable);
typedef mtsStateTable::IndexRange mtsStateTableIndexRange;
CMN_DECLARE_SERVICES_INSTANTIATION(mtsStateTableIndexRange);
 
 
// overload mtsObjectName to provide the class name
inline std::string mtsObjectName(const mtsStateTable * object)
{
    return object->GetName();
}
 
// overload mtsObjectName for mtsStateTable::Accessor
template <class _elementType>
inline std::string mtsObjectName(const mtsStateTable::Accessor<_elementType> * CMN_UNUSED(accessor)) {
    return "mtsStateTable::Accessor";
}
 
template <class _elementType>
mtsStateDataId mtsStateTable::NewElement(const std::string & name, _elementType * element) {
    typedef typename mtsGenericTypes<_elementType>::FinalType FinalType;
    typedef typename mtsGenericTypes<_elementType>::FinalRefType FinalRefType;
    mtsStateArray<FinalType> * elementHistory =
        new mtsStateArray<FinalType>(*element, HistoryLength);
    StateVector.push_back(elementHistory);
    FinalRefType *pdata = mtsGenericTypes<_elementType>::ConditionalWrap(*element);
    StateVectorElements.push_back(pdata);
 
    StateVectorDataNames.push_back(name);
    mtsStateDataId id = static_cast<mtsStateDataId>(StateVector.size() - 1);
    AccessorBase * accessor = new Accessor<_elementType>(*this, id, elementHistory, pdata);
    StateVectorAccessors.push_back(accessor);
    return id;
}
 
template <class _elementType>
mtsStateTable::AccessorBase *mtsStateTable::GetAccessorByInstance(const _elementType & element) const
{
    for (size_t i = 0; i < StateVectorElements.size(); i++) {
        if (mtsGenericTypes<_elementType>::IsEqual(element, *StateVectorElements[i]))
            return StateVectorAccessors[i];
    }
    return 0;
}
 
#endif // _mtsStateTable_h