Process.h

Go to the documentation of this file.

/*
 * Copyright (C) 2012 by
 *   MetraLabs GmbH (MLAB), GERMANY
 * and
 *   Neuroinformatics and Cognitive Robotics Labs (NICR) at TU Ilmenau, GERMANY
 * All rights reserved.
 *
 * Contact: info@mira-project.org
 *
 * Commercial Usage:
 *   Licensees holding valid commercial licenses may use this file in
 *   accordance with the commercial license agreement provided with the
 *   software or, alternatively, in accordance with the terms contained in
 *   a written agreement between you and MLAB or NICR.
 *
 * GNU General Public License Usage:
 *   Alternatively, this file may be used under the terms of the GNU
 *   General Public License version 3.0 as published by the Free Software
 *   Foundation and appearing in the file LICENSE.GPL3 included in the
 *   packaging of this file. Please review the following information to
 *   ensure the GNU General Public License version 3.0 requirements will be
 *   met: http://www.gnu.org/copyleft/gpl.html.
 *   Alternatively you may (at your option) use any later version of the GNU
 *   General Public License if such license has been publicly approved by
 *   MLAB and NICR (or its successors, if any).
 *
 * IN NO EVENT SHALL "MLAB" OR "NICR" BE LIABLE TO ANY PARTY FOR DIRECT,
 * INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
 * THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF "MLAB" OR
 * "NICR" HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * "MLAB" AND "NICR" SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
 * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
 * FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND "MLAB" AND "NICR" HAVE NO OBLIGATION TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS OR MODIFICATIONS.
 */

#ifndef _MIRA_EXECUTEPROCESS_H_
#define _MIRA_EXECUTEPROCESS_H_

#include <string>
#include <vector>

#ifndef Q_MOC_RUN
#include <boost/noncopyable.hpp>
#include <boost/optional.hpp>
#include <boost/iostreams/device/file_descriptor.hpp>
#include <boost/iostreams/stream.hpp>
#endif

#include <platform/Platform.h>

#include <utils/EnumToFlags.h>
#include <utils/Time.h>

#ifdef MIRA_LINUX
#  include <unistd.h>
#endif


namespace mira {


MIRA_BASE_EXPORT int executeProcess(const std::string& cmd, 
                                    std::string* oStdOut=NULL,
                                    std::string* oErrOut=NULL);


class MIRA_BASE_EXPORT Process : boost::noncopyable
{
public:
    enum ExitStatus
    {
        NORMALEXIT,
        CRASHED,
        KILLED,
    };



public:

    class MIRA_BASE_EXPORT Environment
    {
    public:
        Environment() {};
        Environment(const Environment& other);
        Environment(Environment&& other) noexcept;

        Environment& operator=(const Environment& other);
        Environment& operator=(Environment&& other) noexcept;

    public:
        void clear();

        bool empty() const;

        void insert(const std::string& var, const std::string& value);

        void insert(const std::string& string);

        void insertList(const std::string& string);

        void insert(const Environment& env);

        void remove(const std::string& var);

        const std::string& value(const std::string& var, const std::string& defaultValue = std::string()) const;

        std::vector<std::string> envp();


    public:

        const std::map<std::string,std::string>& variables() const { return mVariables; }

    public:

        // Returns the environment of the calling process.
        static Environment systemEnvironment();

    private:
        std::map<std::string,std::string> mVariables;

    };



public:


    Process();

    ~Process();

    // move constructor and move assignment op to support move semantics.
    Process(Process&& other) noexcept;
    Process& operator=(Process&& other) noexcept;

public:

    void swap(Process& other);

public:

    enum CreationFlags {
        noflags = 0x00,

        interruptChildOnParentDeath  = 0x01,

        shutdownRecursively = 0x02

    };
    MIRA_ENUM_TO_FLAGS_INCLASS(CreationFlags)

    enum RedirectionFlags {
        none  = 0x00,
        in    = 0x01,
        out   = 0x02,
        err   = 0x04
    };
    MIRA_ENUM_TO_FLAGS_INCLASS(RedirectionFlags)


    
    static Process createProcess(const std::string& commandLine,
                                 CreationFlags flags,
                                 RedirectionFlags streamRedirection = none);

    static Process createProcess(const std::string& commandLine,
                                 RedirectionFlags streamRedirection = none);

    static Process createProcess(const std::string& applicationName,
                                 const std::vector<std::string>& args,
                                 CreationFlags flags = noflags,
                                 RedirectionFlags streamRedirection = none,
                                 boost::optional<Environment> env = boost::optional<Environment>());




public:

    bool wait(Duration maxWait = Duration::infinity());

    int getExitCode();

    ExitStatus getExitStatus();
    bool isRunning();

    void interrupt();
    void terminate();

    void kill();

    void setRecursiveShutdown(bool recursive);

    void shutdown(Duration timeout = Duration::seconds(5));

    uint32 getPID() const;

public:

    typedef boost::iostreams::stream<boost::iostreams::file_descriptor_sink> ostream;
    typedef boost::iostreams::stream<boost::iostreams::file_descriptor_source> istream;

    ostream& cin();

    istream& cout();

    istream& cerr();

protected:

    bool wait(int pid, std::vector<int>& children, Duration timeout = Duration::seconds(5));
    std::vector<int> getRecursiveChildProcesses(int pid, int maxDepth = -1);
    bool interrupt(int pid);
    bool terminate(int pid);
    bool kill(int pid);
    void shutdown(int pid, Duration timeout = Duration::seconds(5));

private:

#ifdef MIRA_WINDOWS
    //PROCESS_INFORMATION mProcess; //  process information (handle, etc)
#endif

#ifdef MIRA_LINUX
    pid_t mProcess; // handle of the process
#endif

    int mExitCode;
    ExitStatus mExitStatus;

    bool mShutdownRecursively;

    boost::shared_ptr<ostream> mCinFd;
    boost::shared_ptr<istream> mCoutFd;
    boost::shared_ptr<istream> mCerrFd;

};


}

#endif