ApplicationLifecycle.h

Go to the documentation of this file.

/*
 * This file is part of ArmarX.
 *
 * 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
 * @copyright  http://www.gnu.org/licenses/gpl-2.0.txt
 *             GNU General Public License
 */
 
#pragma once
 
#include <condition_variable>
#include <memory>
#include <mutex>
#include <shared_mutex>
#include <string>
 
#include "../data_structure/ApplicationInstance.h"
#include "../parser/StatusManager.h"
#include "ApplicationStarter.h"
#include "StopStrategy.h"
 
namespace ScenarioManager::Exec
{
    class ApplicationLifecycle;
    using ApplicationLifecyclePtr = std::shared_ptr<ApplicationLifecycle>;
 
    /**
     * Serializes the actual spawning of applications.
     *
     * Every launch forks this process, and forking a GUI with Qt, Ice and the whole scenario model
     * mapped is expensive. Starting a scenario asks every one of its applications to start at the
     * same time, so without this the process would fork N times concurrently and stall - including
     * the GUI thread. Held only around the spawn itself, never around a wait.
     */
    std::mutex& LaunchMutex();
 
    /**
     * Held *shared* by every application operation, and *exclusively* by global operations that
     * act on all armarx processes at once, such as `armarx killAll`.
     *
     * This is what gives "kill everything" a defined outcome: a start requested while a kill-all is
     * running waits for it and then runs, rather than racing it and leaving an application alive
     * that was supposed to be killed.
     */
    std::shared_mutex& GlobalOperationMutex();
 
    /**
     * @class ApplicationLifecycle
     * @ingroup exec
     * @brief Owns every start and stop of one application - nothing else may launch or signal it.
     *
     * Callers do not execute operations, they *request an intent*. Requesting an intent supersedes
     * any intent that has not been carried out yet, so pressing Start, Stop, Start, Stop in quick
     * succession runs at most one superfluous operation and always ends in the state the last press
     * asked for ("last intent wins"). Nothing is ever refused and nothing is ever aborted halfway:
     * a fork/exec or a wait for a process to die always runs to completion, and a newer intent is
     * only picked up at a phase boundary.
     *
     * The reason this class exists is that lifecycle state used to be owned by three classes at
     * once - the Executor set a "write block" flag, the starter cleared it in a scope guard and the
     * stop strategy cleared it as well. A restart's internal stop therefore released the flag that
     * the restart itself still needed, which let a concurrent start launch a second process that
     * the ScenarioManager then lost track of.
     *
     * Threading: a worker thread is spawned on demand and exits as soon as there is nothing left to
     * do, so only applications that are currently being operated on cost a thread. The worker holds
     * a shared_ptr to this object and to the application, so neither can be destroyed underneath it.
     */
    class ApplicationLifecycle : public std::enable_shared_from_this<ApplicationLifecycle>
    {
    public:
        ApplicationLifecycle(Data_Structure::ApplicationInstancePtr application,
                             StatusManager statusManager);
 
        /**
         * Requests that the application be started, stopped or restarted, superseding any intent
         * that has not been executed yet. Returns immediately; the work happens on a worker thread.
         *
         * @param intent what should happen to the application
         * @param starter used to launch the application
         * @param stopStrategy used to terminate the application
         */
        void request(Data_Structure::Intent intent,
                     const ApplicationStarterPtr& starter,
                     const StopStrategyPtr& stopStrategy,
                     const std::string& commandLineParameters = "",
                     bool printOnly = false);
 
        /**
         * @return the intent the application is moving towards: the superseding one if a newer
         * request has arrived, otherwise the one being executed, or None when idle.
         */
        Data_Structure::Intent effectiveIntent() const;
 
        /// @return whether an operation is requested or running.
        bool busy() const;
 
        /**
         * Blocks until nothing is requested or running any more.
         *
         * Meant for callers that have to see the operation through before they can go away, such
         * as the command line interface, which would otherwise exit while the worker is still
         * launching. Returns immediately when the application is already idle.
         */
        void wait();
 
    private:
        struct Request
        {
            Data_Structure::Intent intent = Data_Structure::Intent::None;
            ApplicationStarterPtr starter;
            StopStrategyPtr stopStrategy;
            std::string commandLineParameters;
            bool printOnly = false;
        };
 
        /// Worker loop: execute the pending request, then whatever superseded it, then exit.
        void run();
 
        void execute(const Request& request);
        void executeStart(const Request& request);
        void executeStop(const Request& request);
        void executeRestart(const Request& request);
 
        /// Loads the property definitions the launch needs (notably the config domain).
        void prepare();
        void launch(const Request& request);
        void stopAndWait(const Request& request);
 
        /// @return whether the application currently has a live process. Clears a stale pid.
        bool isRunning();
 
        /**
         * @return whether a newer request has made the rest of the running operation pointless.
         * Only a superseding Stop can do that: any other intent still wants the application up, so
         * finishing the current operation first is both correct and cheaper.
         */
        bool supersededByStop() const;
 
        /// Publishes effectiveIntent() on the application for the GUI. Call with `mutex` held.
        void publishIntent();
 
        Data_Structure::ApplicationInstancePtr application;
        StatusManager statusManager;
 
        mutable std::mutex mutex;
        std::condition_variable idleCondition;
        Request pending;
        Request current;
        bool workerRunning = false;
    };
} // namespace ScenarioManager::Exec