ApplicationInstance.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     Dennis Weigelt
 * @date       2016
 * @copyright  http://www.gnu.org/licenses/gpl-2.0.txt
 *             GNU General Public License
 */
 
 
#pragma once
 
#include "Application.h"
 
namespace ScenarioManager::Data_Structure
{
    class ApplicationInstance;
    using ApplicationInstancePtr = std::shared_ptr<ApplicationInstance>;
    using ApplicationInstanceWPtr = std::weak_ptr<ApplicationInstance>;
    using ApplicationInstanceVectorPtr = std::shared_ptr<std::vector<ApplicationInstancePtr>>;
} // namespace ScenarioManager::Data_Structure
 
#include <atomic>
#include <memory>
#include <string>
#include <vector>
 
#include "Scenario.h"
 
namespace ScenarioManager::Data_Structure
{
    /**
     * What the ScenarioManager is currently trying to do with an application.
     *
     * An intent is *requested* rather than executed: requesting one supersedes any earlier intent
     * that has not been carried out yet, so the last thing the user asked for is what happens
     * ("last intent wins"). `None` means no operation is requested or running.
     *
     * `Restart` is a separate intent rather than "desired state = running" because it has to bounce
     * an application that is already running. On a stopped application it simply starts it.
     */
    enum class Intent
    {
        None,
        Start,
        Stop,
        Restart
    };
 
    /// Human readable name of an intent, for logging.
    const char* ToString(Intent intent);
 
    struct ApplicationStatus
    {
        static const std::string Stopped;
        static const std::string Running;
        static const std::string Waiting;
        static const std::string Mixed;
        static const std::string Unknown;
        static const std::string Inactive;
        static const std::string Missing;
 
        /**
         * Combines the stati of several applications into the status of their common parent
         * (a scenario or the package subtree of a scenario). The rules are:
         *
         * - `Missing` applications are ignored: a binary that cannot be found says nothing about
         *   what is currently running. If every application is missing, the result is `Missing`.
         * - If any application is `Waiting`, the result is `Waiting`: a start/stop is in flight
         *   and that is the most useful thing to show.
         * - `Unknown` applications are ignored as long as at least one other application has a
         *   definite status, so that a single indeterminate probe does not blank out a whole
         *   scenario. If all of them are `Unknown`, the result is `Unknown`.
         * - If all remaining applications agree, that status is the result, otherwise `Mixed`.
         *
         * The result only depends on the set of stati, not on their order.
         *
         * Note that `Missing` is never stored on an ApplicationInstance itself; it is derived by
         * the GUI from Application::getFound() and passed in here by the tree items.
         */
        static std::string Aggregate(const std::vector<std::string>& stati);
    };
 
    /**
    * @class ApplicationInstance
    * @ingroup Data_Structure
    * @brief Class containing data about the instance of an application.
    * Provides methods to get and set the data. It is only representative and doesn't actually synchronize
    * with the configuration files.
    */
    class ApplicationInstance :
        public Application,
        public std::enable_shared_from_this<ApplicationInstance>
    {
 
    private:
        std::string instanceName;
        std::filesystem::path configPath;
        std::string status;
        std::string nodeName;
        std::string configDomain;
        ScenarioPtr scenario;
        /// Touched by the GUI thread, the status polling thread and every starter/stopper thread.
        std::atomic<int> pid;
        /// Published by the ApplicationLifecycle that owns this application, read by the GUI.
        std::atomic<Intent> pendingIntent;
        bool enabled;
        bool readOnly;
 
    public:
        /**
        * Constructor that sets the base data of this ApplicationInstance.
        * @param executableName The name of the Application
        * @param executablePath The path of the Executable
        * @param instanceName a name that distinguishes this instance from other instances
        * @param configPath path to the config file of this instance
        */
        ApplicationInstance(std::string executableName,
                            std::string executablePath,
                            std::string instanceName,
                            std::string configPath,
                            std::string packageName,
                            ScenarioPtr scenarioName,
                            std::string node,
                            bool enabled);
 
        /**
        * Constructor that sets the base data of this ApplicationInstance.
        * @param application The application this class instantiates.
        * @param instanceName a name that distinguishes this instance from other instances
        * @param configPath path to the config file of this instance
        */
        ApplicationInstance(Application application,
                            std::string instanceName,
                            std::string configPath,
                            ScenarioPtr scenarioName,
                            std::string node,
                            bool enabled);
 
        /**
        * @return name of this ApplicationInstance
        */
        std::string getInstanceName();
 
        /**
        * Sets the name of this ApplicationInstance
        * @param new name
        */
        void setInstanceName(std::string newName); //wird die setter gebraucht?
 
        /**
        * @return config path of this ApplicationInstance
        */
        std::string getConfigPath();
        bool isConfigWritable();
 
        ScenarioPtr getScenario();
 
        /**
        * Sets the config path of this ApplicationInstance
        * @param new config path
        */
        void setConfigPath(std::string configPath);
 
        /**
         * @brief resetConfigPath. should be called when the instanceName is changed/ deletes the old cfg file and resets the local config Path to where the file should be
         * you should call save after this
         */
        void resetConfigPath();
 
        /**
        * Returns the status. Doesn't update automatically, is not necessarily synchronized with
        * the actual status of the process. Use the Executor to get the actual status of this application.
        * @return status of this ApplicationInstance
        * @see Executor
        */
        std::string getStatus();
 
        /**
        * Sets the status of this ApplicationInstance
        * @param new status. Should be either "running" or "stopped" for Scenario statuses to work
        * properly.
        * @return tree if status changed.
        */
        bool setStatus(const std::string& status);
 
        std::string getNodeName() const;
        std::string getEffectiveNodeName() const;
        void setNodeName(std::string nodeName);
 
        /**
        * @return pid of this ApplicationInstance
        */
        int getPid();
 
        /**
        * Sets the pid of this ApplicationInstance. This pid gets used by the Executor to
        * stop this application, therefore it is not suggested to set this to random values.
        * Set this to -1, if no pid is known.
        * @param pid new pid
        */
        void setPid(int pid);
 
        /**
         * Sets the pid to -1, but only if it is still `expectedPid`.
         *
         * The status poller and the starter/stopper threads all inspect and update the pid
         * concurrently. Whoever observes that a process has died must clear only the pid it
         * actually probed - an unconditional reset can wipe the pid a concurrent start has just
         * stored, which would leave a running application marked as stopped indefinitely.
         *
         * @return whether the pid was reset.
         */
        bool compareAndResetPid(int expectedPid);
 
        /**
         * Sets the pid to `newPid`, but only if no pid is currently known (i.e. it is -1).
         * Used when adopting a pid cached on disk, so that a concurrently started process wins.
         * @return whether the pid was set.
         */
        bool adoptPidIfUnset(int newPid);
 
        /**
        * Changes the value of the specified property.
        * @param name name of the property whose value is to be changed
        * @param value new value of the property
        */
        void modifyProperty(std::string name, std::string value);
 
        /**
        * Adds a new property with the specified name and value to this ApplicationInstance.
        * @param name name of the new property
        * @param value value of the new property
        */
        void addProperty(std::string name, std::string value);
 
 
        /**
        * Saves the IceProperties to the configPath
        */
        void save();
 
        /**
         * Make a local copy of this instance if it is linked and nothing otherwise
         */
        void makeLocal();
 
        /**
         * @brief linkFrom Link this instance configuration from the other instance.
         * @param other the source instance
         */
        void linkFrom(ApplicationInstance& other);
 
        /**
         * @brief copyFrom Copy the other instance configuration to this one.
         * @param other the instance to copy
         */
        void copyFrom(ApplicationInstance& other);
 
        void deleteConfig();
 
        /**
        * Loades the IceProperties from the configPath
        * Firstload determins if properties that equal their default value get uncommented
        */
        void load(bool firstLoad = false);
 
        /**
        * The intent this application is currently moving towards, or None when idle.
        *
        * Written by the ApplicationLifecycle that owns the application, so it is up to date as
        * soon as a request has been made rather than only after the next status poll. The GUI uses
        * it both to show the application as "Waiting" and to grey out the button of the operation
        * that is under way.
        */
        Intent getPendingIntent() const;
        void setPendingIntent(Intent intent);
 
 
        bool getEnabled();
        void setEnabled(bool enabled);
 
        std::string getConfigDomain() const;
        void setConfigDomain(const std::string& value);
 
        bool isReadOnly() const;
    };
} // namespace ScenarioManager::Data_Structure