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();

    // methods

    static constexpr Uint32 getDefaultOptions();
    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;
};

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.

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