path: root/indra/llcommon/llprocess.h

/**
 * @file llprocess.h
 * @brief Utility class for launching, terminating, and tracking child processes.
 *
 * $LicenseInfo:firstyear=2008&license=viewerlgpl$
 * Second Life Viewer Source Code
 * Copyright (C) 2010, Linden Research, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation;
 * version 2.1 of the License only.
 *
 * This library 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
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 *
 * Linden Research, Inc., 945 Battery Street, San Francisco, CA  94111  USA
 * $/LicenseInfo$
 */

#ifndef LL_LLPROCESS_H
#define LL_LLPROCESS_H

#include "llinitparam.h"
#include "llsdparam.h"
#include "llwin32headerslean.h"
#include "llexception.h"
#include "apr_thread_proc.h"
#include <boost/shared_ptr.hpp>
#include <boost/ptr_container/ptr_vector.hpp>
#include <boost/optional.hpp>
#include <boost/noncopyable.hpp>
#include <iosfwd>                   // std::ostream

#if LL_WINDOWS
#include "llwin32headerslean.h" // for HANDLE
#elif LL_LINUX || __FreeBSD__
#if defined(Status)
#undef Status
#endif
#endif

class LLEventPump;

class LLProcess;
/// LLProcess instances are created on the heap by static factory methods and
/// managed by ref-counted pointers.
typedef std::shared_ptr<LLProcess> LLProcessPtr;

/**
 * LLProcess handles launching an external process with specified command line
 * arguments. It also keeps track of whether the process is still running, and
 * can kill it if required.
 *
 * In discussing LLProcess, we use the term "parent" to refer to this process
 * (the process invoking LLProcess), versus "child" to refer to the process
 * spawned by LLProcess.
 *
 * LLProcess relies on periodic post() calls on the "mainloop" LLEventPump: an
 * LLProcess object's Status won't update until the next "mainloop" tick. For
 * instance, the Second Life viewer's main loop already posts to an
 * LLEventPump by that name once per iteration. See
 * indra/llcommon/tests/llprocess_test.cpp for an example of waiting for
 * child-process termination in a standalone test context.
 */
class LL_COMMON_API LLProcess: public boost::noncopyable
{
    LOG_CLASS(LLProcess);
public:
    /**
     * Specify what to pass for each of child stdin, stdout, stderr.
     * @see LLProcess::Params::files.
     */
    struct FileParam: public LLInitParam::Block<FileParam>
    {
        /**
         * type of file handle to pass to child process
         *
         * - "" (default): let the child inherit the same file handle used by
         *   this process. For instance, if passed as stdout, child stdout
         *   will be interleaved with stdout from this process. In this case,
         *   @a name is moot and should be left "".
         *
         * - "file": open an OS filesystem file with the specified @a name.
         *   <i>Not yet implemented.</i>
         *
         * - "pipe" or "tpipe" or "npipe": depends on @a name
         *
         *   - @a name.empty(): construct an OS pipe used only for this slot
         *     of the forthcoming child process.
         *
         *   - ! @a name.empty(): in a global registry, find or create (using
         *     the specified @a name) an OS pipe. The point of the (purely
         *     internal) @a name is that passing the same @a name in more than
         *     one slot for a given LLProcess -- or for slots in different
         *     LLProcess instances -- means the same pipe. For example, you
         *     might pass the same @a name value as both stdout and stderr to
         *     make the child process produce both on the same actual pipe. Or
         *     you might pass the same @a name as the stdout for one LLProcess
         *     and the stdin for another to connect the two child processes.
         *     Use LLProcess::getPipeName() to generate a unique name
         *     guaranteed not to already exist in the registry. <i>Not yet
         *     implemented.</i>
         *
         *   The difference between "pipe", "tpipe" and "npipe" is as follows.
         *
         *   - "pipe": direct LLProcess to monitor the parent end of the pipe,
         *     pumping nonblocking I/O every frame. The expectation (at least
         *     for stdout or stderr) is that the caller will listen for
         *     incoming data and consume it as it arrives. It's important not
         *     to neglect such a pipe, because it's buffered in memory. If you
         *     suspect the child may produce a great volume of output between
         *     frames, consider directing the child to write to a filesystem
         *     file instead, then read the file later.
         *
         *   - "tpipe": do not engage LLProcess machinery to monitor the
         *     parent end of the pipe. A "tpipe" is used only to connect
         *     different child processes. As such, it makes little sense to
         *     pass an empty @a name. <i>Not yet implemented.</i>
         *
         *   - "npipe": like "tpipe", but use an OS named pipe with a
         *     generated name. Note that @a name is the @em internal name of
         *     the pipe in our global registry -- it doesn't necessarily have
         *     anything to do with the pipe's name in the OS filesystem. Use
         *     LLProcess::getPipeName() to obtain the named pipe's OS
         *     filesystem name, e.g. to pass it as the @a name to another
         *     LLProcess instance using @a type "file". This supports usage
         *     like bash's &lt;(subcommand...) or &gt;(subcommand...)
         *     constructs. <i>Not yet implemented.</i>
         *
         * In all cases the open mode (read, write) is determined by the child
         * slot you're filling. Child stdin means select the "read" end of a
         * pipe, or open a filesystem file for reading; child stdout or stderr
         * means select the "write" end of a pipe, or open a filesystem file
         * for writing.
         *
         * Confusion such as passing the same pipe as the stdin of two
         * processes (rather than stdout for one and stdin for the other) is
         * explicitly permitted: it's up to the caller to construct meaningful
         * LLProcess pipe graphs.
         */
        Optional<std::string> type;
        Optional<std::string> name;

        FileParam(const std::string& tp="", const std::string& nm=""):
            type("type"),
            name("name")
        {
            // If caller wants to specify values, use explicit assignment to
            // set them rather than initialization.
            if (! tp.empty()) type = tp;
            if (! nm.empty()) name = nm;
        }
    };

    /// Param block definition
    struct Params: public LLInitParam::Block<Params>
    {
        Params():
            executable("executable"),
            args("args"),
            envs("envs"),
            cwd("cwd"),
            autokill("autokill", true),
            attached("attached", true),
            files("files"),
            postend("postend"),
            desc("desc")
        {}

        /// pathname of executable
        Mandatory<std::string> executable;
        /**
         * zero or more additional command-line arguments. Arguments are
         * passed through as exactly as we can manage, whitespace and all.
         * @note On Windows we manage this by implicitly double-quoting each
         * argument while assembling the command line.
         */
        Multiple<std::string> args;
        /**
         * zero or more additional command-line environment values.
         */
        Multiple<std::string> envs;
        /// current working directory, if need it changed
        Optional<std::string> cwd;
        /// implicitly kill child process on termination of parent, whether
        /// voluntary or crash (default true)
        Optional<bool> autokill;
        /// implicitly kill process on destruction of LLProcess object
        /// (default same as autokill)
        ///
        /// Originally, 'autokill' conflated two concepts: kill child process on
        /// - destruction of its LLProcess object, and
        /// - termination of parent process, voluntary or otherwise.
        ///
        /// It's useful to tease these apart. Some child processes are sent a
        /// "clean up and terminate" message before the associated LLProcess
        /// object is destroyed. A child process launched with attached=false
        /// has an extra time window from the destruction of its LLProcess
        /// until parent-process termination in which to perform its own
        /// orderly shutdown, yet autokill=true still guarantees that we won't
        /// accumulate orphan instances of such processes indefinitely. With
        /// attached=true, if a child process cannot clean up between the
        /// shutdown message and LLProcess destruction (presumably very soon
        /// thereafter), it's forcibly killed anyway -- which can lead to
        /// distressing user-visible crash indications.
        ///
        /// (The usefulness of attached=true with autokill=false is less
        /// clear, but we don't prohibit that combination.)
        Optional<bool> attached;
        /**
         * Up to three FileParam items: for child stdin, stdout, stderr.
         * Passing two FileParam entries means default treatment for stderr,
         * and so forth.
         *
         * @note LLInitParam::Block permits usage like this:
         * @code
         * LLProcess::Params params;
         * ...
         * params.files
         *     .add(LLProcess::FileParam()) // stdin
         *     .add(LLProcess::FileParam().type("pipe") // stdout
         *     .add(LLProcess::FileParam().type("file").name("error.log"));
         * @endcode
         *
         * @note While it's theoretically plausible to pass additional open
         * file handles to a child specifically written to expect them, our
         * underlying implementation doesn't yet support that.
         */
        Multiple<FileParam, AtMost<3> > files;
        /**
         * On child-process termination, if this LLProcess object still
         * exists, post LLSD event to LLEventPump with specified name (default
         * no event). Event contains at least:
         *
         * - "id" as obtained from getProcessID()
         * - "desc" short string description of child (executable + pid)
         * - "state" @c state enum value, from Status.mState
         * - "data"  if "state" is EXITED, exit code; if KILLED, on Posix,
         *   signal number
         * - "string" English text describing "state" and "data" (e.g. "exited
         *   with code 0")
         */
        Optional<std::string> postend;
        /**
         * Description of child process for logging purposes. It need not be
         * unique; the logged description string will contain the PID as well.
         * If this is omitted, a description will be derived from the
         * executable name.
         */
        Optional<std::string> desc;
    };
    typedef LLSDParamAdapter<Params> LLSDOrParams;

    /**
     * Factory accepting either plain LLSD::Map or Params block.
     * MAY RETURN DEFAULT-CONSTRUCTED LLProcessPtr if params invalid!
     */
    static LLProcessPtr create(const LLSDOrParams& params);
    virtual ~LLProcess();

    /// Is child process still running?
    bool isRunning() const;
    // static isRunning(LLProcessPtr), getStatus(LLProcessPtr),
    // getStatusString(LLProcessPtr), kill(LLProcessPtr) handle the case in
    // which the passed LLProcessPtr might be NULL (default-constructed).
    static bool isRunning(const LLProcessPtr&);

    /**
     * State of child process
     */
    enum state
    {
        UNSTARTED,                  ///< initial value, invisible to consumer
        RUNNING,                    ///< child process launched
        EXITED,                     ///< child process terminated voluntarily
        KILLED                      ///< child process terminated involuntarily
    };

    /**
     * Status info
     */
    struct Status
    {
        Status():
            mState(UNSTARTED),
            mData(0)
        {}

        state mState;               ///< @see state
        /**
         * - for mState == EXITED: mData is exit() code
         * - for mState == KILLED: mData is signal number (Posix)
         * - otherwise: mData is undefined
         */
        int mData;
    };

    /// Status query
    Status getStatus() const;
    static Status getStatus(const LLProcessPtr&);
    /// English Status string query, for logging etc.
    std::string getStatusString() const;
    static std::string getStatusString(const std::string& desc, const LLProcessPtr&);
    /// English Status string query for previously-captured Status
    std::string getStatusString(const Status& status) const;
    /// static English Status string query
    static std::string getStatusString(const std::string& desc, const Status& status);

    // Attempt to kill the process -- returns true if the process is no longer running when it returns.
    // Note that even if this returns false, the process may exit some time after it's called.
    bool kill(const std::string& who="");
    static bool kill(const LLProcessPtr& p, const std::string& who="");

#if LL_WINDOWS
    typedef int id;                 ///< as returned by getProcessID()
    typedef HANDLE handle;          ///< as returned by getProcessHandle()
#else
    typedef pid_t id;
    typedef pid_t handle;
#endif
    /**
     * Get an int-like id value. This is primarily intended for a human reader
     * to differentiate processes.
     */
    id getProcessID() const;
    /**
     * Get a "handle" of a kind that you might pass to platform-specific API
     * functions to engage features not directly supported by LLProcess.
     */
    handle getProcessHandle() const;

    /**
     * Test if a process (@c handle obtained from getProcessHandle()) is still
     * running. Return same nonzero @c handle value if still running, else
     * zero, so you can test it like a bool. But if you want to update a
     * stored variable as a side effect, you can write code like this:
     * @code
     * hchild = LLProcess::isRunning(hchild);
     * @endcode
     * @note This method is intended as a unit-test hook, not as the first of
     * a whole set of operations supported on freestanding @c handle values.
     * New functionality should be added as nonstatic members operating on
     * the same data as getProcessHandle().
     *
     * In particular, if child termination is detected by this static isRunning()
     * rather than by nonstatic isRunning(), the LLProcess object won't be
     * aware of the child's changed status and may encounter OS errors trying
     * to obtain it. This static isRunning() is only intended for after the
     * launching LLProcess object has been destroyed.
     */
    static handle isRunning(handle, const std::string& desc="");

    /// Provide symbolic access to child's file slots
    enum FILESLOT { STDIN=0, STDOUT=1, STDERR=2, NSLOTS=3 };

    /**
     * For a pipe constructed with @a type "npipe", obtain the generated OS
     * filesystem name for the specified pipe. Otherwise returns the empty
     * string. @see LLProcess::FileParam::type
     */
    std::string getPipeName(FILESLOT) const;

    /// base of ReadPipe, WritePipe
    class LL_COMMON_API BasePipe
    {
    public:
        virtual ~BasePipe() = 0;

        typedef std::size_t size_type;
        static const size_type npos;

        /**
         * Get accumulated buffer length.
         *
         * For WritePipe, is there still pending data to send to child?
         *
         * For ReadPipe, we often need to refrain from actually reading the
         * std::istream returned by get_istream() until we've accumulated
         * enough data to make it worthwhile. For instance, if we're expecting
         * a number from the child, but the child happens to flush "12" before
         * emitting "3\n", get_istream() >> myint could return 12 rather than
         * 123!
         */
        virtual size_type size() const = 0;
    };

    /// As returned by getWritePipe() or getOptWritePipe()
    class WritePipe: public BasePipe
    {
    public:
        /**
         * Get ostream& on which to write to child's stdin.
         *
         * @usage
         * @code
         * myProcess->getWritePipe().get_ostream() << "Hello, child!" << std::endl;
         * @endcode
         */
        virtual std::ostream& get_ostream() = 0;
    };

    /// As returned by getReadPipe() or getOptReadPipe()
    class ReadPipe: public BasePipe
    {
    public:
        /**
         * Get istream& on which to read from child's stdout or stderr.
         *
         * @usage
         * @code
         * std::string stuff;
         * myProcess->getReadPipe().get_istream() >> stuff;
         * @endcode
         *
         * You should be sure in advance that the ReadPipe in question can
         * fill the request. @see getPump()
         */
        virtual std::istream& get_istream() = 0;

        /**
         * Like std::getline(get_istream(), line), but trims off trailing '\r'
         * to make calling code less platform-sensitive.
         */
        virtual std::string getline() = 0;

        /**
         * Like get_istream().read(buffer, n), but returns std::string rather
         * than requiring caller to construct a buffer, etc.
         */
        virtual std::string read(size_type len) = 0;

        /**
         * Peek at accumulated buffer data without consuming it. Optional
         * parameters give you substr() functionality.
         *
         * @note You can discard buffer data using get_istream().ignore(n).
         */
        virtual std::string peek(size_type offset=0, size_type len=npos) const = 0;

        /**
         * Detect presence of a substring (or char) in accumulated buffer data
         * without retrieving it. Optional offset allows you to search from
         * specified position.
         */
        template <typename SEEK>
        bool contains(SEEK seek, size_type offset=0) const
        { return find(seek, offset) != npos; }

        /**
         * Search for a substring in accumulated buffer data without
         * retrieving it. Returns size_type position at which found, or npos
         * meaning not found. Optional offset allows you to search from
         * specified position.
         */
        virtual size_type find(const std::string& seek, size_type offset=0) const = 0;

        /**
         * Search for a char in accumulated buffer data without retrieving it.
         * Returns size_type position at which found, or npos meaning not
         * found. Optional offset allows you to search from specified
         * position.
         */
        virtual size_type find(char seek, size_type offset=0) const = 0;

        /**
         * Get LLEventPump& on which to listen for incoming data. The posted
         * LLSD::Map event will contain:
         *
         * - "data" part of pending data; see setLimit()
         * - "len" entire length of pending data, regardless of setLimit()
         * - "slot" this ReadPipe's FILESLOT, e.g. LLProcess::STDOUT
         * - "name" e.g. "stdout"
         * - "desc" e.g. "SLPlugin (pid) stdout"
         * - "eof" @c true means there no more data will arrive on this pipe,
         *   therefore no more events on this pump
         *
         * If the child sends "abc", and this ReadPipe posts "data"="abc", but
         * you don't consume it by reading the std::istream returned by
         * get_istream(), and the child next sends "def", ReadPipe will post
         * "data"="abcdef".
         */
        virtual LLEventPump& getPump() = 0;

        /**
         * Set maximum length of buffer data that will be posted in the LLSD
         * announcing arrival of new data from the child. If you call
         * setLimit(5), and the child sends "abcdef", the LLSD event will
         * contain "data"="abcde". However, you may still read the entire
         * "abcdef" from get_istream(): this limit affects only the size of
         * the data posted with the LLSD event. If you don't call this method,
         * @em no data will be posted: the default is 0 bytes.
         */
        virtual void setLimit(size_type limit) = 0;

        /**
         * Query the current setLimit() limit.
         */
        virtual size_type getLimit() const = 0;
    };

    /// Exception thrown by getWritePipe(), getReadPipe() if you didn't ask to
    /// create a pipe at the corresponding FILESLOT.
    struct NoPipe: public LLException
    {
        NoPipe(const std::string& what): LLException(what) {}
    };

    /**
     * Get a reference to the (only) WritePipe for this LLProcess. @a slot, if
     * specified, must be STDIN. Throws NoPipe if you did not request a "pipe"
     * for child stdin. Use this method when you know how you created the
     * LLProcess in hand.
     */
    WritePipe& getWritePipe(FILESLOT slot=STDIN);

    /**
     * Get a boost::optional<WritePipe&> to the (only) WritePipe for this
     * LLProcess. @a slot, if specified, must be STDIN. The return value is
     * empty if you did not request a "pipe" for child stdin. Use this method
     * for inspecting an LLProcess you did not create.
     */
    boost::optional<WritePipe&> getOptWritePipe(FILESLOT slot=STDIN);

    /**
     * Get a reference to one of the ReadPipes for this LLProcess. @a slot, if
     * specified, must be STDOUT or STDERR. Throws NoPipe if you did not
     * request a "pipe" for child stdout or stderr. Use this method when you
     * know how you created the LLProcess in hand.
     */
    ReadPipe& getReadPipe(FILESLOT slot);

    /**
     * Get a boost::optional<ReadPipe&> to one of the ReadPipes for this
     * LLProcess. @a slot, if specified, must be STDOUT or STDERR. The return
     * value is empty if you did not request a "pipe" for child stdout or
     * stderr. Use this method for inspecting an LLProcess you did not create.
     */
    boost::optional<ReadPipe&> getOptReadPipe(FILESLOT slot);

    /// little utilities that really should already be somewhere else in the
    /// code base
    static std::string basename(const std::string& path);
    static std::string getline(std::istream&);

private:
    /// constructor is private: use create() instead
    LLProcess(const LLSDOrParams& params);
    void autokill();
    // Classic-C-style APR callback
    static void status_callback(int reason, void* data, int status);
    // Object-oriented callback
    void handle_status(int reason, int status);
    // implementation for get[Opt][Read|Write]Pipe()
    template <class PIPETYPE>
    PIPETYPE& getPipe(FILESLOT slot);
    template <class PIPETYPE>
    boost::optional<PIPETYPE&> getOptPipe(FILESLOT slot);
    template <class PIPETYPE>
    PIPETYPE* getPipePtr(std::string& error, FILESLOT slot);

    std::string mDesc;
    std::string mPostend;
    apr_proc_t mProcess;
    bool mAutokill, mAttached;
    Status mStatus;
    // explicitly want this ptr_vector to be able to store NULLs
    typedef boost::ptr_vector< boost::nullable<BasePipe> > PipeVector;
    PipeVector mPipes;
    apr_pool_t* mPool;
};

/// for logging
LL_COMMON_API std::ostream& operator<<(std::ostream&, const LLProcess::Params&);

#endif // LL_LLPROCESS_H