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-2011 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/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 {
        mtsGenericObject::SerializeRaw(outputStream);
        cmnSerializeRaw(outputStream, Name);
        cmnSerializeRaw(outputStream, Arg);
    }

    void DeSerializeRaw(std::istream & inputStream) {
        mtsGenericObject::DeSerializeRaw(inputStream);
        cmnDeSerializeRaw(inputStream, Name);
        cmnDeSerializeRaw(inputStream, Arg);
    }

    void ToStream(std::ostream & outputStream) const {
        outputStream << "Name: " << Name
                     << ", Arg: " << Arg << std::endl;
    }

    virtual void ToStreamRaw(std::ostream & outputStream, const char delimiter = ' ',
                             bool headerOnly = false, const std::string & headerPrefix = "") const {
        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 = ' ') {
        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_NO_DYNAMIC_CREATION, CMN_LOG_ALLOW_DEFAULT);

    friend class mtsManagerLocal;
    friend class mtsComponentProxy;

 protected:

    std::string Name;

    mtsComponentState State;

    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();

    const std::string & GetName(void) const;
    void GetName(std::string & placeHolder) 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,
                                                bool isProxy = false);

    // 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, const bool skipDisconnect = false);

    //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, const bool skipDisconnect = false);

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

    const mtsManagerComponentServices *GetManagerComponentServices(void) const
    { return this->ManagerComponentServices; }
    mtsManagerComponentServices *GetManagerComponentServices(void)
    { return this->ManagerComponentServices; }

    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;

    /********************* Methods to query the task state ****************/

    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;

 protected:

    virtual bool WaitForState(mtsComponentState desiredState, double timeout);

    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);

    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);
    void InterfaceInternalCommands_ComponentCreate(const mtsDescriptionComponent & componentDescription, bool & result);
    void InterfaceInternalCommands_ComponentStartOther(const mtsComponentStatusControl & arg);

 public:
    void ToStream(std::ostream & outputStream) const;

    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)


#endif // _mtsComponent_h