class EE::System::Process¶

Overview¶

#include <process.hpp>

class Process {
public:
    // typedefs

    typedef std::function<void(const char*bytes, size_t n)> ReadFn;

    // enums

    enum Options;

    // structs

    struct Config;

    // construction

    Process();
    Process(const std::string& command, Uint32 options = getDefaultOptions(), const std::unordered_map<std::string, std::string>& environment = {}, const std::string& workingDirectory = "", const size_t& bufferSize = 132072);
    Process(const std::string& command, const std::vector<std::string>& args, Uint32 options = getDefaultOptions(), const std::unordered_map<std::string, std::string>& environment = {}, const std::string& workingDirectory = "", const size_t& bufferSize = 132072);
    ~Process();

    // methods

    static constexpr Uint32 getDefaultOptions();
    static std::vector<std::string> parseArgs(const std::string& str);
    bool create(const std::string& command, Uint32 options = getDefaultOptions(), const std::unordered_map<std::string, std::string>& environment = {}, const std::string& workingDirectory = "");
    bool create(const std::string& command, const std::string& args, Uint32 options = getDefaultOptions(), const std::unordered_map<std::string, std::string>& environment = {}, const std::string& workingDirectory = "");
    bool create(const std::string& command, const std::vector<std::string>& args, Uint32 options = getDefaultOptions(), const std::unordered_map<std::string, std::string>& environment = {}, const std::string& workingDirectory = "");
    void startAsyncRead(ReadFn readStdOut = nullptr, ReadFn readStdErr = nullptr);
    size_t readAllStdOut(std::string& buffer, Time timeout = Time::Zero);
    size_t readStdOut(std::string& buffer);
    size_t readStdOut(char*const buffer, const size_t& size);
    size_t readAllStdErr(std::string& buffer, Time timeout = Time::Zero);
    size_t readStdErr(std::string& buffer);
    size_t readStdErr(char*const buffer, const size_t& size);
    size_t write(const char* buffer, const size_t& size);
    size_t write(const std::string& buffer);
    size_t write(const std::string_view& buffer);
    bool join(int*const returnCodeOut);
    bool kill();
    bool destroy();
    bool isAlive();
    FILE* getStdIn() const;
    FILE* getStdOut() const;
    FILE* getStdErr() const;
    void startShutdown();
    bool isShuttingDown() const;
    bool killed() const;
};

Detailed Documentation¶

Construction¶

Process(const std::string& command, Uint32 options = getDefaultOptions(), const std::unordered_map<std::string, std::string>& environment = {}, const std::string& workingDirectory = "", const size_t& bufferSize = 132072)

Create a process.

Parameters:

command	Command line to execute for this process.
options	A bit field of Options’s to pass.

Process(const std::string& command, const std::vector<std::string>& args, Uint32 options = getDefaultOptions(), const std::unordered_map<std::string, std::string>& environment = {}, const std::string& workingDirectory = "", const size_t& bufferSize = 132072)

Create a process.

Parameters:

command	Command line to execute for this process.
args	Command line arguments
options	A bit field of Options’s to pass.

Methods¶

bool create(const std::string& command, Uint32 options = getDefaultOptions(), const std::unordered_map<std::string, std::string>& environment = {}, const std::string& workingDirectory = "")

Create a process.

Parameters:

command	Command line to execute for this process.
options	A bit field of Options’s to pass.

Returns:

On success true is returned.

bool create(const std::string& command, const std::string& args, Uint32 options = getDefaultOptions(), const std::unordered_map<std::string, std::string>& environment = {}, const std::string& workingDirectory = "")

Create a process.

Parameters:

command	Command line to execute for this process.
args	Command line arguments to execute for this process.
options	A bit field of Options’s to pass.

Returns:

On success true is returned.

bool create(const std::string& command, const std::vector<std::string>& args, Uint32 options = getDefaultOptions(), const std::unordered_map<std::string, std::string>& environment = {}, const std::string& workingDirectory = "")

Create a process.

Parameters:

command	Command line to execute for this process.
args	Command line arguments to execute for this process.
options	A bit field of Options’s to pass.

Returns:

On success true is returned.

void startAsyncRead(ReadFn readStdOut = nullptr, ReadFn readStdErr = nullptr)

Starts a new thread to receive all stdout and stderr data.

size_t readAllStdOut(std::string& buffer, Time timeout = Time::Zero)

Read all standard output from the child process.

The only safe way to read from the standard output of a process during it’s execution is to use the Option::EnableAsync option in conjuction with this method.

Parameters:

buffer

The buffer to read into.

Returns:

The number of bytes actually read into buffer. Can only be 0 if the process has complete.

size_t readStdOut(std::string& buffer)

Read the standard output from the child process.

The only safe way to read from the standard output of a process during it’s execution is to use the Option::EnableAsync option in conjuction with this method.

Parameters:

buffer

The buffer to read into.

Returns:

The number of bytes actually read into buffer. Can only be 0 if the process has complete.

size_t readStdOut(char*const buffer, const size_t& size)

Read the standard output from the child process.

The only safe way to read from the standard output of a process during it’s execution is to use the Option::EnableAsync option in conjuction with this method.

Parameters:

buffer	The buffer to read into.
size	The maximum number of bytes to read.

Returns:

The number of bytes actually read into buffer. Can only be 0 if the process has complete.

size_t readAllStdErr(std::string& buffer, Time timeout = Time::Zero)

Read all the standard error from the child process.

The only safe way to read from the standard error of a process during it’s execution is to use the Option::EnableAsync option in conjuction with this method.

Parameters:

buffer

The buffer to read into.

Returns:

The number of bytes actually read into buffer. Can only be 0 if the process has complete.

size_t readStdErr(std::string& buffer)

Read the standard error from the child process.

The only safe way to read from the standard error of a process during it’s execution is to use the Option::EnableAsync option in conjuction with this method.

Parameters:

buffer

The buffer to read into.

Returns:

The number of bytes actually read into buffer. Can only be 0 if the process has complete.

size_t readStdErr(char*const buffer, const size_t& size)

Read the standard error from the child process.

The only safe way to read from the standard error of a process during it’s execution is to use the Option::EnableAsync option in conjuction with this method.

Parameters:

buffer	The buffer to read into.
size	The maximum number of bytes to read.

Returns:

The number of bytes actually read into buffer. Can only be 0 if the process has complete.

size_t write(const char* buffer, const size_t& size)

Write the standard output from the child process.

Parameters:

buffer	The buffer to write into.
size	The number of bytes to write.

Returns:

The number of bytes actually written into buffer.

size_t write(const std::string& buffer)

Write the standard output from the child process.

Parameters:

buffer

The buffer to write into.

Returns:

The number of bytes actually written into buffer.

size_t write(const std::string_view& buffer)

Write the standard output from the child process.

Parameters:

buffer

The buffer to write into.

Returns:

The number of bytes actually written into buffer.

bool join(int*const returnCodeOut)

Wait for a process to finish execution.

Joining a process will close the stdin pipe to the process.

Parameters:

returnCodeOut

The return code of the returned process (can be nullptr).

Returns:

On success true is returned.

bool kill()

Terminate a previously created process.

If the process to be destroyed had not finished execution, it will be terminated (i.e killed).

Returns:

On success true is returned.

bool destroy()

Destroy a previously created process.

If the process to be destroyed had not finished execution, it may out live the parent process.

Returns:

On success true is returned.

bool isAlive()

Returns if the subprocess is currently still alive and executing.

Returns:

If the process is still alive true returned.

FILE* getStdIn() const

Get the standard input file for a process.

The file returned can be written to by the parent process to feed data to the standard input of the process.

Returns:

The file for standard input of the process.

FILE* getStdOut() const

Get the standard output file for a process.

The file returned can be read from by the parent process to read data from the standard output of the child process.

Returns:

The file for standard output of the process.

FILE* getStdErr() const

Get the standard error file for a process.

The file returned can be read from by the parent process to read data from the standard error of the child process.

If the process was created with the Option::CombinedStdoutStderr option bit set, this function will return NULL, and the getStdOut function should be used for both the standard output and error combined.

Returns:

The file for standard error of the process.

void startShutdown()

Indicates that the process must start its shutdown

bool isShuttingDown() const

Indicates if the process started its shutdown

bool killed() const

Returns:

True if the process has been manually killed via a kill() call