Framework.h

Go to the documentation of this file.

/*
 * Copyright (C) 2012 by
 *   MetraLabs GmbH (MLAB), GERMANY
 * and
 *   Neuroinformatics and Cognitive Robotics Labs (NICR) at TU Ilmenau, GERMANY
 * All rights reserved.
 *
 * Contact: info@mira-project.org
 *
 * Commercial Usage:
 *   Licensees holding valid commercial licenses may use this file in
 *   accordance with the commercial license agreement provided with the
 *   software or, alternatively, in accordance with the terms contained in
 *   a written agreement between you and MLAB or NICR.
 *
 * GNU General Public License Usage:
 *   Alternatively, this file may be used under the terms of the GNU
 *   General Public License version 3.0 as published by the Free Software
 *   Foundation and appearing in the file LICENSE.GPL3 included in the
 *   packaging of this file. Please review the following information to
 *   ensure the GNU General Public License version 3.0 requirements will be
 *   met: http://www.gnu.org/copyleft/gpl.html.
 *   Alternatively you may (at your option) use any later version of the GNU
 *   General Public License if such license has been publicly approved by
 *   MLAB and NICR (or its successors, if any).
 *
 * IN NO EVENT SHALL "MLAB" OR "NICR" BE LIABLE TO ANY PARTY FOR DIRECT,
 * INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
 * THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF "MLAB" OR
 * "NICR" HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * "MLAB" AND "NICR" SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
 * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND "MLAB" AND "NICR" HAVE NO OBLIGATION TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS OR MODIFICATIONS.
 */

#ifndef _MIRA_FRAMEWORK_H_
#define _MIRA_FRAMEWORK_H_

#include <serialization/adapters/std/list>
#include <serialization/adapters/std/map>
#include <serialization/adapters/boost/shared_ptr.hpp>

#include <utils/ProgramOptions.h>
#include <platform/Types.h>
#include <rpc/RPCManager.h>
#include <thread/ScopedAccess.h>
#include <utils/Singleton.h>
#include <xml/XMLDomReflect.h>
#include <xml/XMLDomModifier.h>
#include <factory/LibraryRegistry.h>

#include <fw/Authority.h>
#include <fw/AuthorityManager.h>
#include <fw/Channel.h>
#include <fw/ChannelManager.h>
#include <fw/NameRegistry.h>

#include <loader/Loader.h>

#define MIRA_FW mira::Framework::instance()

namespace mira {


// forward decls.
struct IntSignal;
class ErrorService;
class Framework;
class FrameworkTransformer;
class RemoteModule;
class UnitManager;

namespace Private {


class MIRA_FRAMEWORK_EXPORT FrameworkStartup
{
public:
    FrameworkStartup(int argc, char** argv);
    FrameworkStartup(const std::vector<std::string>& args);

protected:

    void initialize();
    ProgramOptions mOptions;
    typedef std::vector<std::string> CommandLineStrings;
    CommandLineStrings mCommandLineVariables;
    CommandLineStrings mCommandLineKnownFrameworks;
};


class FrameworkAuthority : public Authority
{
public:
    FrameworkAuthority(Framework* framework, const ResourceName& ns,
                       const std::string& name, Flags flags = Authority::NORMAL)
        : Authority(ns, name, flags), mFramework(framework)
    {}

public:
    boost::shared_ptr<PropertyNode> getProperties();

protected:
    Framework* mFramework;
};


}


class MIRA_FRAMEWORK_EXPORT Framework : public Private::FrameworkStartup,
                                        public ExplicitSingleton<Framework>
{
public:

    Framework(int argc, char** argv, bool startImmediately = false);
    Framework(const std::vector<std::string>& args, bool startImmediately = false);

    virtual ~Framework();

    template<typename Reflector>
    void reflect(Reflector& r)
    {
        serialization::VersionType version = r.version(2, this);

        if (version >= 2)
            r.property("RemoteModule", mRemoteModule, "The remote module", boost::shared_ptr<RemoteModule>());

        r.method("getUptime", &Framework::getUptime, this, "Get the time since the framework was started");

        r.method("terminateProcess", &Framework::requestTermination, this,
                 "Terminate framework (and thus, the process). Use with care!",
                 "exitcode", "the exitcode returned by the process", 0u);

        r.interface("IVariableRegistry");
        r.method("getVariables", &Framework::getVariables, this,
                 "Query variables");

        r.interface("ILibraryRegistry");
        r.method("getLibraries",
                  boost::function<LibraryRegistry::Register()>(LibraryRegistry::getRegister),
                 "Query libraries");
        r.method("getLoadedLibraries",
                 boost::function<LibraryRegistry::Register()>([](){
                    LibraryRegistry::Register reg = LibraryRegistry::getRegister();
                    for (auto it = reg.begin(); it != reg.end(); ) {
                        if (it->second.mIsLoaded)
                            ++it;
                        else {
                            auto succ = it; ++succ;
                            reg.erase(it);
                            it = succ;
                        }
                    }
                    return reg;
                 }),
                 "Query only loaded libraries");

        r.interface("IConfigurationLoader");
        r.method("loadConfig",
                 boost::function<void(const XMLDom&)>(
                    [&](const XMLDom& xml) { this->load(const_cast<XMLDom&>(xml)); } ),
                 "Load a configuration",
                 "xml", "XML document", XMLDom());

    }

public:
    boost::shared_ptr<PropertyNode> getProperties() {
        return mProperties;
    }

public:

    void load(XMLDom& xml);

    void load(const std::string& configFile);

    void load();

    void start();

    bool isStarted() const
    {
        return mIsStarted;
    }

    Duration getUptime() const
    {
        return Time::now() - mStartTime;
    }

    virtual int exec();

    virtual void requestTermination(int exitcode=0);

    virtual bool isTerminationRequested() const;

    int getTerminationExitCode() const;

    int run();

public:


    NameRegistry& getNameRegistry() { return mNames; }

    AuthorityManager& getAuthorityManager() { return mAuthorityManager; }

    ChannelManager& getChannelManager() { return mChannelManager; }

    boost::shared_ptr<FrameworkTransformer> getTransformer() { return mTransformer; }

    ConfigurationLoader& getConfigurationLoader() { return mConfigurationLoader; }

    boost::shared_ptr<UnitManager> getUnitManager() { return mUnitManager; }

    RPCManager& getRPCManager() { return mRPCManager; }

    boost::shared_ptr<ErrorService> getErrorService() { return mErrorServiceModule; }

    boost::shared_ptr<RemoteModule> getRemoteModule() { return mRemoteModule; }


    std::string getID() const { return mAuthority->getID(); }

    std::string getGlobalID() const { return mAuthority->getGlobalID(); }

    XMLVariablesMap& getVariables() { return mXMLPreprocessor.variables; }

    XMLDomPreprocessor& getXMLDomPreprocessor() { return mXMLPreprocessor; }

    typedef ProtecteeMixin<MetaTypeDatabase> ProtecteeDatabase;
    ScopedAccess<ProtecteeDatabase> getMetaDatabase()
    {
        return ScopedAccess<ProtecteeDatabase>(&mMetaDatabase);
    }

    bool isInExec() const { return mInExec; }

protected:

    friend class Private::FrameworkStartup;

    void initialize();
    void finalize();
    void ctrlCHandler(const IntSignal& sig);

    static void errorHandler(const IntSignal& sig);
    static bool enterLeaveErrorHandler(bool enter);

protected:

    bool mTerminationRequested;
    int  mTerminationExitCode;
    bool mIsStarted;
    bool mInExec;
    bool mRemoteDisabled;

    // The authority of the framework (used for all services of the framework
    // as well as providing a process thread for submodules)
    boost::shared_ptr<Private::FrameworkAuthority> mAuthority;

    RootPropertyNode mPropertiesRoot;
    boost::shared_ptr<PropertyNode> mProperties;

    // our components:
    NameRegistry mNames;
    boost::shared_ptr<RemoteModule> mRemoteModule;

    // DO NOT CHANGE THE ORDER of the following components, the order of
    // destruction is important for producing correct error messages when
    // destroying the framework and errors occur. If the order is not correct,
    // it could result in misleading error messages.
    RPCManager mRPCManager;          // create RPCManager and ChannelManager first
    ChannelManager mChannelManager;  // to bring up the communication components
                                     // that may be used by the components below.
    AuthorityManager mAuthorityManager;
    boost::shared_ptr<FrameworkTransformer> mTransformer;

    boost::shared_ptr<UnitManager> mUnitManager;

    ConfigurationLoader mConfigurationLoader;

    boost::shared_ptr<ErrorService> mErrorServiceModule;
    std::string mName;

    XMLDomPreprocessor mXMLPreprocessor;
    XMLDom mConfigDom;
    ProtecteeDatabase mMetaDatabase;

    Time mStartTime;
};


}

#include <fw/impl/Authority.hpp>
#include <fw/impl/ConcreteChannel.hpp>

#endif