ProcessUtil.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 <chrono>
#include <optional>
#include <string>
#include <vector>
 
namespace ScenarioManager::Exec::ProcessUtil
{
    /**
     * @return whether the process with the given pid has terminated but has not been reaped yet.
     *
     * A zombie still occupies its pid and still has a /proc entry, but it is dead: it cannot be
     * signalled, it will never run again, and it disappears only once somebody waits for it.
     * `pid <= 0` is never a zombie.
     */
    bool IsZombie(int pid);
 
    /**
     * @return whether a process with the given pid currently exists *and has not terminated*.
     * `pid <= 0` is never alive.
     *
     * Zombies are deliberately not alive. The whole point of asking is to decide whether there is
     * still a process there to wait for, to signal, or to refuse a start over, and for a zombie the
     * answer to all three is no - waiting for one to disappear runs into the full timeout, and
     * signalling one is silently discarded (kill() even reports success).
     */
    bool IsAlive(int pid);
 
    /**
     * Reads the name of the executable behind `pid` (the basename of argv[0]).
     *
     * Returns an empty string if the name could not be determined. That is *not* the same as
     * "the process is gone": a process that has been forked but has not reached execve() yet, a
     * zombie and a process we are not allowed to inspect all report an empty name while being
     * very much alive. Callers must use IsAlive() to tell the two cases apart before drawing
     * conclusions about the process' status.
     */
    std::string GetProcessName(int pid);
 
    /**
     * Reads the full argument vector of `pid` from /proc/<pid>/cmdline.
     *
     * Returns an empty vector when it cannot be read - see GetProcessName() for why that does not
     * imply the process is gone.
     */
    std::vector<std::string> GetProcessArguments(int pid);
 
    /**
     * A live process as seen by ScanProcesses().
     */
    struct ProcessInfo
    {
        int pid = -1;
        /// Basename of argv[0].
        std::string name;
        /// The full argument vector, argv[0] included.
        std::vector<std::string> arguments;
    };
 
    /**
     * Walks /proc and returns every process whose argument vector could be read.
     *
     * This is the only way to find an application the ScenarioManager did not launch itself (or
     * whose pid it lost), since nothing else ties a running process back to an application.
     * Processes that cannot be read - other users' processes, or ones exiting while we walk - are
     * silently skipped.
     *
     * The walk costs one open() per process on the machine, so callers are expected to do it for
     * all applications at once rather than per application, and not on every status poll.
     */
    std::vector<ProcessInfo> ScanProcesses();
 
    /**
     * @return the value of the `--Ice.Config=` argument in `arguments`, if there is one.
     */
    std::optional<std::string> FindIceConfigArgument(const std::vector<std::string>& arguments);
 
    /**
     * Whether the process behind a pid still is the one we think it is.
     */
    enum class Identity
    {
        /// argv says this is the expected executable, and it does not claim a foreign config.
        Matches,
        /// argv says this is a different program, or the same program serving a different config.
        Differs,
        /// argv could not be read, so nothing can be concluded either way. A zombie, a process
        /// forked but not yet exec'd, and a process we may not inspect all land here.
        Unverifiable
    };
 
    /**
     * Checks whether the process with the given pid is still the application it is supposed to be.
     *
     * Pids are recycled. Once the process an application was launched as has exited, the kernel is
     * free to hand its pid to something completely unrelated, and from that moment on every
     * conclusion drawn from `/proc/<pid>` is about a stranger: the application looks alive when it
     * is not, a start is refused because "it is already running", and a stop signals - possibly
     * kills - an innocent process.
     *
     * `configPath` is the stronger of the two criteria and catches a pid recycled by *another*
     * instance of the same binary; it is only applied when the process carries an `--Ice.Config`
     * at all, since an application started by hand from a shell legitimately has none.
     *
     * @param executableName basename of the application's executable.
     * @param configPath the application's config file; may be empty, in which case only the name
     * is compared.
     */
    Identity IdentifyProcess(int pid,
                             const std::string& executableName,
                             const std::string& configPath);
 
    /**
     * Blocks until the process with the given pid has disappeared, at most for `timeout`.
     * @return true if the process is gone, false if it was still alive when `timeout` elapsed.
     */
    bool WaitForExit(int pid,
                     std::chrono::milliseconds timeout,
                     std::chrono::milliseconds pollInterval = std::chrono::milliseconds(20));
} // namespace ScenarioManager::Exec::ProcessUtil