AProcess#

Retrieves information about processes.

Header:	`#include <AUI/Platform/AProcess.h>`
CMake:	`aui_link(my_target PUBLIC aui::core)`

Detailed Description#

Process model that facilitates process creation, management, and interaction with other processes.

In a sandboxed environment (especially in iOS and Android) this functionality is mostly irrelevant (except AProcess::self()).

The AProcess class is typically used for creating, controlling, and monitoring subprocesses (including self) in a platform-independent manner. It provides a way to run external applications from within the application itself, which can be useful for tasks like running scripts, launching other programs, or automating system operations through commands.

compilation breaks on older msvc

Launching executable#

To start a process, pass the name of application you want to run and optionally provide arguments and working dir for that application. In this code snippet, we are starting another instance of the current executable with specific arguments and capturing its standard output (stdOut).

auto self = AProcess::self()->getPathToExecutable();
AProcess::ArgStringList args;
args.list << "--help";
args.list << "-a";
auto p = AProcess::create({
  .executable = self,
  .args = std::move(args),
  .workDir = self.parent(),
});

AString accumulator;
AObject::connect(p->stdOut, p, [&](const AByteBuffer& buffer) { accumulator += AString::fromUtf8(buffer); });

p->run();

EXPECT_EQ(p->waitForExitCode(), 0);
EXPECT_TRUE(accumulator.contains("This program contains tests written using Google Test.")) << accumulator;

We define an empty string accumulator to collect the output from the process. Then, we connect a lambda function to the stdOut signal of the process. This lambda function converts the received buffer (a byte array) to a UTF-8 string and appends it to accumulator.

We start the new process by calling its AProcess::run() method, which will execute the specified application with the provided arguments in the given working directory.

We wait for the process to finish by calling waitForExitCode(), which blocks until the process exits and returns its exit code. If the exit code is 0, it means the process completed successfully.

Public Types#

ArgSingleString#

struct AProcess::ArgSingleString

Process arguments represented as a single string. In general, prefer using AProcess::Args.

Field	Description
`AString arg`

ArgStringList#

struct AProcess::ArgStringList

Process arguments represented as array of strings.

Field Description

AStringVector list Argument list.

bool win32WrapWhitespaceArgumentsWithQuots {windows} Takes action only on Windows platform. If true, during conversion to a single command line string on Windows platforms elements of list containing whitespaces are wrapped with quots escaping existing quots. As it's the only way on Windows platforms to supply paths with whitespaces, executables generally handle these quots properly. If it does not work for your particular case, you may try setting this to false or use AProcess::ArgSingleString to take full control of command line during process creation. Defaults to true.

ProcessCreationInfo#

struct AProcess::ProcessCreationInfo

Process creation info.

Field	Description
`APath executable`	Target executable file. Mandatory.
`std::variant<ArgSingleString,ArgStringList> args`	Child process arguments. In common, prefer Args variant. Unix native APIs use arguments as array of strings. If ArgSingleString variant is chosen, AUI splits it with whitespaces. {windows} Windows native APIs use arguments as a single string. If ArgStringList variant is chosen, AUI converts array of strings to a single command line string value. See ArgStringList for details of this conversion.
`APath workDir`	Process working directory. Defaults to working directory of the calling process.

Public Methods#

all#

static AVector<_<AProcess>> AProcess::all()

Returns: data about all other running processes.

create#

static _<AChildProcess> AProcess::create(ProcessCreationInfo args)

Launches an executable.

Arguments: args
designated-initializer-style args. See ProcessCreationInfo
Returns: AChildProcess instance. Use AChildProcess::run to execute.

executeAsAdministrator#

static void AProcess::executeAsAdministrator(const AString& applicationFile, const AString& args = { }, const APath& workingDirectory = { })

Launches executable with administrator rights. (Windows only)

Arguments: applicationFile
executable file

args
arguments

workingDirectory
pro

This function could not determine exit code because of MS Windows restrictions

executeWaitForExit#

static int AProcess::executeWaitForExit(AString applicationFile, AString args = { }, APath workingDirectory = { }, ASubProcessExecutionFlags flags = ASubProcessExecutionFlags::DEFAULT)

Launches executable.

Arguments: applicationFile
executable file.

args
arguments.

workingDirectory
working directory.

flags
process execution flags. see ASubProcessExecutionFlags.
Returns: exit code

findAnotherSelfInstance#

static _<AProcess> AProcess::findAnotherSelfInstance(const AString& yourProjectName)

tempFileName file name which will be used as lock

Returns: another instance of this application; nullptr, if not found

fromPid#

static _<AProcess> AProcess::fromPid(uint32_t pid)

Returns: process by id

This function might cause race condition if process is about to die. If process is not found, nullptr is returned so you must check for nullptr before proceeding. However, if non-nullptr is returned, the process handle is "acquired" and guaranteed to be valid during lifetime of AProcess instance.

getModuleName#

virtual APath AProcess::getModuleName()

Returns: process' executable file name.

getPathToExecutable#

virtual APath AProcess::getPathToExecutable()

Returns: path to the process' executable.

getPid#

virtual uint32_t AProcess::getPid()

Returns: process' ID.

make#

static _<AChildProcess> AProcess::make(AString applicationFile, AString args = { }, APath workingDirectory = { })

Launches an executable.

Arguments: applicationFile
executable file

args
arguments

workingDirectory
working directory
Returns: AChildProcess instance. Use AChildProcess::run to execute.

Examples#

examples/7guis/flight_booker/src/main.cpp

7GUIs Flight Booker - Flight Booker.

          ass::BackgroundSolid { AColor::RED },
        } });
        setContents(Centered {
          Vertical {
            _new<ADropdownList>(AListModel<AString>::make({ "one-way flight", "return flight" })) AUI_LET {
                    connect(it->selectionId().readProjected([](int selectionId) { return selectionId == 1; }),
                            mIsReturnFlight);
                },
            dateTextField(mDepartureDate),
            dateTextField(mReturnDate) AUI_LET { connect(mIsReturnFlight, AUI_SLOT(it)::setEnabled); },

processMemory#

virtual size_t AProcess::processMemory()

Obtain process memory usage.

self#

static _<AProcess> AProcess::self()

Returns: data about this process.

waitForExitCode#

virtual int AProcess::waitForExitCode()

Wait for process to be finished and returns exit code.

Returns: exit code