mtsComponent.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, Peter Kazanzides, Anton Deguet, Min Yang Jung
  Created on: 2004-04-30
 
  (C) Copyright 2004-2026 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 _mtsComponent_h
#define _mtsComponent_h
 
#include <cisstCommon/cmnPortability.h>
#include <cisstCommon/cmnGenericObject.h>
#include <cisstCommon/cmnClassRegisterMacros.h>
#include <cisstCommon/cmnNamedMap.h>
 
#include <cisstMultiTask/mtsForwardDeclarations.h>
#include <cisstMultiTask/mtsComponentState.h>
#include <cisstMultiTask/mtsFunctionVoid.h>
#include <cisstMultiTask/mtsFunctionWrite.h>
#include <cisstMultiTask/mtsFunctionRead.h>
#include <cisstMultiTask/mtsFunctionQualifiedRead.h>
#include <cisstMultiTask/mtsFunctionVoidReturn.h>
#include <cisstMultiTask/mtsFunctionWriteReturn.h>
#include <cisstMultiTask/mtsInterfaceRequired.h>
#include <cisstMultiTask/mtsMulticastCommandVoid.h>
#include <cisstMultiTask/mtsMulticastCommandWrite.h>
#include <cisstMultiTask/mtsParameterTypes.h>
 
// Always include last
#include <cisstMultiTask/mtsExport.h>

 

 
template <class T>
class mtsComponentConstructorNameAndArg : public mtsGenericObject
{
    CMN_DECLARE_SERVICES_EXPORT(CMN_DYNAMIC_CREATION, CMN_LOG_ALLOW_DEFAULT);
public:
    std::string Name;
    T Arg;
 
    mtsComponentConstructorNameAndArg() : mtsGenericObject() {}
    mtsComponentConstructorNameAndArg(const std::string &name, const T &arg) : mtsGenericObject(),
        Name(name), Arg(arg) {}
    ~mtsComponentConstructorNameAndArg() {}
 
    void SerializeRaw(std::ostream & outputStream) const override {
        mtsGenericObject::SerializeRaw(outputStream);
        cmnSerializeRaw(outputStream, Name);
        cmnSerializeRaw(outputStream, Arg);
    }
 
    void DeSerializeRaw(std::istream & inputStream) override {
        mtsGenericObject::DeSerializeRaw(inputStream);
        cmnDeSerializeRaw(inputStream, Name);
        cmnDeSerializeRaw(inputStream, Arg);
    }
 
    void ToStream(std::ostream & outputStream) const override {
        outputStream << "Name: " << Name
                     << ", Arg: " << Arg << std::endl;
    }

    virtual void ToStreamRaw(std::ostream & outputStream, const char delimiter = ' ',
                             bool headerOnly = false, const std::string & headerPrefix = "") const override {
        mtsGenericObject::ToStreamRaw(outputStream, delimiter, headerOnly, headerPrefix);
        if (headerOnly) {
            outputStream << headerPrefix << "-name" << delimiter
                         << headerPrefix << "-arg";
        } else {
            outputStream << this->Name << delimiter
                         << this->Arg;
        }
    }

    virtual bool FromStreamRaw(std::istream & inputStream, const char delimiter = ' ') override {
        mtsGenericObject::FromStreamRaw(inputStream, delimiter);
        if (inputStream.fail())
            return false;
        inputStream >> Name >> Arg;
        if (inputStream.fail())
            return false;
        return (typeid(*this) == typeid(mtsComponentConstructorNameAndArg<T>));
    }
};
 
typedef mtsComponentConstructorNameAndArg<int> mtsComponentConstructorNameAndInt;
CMN_DECLARE_SERVICES_INSTANTIATION(mtsComponentConstructorNameAndInt)
 
typedef mtsComponentConstructorNameAndArg<unsigned int> mtsComponentConstructorNameAndUInt;
CMN_DECLARE_SERVICES_INSTANTIATION(mtsComponentConstructorNameAndUInt)
 
typedef mtsComponentConstructorNameAndArg<long> mtsComponentConstructorNameAndLong;
CMN_DECLARE_SERVICES_INSTANTIATION(mtsComponentConstructorNameAndLong)
 
typedef mtsComponentConstructorNameAndArg<unsigned long> mtsComponentConstructorNameAndULong;
CMN_DECLARE_SERVICES_INSTANTIATION(mtsComponentConstructorNameAndULong)
 
typedef mtsComponentConstructorNameAndArg<double> mtsComponentConstructorNameAndDouble;
CMN_DECLARE_SERVICES_INSTANTIATION(mtsComponentConstructorNameAndDouble)
 
typedef mtsComponentConstructorNameAndArg<std::string> mtsComponentConstructorNameAndString;
CMN_DECLARE_SERVICES_INSTANTIATION(mtsComponentConstructorNameAndString)

class CISST_EXPORT mtsComponent: public cmnGenericObject
{
    CMN_DECLARE_SERVICES(CMN_DYNAMIC_CREATION_ONEARG, CMN_LOG_ALLOW_DEFAULT);
 
    friend class mtsManagerComponent;
    friend class mtsManagerLocal;
 
 protected:

    std::string Name;

    mtsComponentState State;

    std::set<std::string> mTags;

    mtsInterfaceProvided *InterfaceProvidedToManager;

    mtsComponent(void);

    mtsComponent(const mtsComponent & other);

    void Initialize(void);

    mtsInterfaceRequired * AddInterfaceRequiredExisting(const std::string & interfaceRequiredName,
                                                        mtsInterfaceRequired * interfaceRequired);

    mtsInterfaceRequired * AddInterfaceRequiredUsingMailbox(const std::string & interfaceRequiredName,
                                                            mtsMailBox * mailBox,
                                                            mtsRequiredType required);

    mtsInterfaceProvided * AddInterfaceProvidedUsingMailbox(const std::string & interfaceProvidedName,
                                                            mtsMailBox * mailBox);
 
    mtsInterfaceInput * AddInterfaceInputExisting(const std::string & interfaceInputName,
                                                  mtsInterfaceInput * interfaceInput);
 
    mtsInterfaceOutput * AddInterfaceOutputExisting(const std::string & interfaceOutputName,
                                                    mtsInterfaceOutput * interfaceOutput);

    void KillSeparateLogFile(void);
 
 public:
 
    typedef mtsComponent ThisType;

    mtsComponent(const std::string & deviceName);

    virtual ~mtsComponent();
 
#if CISST_HAS_JSON
    virtual void ConfigureJSON(const Json::Value & configuration);
#endif

    const std::string & GetName(void) const;
    void GetName(std::string & placeHolder) const;

    void AddTag(const std::string & tag);

    const std::set<std::string> & GetTags(void) const;

    void SetName(const std::string & componentName);

    virtual void Configure(const std::string & filename = "");

    virtual void Create(void);

    bool CreateAndWait(double timeoutInSeconds);

    virtual void Start(void);

    bool StartAndWait(double timeoutInSeconds);

    virtual void Suspend(void);

    virtual void Kill(void);

    bool KillAndWait(double timeoutInSeconds);

    virtual void Startup(void) {}

    virtual void Cleanup(void) {}

    mtsInterfaceProvided * AddInterfaceProvided(const std::string & interfaceProvidedName,
                                                mtsInterfaceQueueingPolicy queueingPolicy = MTS_COMPONENT_POLICY);

    virtual mtsInterfaceProvided *
        AddInterfaceProvidedWithoutSystemEvents(const std::string & interfaceProvidedName,
                                                mtsInterfaceQueueingPolicy queueingPolicy = MTS_COMPONENT_POLICY);
 
    // provided for backward compatibility
    inline CISST_DEPRECATED mtsInterfaceProvided * AddProvidedInterface(const std::string & interfaceProvidedName) {
        return this->AddInterfaceProvided(interfaceProvidedName);
    }

    virtual mtsInterfaceOutput * AddInterfaceOutput(const std::string & interfaceOutputName);

    std::vector<std::string> GetNamesOfInterfacesProvidedOrOutput(void) const;
    std::vector<std::string> GetNamesOfInterfacesProvided(void) const;
    std::vector<std::string> GetNamesOfInterfacesOutput(void) const;

    bool InterfaceExists(const std::string & interfaceName, cmnLogLevel lod = CMN_LOG_LEVEL_INIT_VERBOSE) const;

    bool InterfaceProvidedOrOutputExists(const std::string & interfaceName, cmnLogLevel lod = CMN_LOG_LEVEL_INIT_VERBOSE) const;

    bool InterfaceRequiredOrInputExists(const std::string & interfaceName, cmnLogLevel lod = CMN_LOG_LEVEL_INIT_VERBOSE) const;

    mtsInterfaceProvided * GetInterfaceProvided(const std::string & interfaceProvidedName) const;

    mtsInterfaceOutput * GetInterfaceOutput(const std::string & interfaceOutputName) const;

    size_t GetNumberOfInterfacesProvided(void) const;

    size_t GetNumberOfInterfacesOutput(void) const;

    bool RemoveInterfaceProvided(const std::string & interfaceProvidedName);

    //bool RemoveInterfaceOutput(const std::string & interfaceOutputName);

    mtsInterfaceRequired * AddInterfaceRequired(const std::string & interfaceRequiredName,
                                                mtsRequiredType isRequired = MTS_REQUIRED);
 
    virtual mtsInterfaceRequired *
        AddInterfaceRequiredWithoutSystemEventHandlers(const std::string & interfaceRequiredName,
                                                       mtsRequiredType isRequired = MTS_REQUIRED);
 
    // provided for backward compatibility
    inline CISST_DEPRECATED mtsInterfaceRequired * AddRequiredInterface(const std::string & requiredInterfaceName) {
        return this->AddInterfaceRequired(requiredInterfaceName);
    }

    virtual mtsInterfaceInput * AddInterfaceInput(const std::string & interfaceInputName);

    std::vector<std::string> GetNamesOfInterfacesRequiredOrInput(void) const;
    std::vector<std::string> GetNamesOfInterfacesRequired(void) const;
    std::vector<std::string> GetNamesOfInterfacesInput(void) const;

    const mtsInterfaceProvided * GetInterfaceProvidedFor(const std::string & interfaceRequiredName);

    mtsInterfaceRequired * GetInterfaceRequired(const std::string & interfaceRequiredName);

    mtsInterfaceInput * GetInterfaceInput(const std::string & interfaceInputName) const;

    size_t GetNumberOfInterfacesRequired(void) const;

    size_t GetNumberOfInterfacesInput(void) const;

    bool RemoveInterfaceRequired(const std::string & interfaceRequiredName);

    //bool RemoveInterfaceInput(const std::string & interfaceInputName);

    mtsStateTable * GetStateTable(const std::string & stateTableName);

    bool AddStateTable(mtsStateTable * existingStateTable, bool addInterfaceProvided = true);

    void UseSeparateLogFileDefault(bool forwardToLogger = true);

    void UseSeparateLogFileDefaultWithDate(bool forwardToLogger = true);

    void UseSeparateLogFile(const std::string & filename, bool forwardToLogger = true);

    cmnLogger::StreamBufType * GetLogMultiplexer(void) const override;
 
    /********************* Methods to query the task state ****************/

    bool AreAllInterfacesRequiredConnected(const bool log = false);

    bool IsRunning(void) const;
    inline bool CISST_DEPRECATED Running(void) const {
        return this->IsRunning();
    }

    bool IsStarted(void) const;

    bool IsTerminated(void) const;

    bool IsEndTask(void) const;

    const mtsComponentState & GetState(void) const;
    void GetState(mtsComponentState &state) const;

    virtual bool WaitForState(mtsComponentState desiredState, double timeout);
 
 protected:

    bool UseSeparateLogFileFlag;

    cmnLogger::StreamBufType * LoDMultiplexerStreambuf;

    std::ofstream * LogFile;

    typedef cmnNamedMap<mtsInterfaceProvided> InterfacesProvidedMapType;
    InterfacesProvidedMapType InterfacesProvided;
    typedef cmnNamedMap<mtsInterfaceOutput> InterfacesOutputMapType;
    InterfacesOutputMapType InterfacesOutput;

    typedef cmnNamedMap<mtsInterfaceRequired> InterfacesRequiredMapType;
    InterfacesRequiredMapType InterfacesRequired;
    typedef cmnNamedMap<mtsInterfaceInput> InterfacesInputMapType;
    InterfacesInputMapType InterfacesInput;

    typedef cmnNamedMap<mtsStateTable> StateTableMapType;
    StateTableMapType StateTables;

    size_t ProcessMailBoxes(InterfacesProvidedMapType & interfaces);

    inline size_t ProcessQueuedCommands(void) {
        return this->ProcessMailBoxes(InterfacesProvided);
    }

    size_t ProcessQueuedEvents(void);

    mtsManagerComponentServices * ManagerComponentServices;

    mtsInterfaceRequired * EnableDynamicComponentManagement(void);

    mtsFunctionWrite EventGeneratorChangeState;

    bool AddInterfaceInternal(const bool useMangerComponentServices = false);

    virtual const mtsManagerComponentServices *GetManagerComponentServices(void) const;

    void InterfaceInternalCommands_GetEndUserInterface(const mtsEndUserInterfaceArg & argin, mtsEndUserInterfaceArg & argout);
    void InterfaceInternalCommands_AddObserverList(const mtsEventHandlerList & argin, mtsEventHandlerList & argout);
    void InterfaceInternalCommands_RemoveEndUserInterface(const mtsEndUserInterfaceArg & argin, mtsEndUserInterfaceArg & argout);
    void InterfaceInternalCommands_RemoveObserverList(const mtsEventHandlerList & argin, mtsEventHandlerList & argout);
 
 public:
    void ToStream(std::ostream & outputStream) const override;

    bool SetReplayMode(void);
 
    bool SetReplayData(const std::string & stateTableName, const std::string & fileName);
 
    bool SetReplayTime(const double time);
 
 protected:
 
    bool ReplayMode;
 
};
 
 
// overload mtsObjectName to retrieve the actual name
inline std::string mtsObjectName(const mtsComponent * object) {
    return "mtsComponent: " + object->GetName();
}
 
 
CMN_DECLARE_SERVICES_INSTANTIATION(mtsComponent)
 
 
// Following derived class enables dynamic component management.
class CISST_EXPORT mtsComponentWithManagement : public mtsComponent
{
    CMN_DECLARE_SERVICES(CMN_DYNAMIC_CREATION_ONEARG, CMN_LOG_ALLOW_DEFAULT);
 
public:
    mtsComponentWithManagement(const std::string &deviceName) : mtsComponent(deviceName)
        { EnableDynamicComponentManagement(); }

    virtual ~mtsComponentWithManagement() { }
};
 
CMN_DECLARE_SERVICES_INSTANTIATION(mtsComponentWithManagement)
 
#endif // _mtsComponent_h