Executor.h

Go to the documentation of this file.

/*
 * This file is part of ArmarX.
 *
 * Copyright (C) 2011-2016, High Performance Humanoid Technologies (H2T), Karlsruhe Institute of Technology (KIT), all rights reserved.
 *
 * ArmarX is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 as
 * published by the Free Software Foundation.
 *
 * ArmarX is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <http://www.gnu.org/licenses/>.
 *
 * @package    ArmarXCore::core
 * @author     Nicola Miskowiec
 * @date       2016
 * @copyright  http://www.gnu.org/licenses/gpl-2.0.txt
 *             GNU General Public License
 */
 
 
#pragma once
 
#include <chrono>
#include <filesystem>
#include <future>
#include <map>
#include <memory>
 
#include "../data_structure/ApplicationInstance.h"
#include "../data_structure/Scenario.h"
#include "../parser/StatusManager.h"
#include "ApplicationStarter.h"
#include "StopStrategy.h"
 
namespace ScenarioManager
{
    class StatusManager;
}
 
namespace ScenarioManager::Exec
{
    class StopStrategy;
    using StopStrategyPtr = std::shared_ptr<StopStrategy>;
 
    // Only forward declared: StatusManager.h includes this header and ApplicationLifecycle.h
    // needs StopStrategy.h, so including it here would close an include cycle.
    class ApplicationLifecycle;
    using ApplicationLifecyclePtr = std::shared_ptr<ApplicationLifecycle>;
 
    /**
    * @class Executor
    * @ingroup exec
    * @brief Starts, stops and restarts applications and scenarios.
    * Can also be used to request the status of an application. The proper system-specific stopstrategy and starter have to be set in the constructor.
    */
    class Executor
    {
 
    private:
        StopStrategyPtr defaultStopStrategy;
        ApplicationStarterPtr defaultStartStrategy;
        std::map<Data_Structure::ScenarioPtr, StopStrategyPtr> stopStrategy;
        std::map<Data_Structure::ScenarioPtr, ApplicationStarterPtr> starter;
        StatusManager statusManager;
 
        /// How long an application may take to dump its property definitions.
        static constexpr std::chrono::milliseconds PropertyGenerationTimeout{30000};
 
        /**
        * Runs the application binary once with `-p -f xml -o <xmlFilePath>` so that it writes its
        * property definitions, and waits for it to finish.
        * @param application the application to run
        * @param xmlFilePath where the application should write its property definitions
        */
        static void generatePropertiesXml(const Data_Structure::ApplicationPtr& application,
                                          const std::filesystem::path& xmlFilePath);
 
        /// Returns the lifecycle owning `application`, creating it on first use.
        ApplicationLifecyclePtr lifecycleFor(const Data_Structure::ApplicationInstancePtr& app);
 
        /// Requests `intent` for every application of `scenario`.
        void requestForScenario(const Data_Structure::ScenarioPtr& scenario,
                                Data_Structure::Intent intent,
                                const std::string& commandLineParameters,
                                bool printOnly);
 
        std::mutex lifecyclesMutex;
        std::map<Data_Structure::ApplicationInstance*, ApplicationLifecyclePtr> lifecycles;
 
    public:
        /**
        * Constructor that sets StopStrategy and ApplicationStarter.
        * @param strategy Strategy used to stop applications.
        * @param starter Starter used to start applications and request their status.
        */
        Executor(StopStrategyPtr strategy, ApplicationStarterPtr starter);
 
        /**
        * Requests that an application be started.
        *
        * All of these methods record an intent and return immediately; the work happens on a
        * worker thread owned by the application's ApplicationLifecycle. A request supersedes any
        * intent that has not been carried out yet, so the last thing the user asked for is what
        * happens. Nothing is ever refused.
        *
        * @param application application to be started.
        */
        void startApplication(Data_Structure::ApplicationInstancePtr application,
                              bool printOnly = false,
                              const std::string& commandLineParameters = "");
 
        /**
        * Requests that an application be stopped.
        * @param application application to be stopped
        */
        void stopApplication(Data_Structure::ApplicationInstancePtr application);
 
        /**
        * Requests that an application be restarted. An application that is not running is started.
        * @param application application to be restarted
        */
        void restartApplication(Data_Structure::ApplicationInstancePtr application,
                                bool printOnly = false);
 
        /**
        * Blocks until the application has no operation requested or running any more.
        *
        * The GUI never needs this - it watches the status instead - but a caller that exits right
        * afterwards, such as the command line interface, has to see the operation through.
        */
        void waitForApplication(const Data_Structure::ApplicationInstancePtr& application);
 
        /// Blocks until no application of the scenario has an operation requested or running.
        void waitForScenario(const Data_Structure::ScenarioPtr& scenario);
 
        /**
        * Returns the status of an application. Uses the ApplicationStarter to request the status, therefore the proper
        * system-specific starter has to be set, even to use this method.
        * @param application application whose status is returned
        * @return status of the application
        */
        std::string getApplicationStatus(Data_Structure::ApplicationInstancePtr application);
 
        /**
        * Starts a scenario. Iterates over the applications in the scenario and starts them.
        * @param scenario scenario to be started
        * @return {@code true} if all applications were successfully started
        */
        void startScenario(Data_Structure::ScenarioPtr scenario,
                           bool printOnly = false,
                           const std::string& commandLineParameters = "");
 
        /**
        * Stops a scenario. Iterates over the applications in the scenario and stops them.
        * @param scenario scenario to be stopped
        * @return {@code true} if all applications were successfully stopped
        */
        void stopScenario(Data_Structure::ScenarioPtr scenario);
 
        /**
        * Restarts a scenario. Iterates over the applications in the scenario and restarts them.
        * @param scenario scenario to be restarted
        * @return {@code true} if all applications were successfully restarted
        */
        void restartScenario(Data_Structure::ScenarioPtr scenario, bool printOnly = false);
 
        /**
        * Generates an XML file of the given application and saves it in the specified path.
        * If there already is an XML file at that location it only reloads the file if the executable is more recently changed
        * than the Xml file
        * @param application Application whose XML file is to be generate
        * @param path location to save the XML, must be a folder
        * @param reload forces to reload the cached XML
        * @param set if true the newly Cached Xml gets loaded into the Application (Warning: If you load an ApplicationInstance the cfg parameter have to be reloaded)
        */
        static void loadAndSetCachedProperties(Data_Structure::ApplicationPtr application,
                                        std::string path,
                                        bool reload = false,
                                        bool set = true);
 
        /**
        * Sets the strategy this Executor uses to stop applications. Needs to be system specific.
        * Use the Factory-Classes to get the proper strategy for your system.
        * @param strategy strategy to be set
        * @see StopStrategyFactory
        */
        void setDefaultStopStrategy(StopStrategyPtr strategy);
        void setStopStrategy(StopStrategyPtr strategy, Data_Structure::ScenarioPtr scenario);
 
        /**
        * Sets the appStarter this Executor uses to start applications and request statuses. Needs to be system specific.
        * Use the Factory-Classes to get the proper appStarter for your system.
        * @param appStarter appStarter to be set
        * @see StarterFactory
        * @see StarterFactoryLinux
        */
        void setDefaultStarter(ApplicationStarterPtr appStarter);
        void setStarter(ApplicationStarterPtr appStarter, Data_Structure::ScenarioPtr scenario);
 
        ApplicationStarterPtr getStarter(Data_Structure::ScenarioPtr scenario);
        StopStrategyPtr getStopStrategy(Data_Structure::ScenarioPtr scenario);
        StopStrategyPtr getDefaultStopStrategy();
    };
 
    using ExecutorPtr = std::shared_ptr<Executor>;
} // namespace ScenarioManager::Exec