System process wrapper. More...

Public Member Methods
	constructor (int pid)
	Construct the child from a PID. More...

	constructor (string command)
	Construct a child from given arguments and launch it. More...

	constructor (string command, hash opts)
	Construct a child from given arguments and launch it. More...

	constructor (string command, softlist arguments)
	Construct a child from given arguments and launch it. More...

	constructor (string command, softlist arguments, hash opts)
	Construct a child from given arguments and launch it. More...

	copy ()
	Copy method - instance of this class cannot be copied. More...

nothing	detach ()
	Detach the child, i.e. let it run after this handle dies. More...

int	exitCode ()
	Get the child process's exit code. More...

hash< MemorySummaryInfo >	getMemorySummaryInfo ()
	Returns process information for the process managed by the current object. More...

int	id ()
	Get the Process Identifier. More...

*string	readStderr (int bytes, timeout timeout=0)
	Read from child process's standard error output. More...

*string	readStdout (int bytes, timeout timeout=0)
	Read from child process's standard output. More...

bool	running ()
	Check if the child process is running. More...

nothing	terminate ()
	Terminate the child process. More...

bool	valid ()
	Check if this handle holds a child process. More...

bool	wait ()
	Wait for the child process to exit. More...

bool	wait (timeout t)
	Wait for the child process to exit. More...

nothing	write (string s)
	Write into child's `stdin`. More...

nothing	write (binary b)
	Write into child's `stdin`. More...

nothing	write (int i)
	Write into child's `stdin`. More...

nothing	write (float f)
	Write into child's `stdin`. More...

nothing	write (number n)
	Write into child's `stdin`. More...

Static Public Member Methods
static bool	checkPid (int pid)
	Returns True if the process is running, False if not. More...

static list< float >	getLoadAvg ()
	returns a list of three CPU load average values, giving the load average in the last 1, 5, and 15 minutes More...

static hash< MemorySummaryInfo >	getMemorySummaryInfo ()
	Returns process information for the current process. More...

static hash< MemorySummaryInfo >	getMemorySummaryInfo (int pid)
	Returns process information for the given PID. More...

static *string	searchPath (string command)
	Search for full path of command in current process's PATH. More...

static *string	searchPath (string command, hash opts)
	Search for full path of command in current process's PATH. More...

static nothing	terminate (int pid)
	terminate a process unconditionally given its PID More...

static nothing	waitForTermination (int pid)
	wait until a given PID terminates More...

Detailed Description

System process wrapper.

Restrictions:: Qore::PO_NO_EXTERNAL_PROCESS

A process is an independently executable entity, which is different from a thread, in that it has it's own resources. Those include memory and hardware resources.

Every process is identified by a unique number, called the process identification digit, pid.

A process will return an integer value indicating whether it was successful. On posix there are more codes associated with that, but not so on windows. Therefore there is not such encoding currently in the library. However an exit code of zero means the process was successful, while one different than zero indicates an error.

Processes can also be forced to exit. There are two ways to do this, signal the process to so and wait, and just terminate the process without conditions.

Usually the first approach is to signal an exit request, but windows - unlike posix - does not provide a consistent way to do this. Hence this is not part of the library and only the hard terminate is.

The environment is a map of variables local to every process. The most significant one for this library is the PATH variable, which containes a list of paths, that ought to be searched for executables. A shell will do this automatically, while this library provides a function for that.

The child process will be destroyed immediatelly when an instance of Process class is destroyed, except if detach() is called.

The simplest usage of Process is:

%new-style
%requires process
Process p("ls");
p.wait();

Process Options

The opts hash can hold following keys. All keys are optional.

env : replace current process's ENV with a hash of env variables. Use
ENV + ( "FOO" : "bar")
is you want to merge parent's ENV to child.
cwd : a string with initial "current working directory", a dir which child should take as its initial work dir
path : a list of strings. It's a custom search path to find command in the Process constructors. If it's not given, parent's ENV PATH is used. This value is not passed to child's ENV at all.
stdout : an opened Qore File object. Standard output of the process will be redirected to this file.
stderr : an opened Qore File object. Standard error output of the process will be redirected to this file.
on_success : a code/call closure with prototype sub (hash e). This handler is invoked if launching the process has succeeded.
on_setup : a code/call closure with prototype sub (hash e). This handler is invoked before the process in launched, to setup parameters
on_error : a code/call closure with prototype sub (hash e). This handler is invoked if an error during launch occured.
on_fork_error : a code/call closure with prototype sub (hash e). This handler is invoked if the fork failed. Posix only.
on_exec_setup : a code/call closure with prototype sub (hash e). This handler is invoked if the fork succeeded. Posix only.
on_exec_error : a code/call closure with prototype sub (hash e). This handler is invoked if the exec call errored. Posix only.

Option example:

%new-style
%requires process
sub executor_func(hash e) {
    printf("on_setup: %n\n", e);
}
hash opts = (
    "env" : ( "FOO" : "bar"),
    "cwd" : "/tmp",
    "on_success" : sub (hash e) { # a closure is used
        printf("on_success: %n\n", e);
    },
    "on_setup" : \executor_func(), # a call ref
);
Process p("true", opts);
p.wait();
int ret = p.exitCode();

output of the script will be:

on_setup: hash: (name : "on_setup", exe : "/usr/bin/true", pid : -1, exit : 127, error_code : 0, error_message : "Success", error_category : "system")

on_success: hash: (name : "on_success", exe : "/usr/bin/true", pid : 23014, exit : 127, error_code : 0, error_message : "Success", error_category : "system")

Member Function Documentation

◆ checkPid()

static bool Qore::Process::Process::checkPid ( int pid )

static

Returns True if the process is running, False if not.

Parameters

pid	the PID of the process

Returns: True if the process is running, False if not

Exceptions

PROCESS-CHECKPID-UNSUPPORTED-ERROR this exception is thrown if there is no implementation for this method on the current platform

Note: this method has been implemented for Unix and Unix-like systems only; on all other platforms a PROCESS-CHECKPID-UNSUPPORTED-ERROR exception is thrown

See also

◆ constructor() [1/5]

Qore::Process::Process::constructor ( int pid )

Construct the child from a PID.

Parameters

id	the PID of the process.

Note: The only functionality available when this constructor is used is id(); all other calls will fail

◆ constructor() [2/5]

Qore::Process::Process::constructor ( string command )

Construct a child from given arguments and launch it.

Parameters

command a string with program to be run; can be either an absolute path or a simple command to be found in the search path

Exceptions

PROCESS-CONSTRUCTOR-ERROR	in case of error. Exception `desc` contains the additional information
PROCESS-SEARCH-PATH-ERROR	in case the `command` is not found in given PATH

◆ constructor() [3/5]

Qore::Process::Process::constructor	(	string	command,
		hash	opts
	)

Construct a child from given arguments and launch it.

Parameters

command	a string with program to be run; can be either an absolute path or a simple command to be found in the search path
opts	a hash with additional options for the child process Process Options

Exceptions

PROCESS-CONSTRUCTOR-ERROR	in case of error. Exception `desc` contains the additional information
PROCESS-OPTIONS-ERROR	in case invalid option is passed
PROCESS-SEARCH-PATH-ERROR	in case the `command` is not found in given PATH

◆ constructor() [4/5]

Qore::Process::Process::constructor	(	string	command,
		softlist	arguments
	)

Construct a child from given arguments and launch it.

Parameters

command	a string with program to be run; can be either an absolute path or a simple command to be found in the search path
arguments	a list with additiona `command` arguments

Exceptions

PROCESS-CONSTRUCTOR-ERROR	in case of error. Exception `desc` contains the additional information
PROCESS-SEARCH-PATH-ERROR	in case the `command` is not found in given PATH

◆ constructor() [5/5]

Qore::Process::Process::constructor	(	string	command,
		softlist	arguments,
		hash	opts
	)

Construct a child from given arguments and launch it.

Parameters

command	a string with program to be run; can be either an absolute path or a simple command to be found in the search path
arguments	a list with additiona `command` arguments
opts	a hash with additional options for the child process. See Process Options

Exceptions

PROCESS-CONSTRUCTOR-ERROR	in case of error. Exception `desc` contains the additional information
PROCESS-OPTIONS-ERROR	in case invalid option is passed
PROCESS-SEARCH-PATH-ERROR	in case the `command` is not found in given PATH

◆ copy()

Qore::Process::Process::copy ( )

Copy method - instance of this class cannot be copied.

Exceptions

PROCESS-COPY-ERROR Copying of Process objects is not supported

◆ detach()

nothing Qore::Process::Process::detach ( )

Detach the child, i.e. let it run after this handle dies.

Exceptions

PROCESS-CHECK-ERROR in case child handle was not properly initialized

◆ exitCode()

int Qore::Process::Process::exitCode ( )

Get the child process's exit code.

The return value is without any meaning if the child wasn't waited for or if it was terminated.

Returns: child process's exit code

Exceptions

PROCESS-CHECK-ERROR in case child handle was not properly initialized

◆ getLoadAvg()

static list<float> Qore::Process::Process::getLoadAvg ( )

static

returns a list of three CPU load average values, giving the load average in the last 1, 5, and 15 minutes

Code Flags:: RET_VALUE_ONLY

Example:: list<float> l = Process::getLoadAvg();
printf("load in the last minute was: %y\n", l[0]);

Returns: a list of three CPU load average values, giving the load average in the last 1, 5, and 15 minutes

Exceptions

PROCESS-GETLOADAVG-ERROR an error occurred calling getloadavg()

◆ getMemorySummaryInfo() [1/3]

hash<MemorySummaryInfo> Qore::Process::Process::getMemorySummaryInfo ( )

Returns process information for the process managed by the current object.

Returns: a MemorySummaryInfo hash of memory info

Exceptions

PROCESS-GETMEMORYINFO-ERROR	an error occurred querying the process's memory usage (PID does not exist or no permission to read the process's virtual memory tables)
PROCESS-GETMEMORYINFO-UNSUPPORTED-ERROR	this exception is thrown if there is no implementation for this method on the current platform
PROCESS-CHECK-ERROR	in case child handle was not properly initialized

Note

this method has been implemented for Linux and MacOS only; on all other platforms a PROCESS-GETMEMORYINFO-UNSUPPORTED-ERROR exception is thrown
on MacOS the memory of another process cannot be read unless the calling process has root privileges or the process has the "com.apple.system-task-ports" entitlement

See also: HAVE_PROCESS_GETMEMORYINFO

◆ getMemorySummaryInfo() [2/3]

static hash<MemorySummaryInfo> Qore::Process::Process::getMemorySummaryInfo ( )

static

Returns process information for the current process.

Returns: a MemorySummaryInfo hash of memory info

Exceptions

PROCESS-GETMEMORYINFO-ERROR	an error occurred querying the process's memory usage (PID does not exist or no permission to read the process's virtual memory tables)
PROCESS-GETMEMORYINFO-UNSUPPORTED-ERROR	this exception is thrown if there is no implementation for this method on the current platform

Note

this method has been implemented for Linux and MacOS only; on all other platforms a PROCESS-GETMEMORYINFO-UNSUPPORTED-ERROR exception is thrown
on MacOS the memory of another process cannot be read unless the calling process has root privileges or the process has the "com.apple.system-task-ports" entitlement

See also: HAVE_PROCESS_GETMEMORYINFO

◆ getMemorySummaryInfo() [3/3]

static hash<MemorySummaryInfo> Qore::Process::Process::getMemorySummaryInfo ( int pid )

static

Returns process information for the given PID.

Parameters

pid	the PID of the process

Returns: a MemorySummaryInfo hash of memory info

Exceptions

PROCESS-GETMEMORYINFO-ERROR	an error occurred querying the process's memory usage (PID does not exist or no permission to read the process's virtual memory tables)
PROCESS-GETMEMORYINFO-UNSUPPORTED-ERROR	this exception is thrown if there is no implementation for this method on the current platform

Note

this method has been implemented for Linux and MacOS only; on all other platforms a PROCESS-GETMEMORYINFO-UNSUPPORTED-ERROR exception is thrown
on MacOS the memory of another process cannot be read unless the calling process has root privileges or the process has the "com.apple.system-task-ports" entitlement

See also: HAVE_PROCESS_GETMEMORYINFO

◆ id()

int Qore::Process::Process::id ( )

Get the Process Identifier.

Returns: child process's PID

Exceptions

PROCESS-CHECK-ERROR in case child handle was not properly initialized

◆ readStderr()

*string Qore::Process::Process::readStderr	(	int	bytes,
		timeout	timeout = `0`
	)

Read from child process's standard error output.

Reads data from child process's standard error output. If no timeout is given, or timeout is 0 or negative, the method reads all data that is currently available up to the count passed in bytes parameter and then returns immediately. If no data is available, it will return NOTHING.

If positive timeout value is passed, then the method reads all data that is currently available up to the count passed in bytes parameter and then returns immediately. If no data is available, it will sleep until timeout and then try to read. If there is still no data, it will return.

This method does not guarantee that any data will be read or that bytes count of bytes will be read.

Parameters

bytes	a maximum count of bytes to read
timeout	timeout in milliseconds; if 0 or negative, the method will return immediately if there is no data available

Exceptions

PROCESS-CHECK-ERROR	in case child handle was not properly initialized
PROCESS-READ-ERROR	in case of read error

Returns: string with data or NOTHING if no data is available

◆ readStdout()

*string Qore::Process::Process::readStdout	(	int	bytes,
		timeout	timeout = `0`
	)

Read from child process's standard output.

Reads data from child process's standard output. If no timeout is given, or timeout is 0 or negative, the method reads all data that is currently available up to the count passed in bytes parameter and then returns immediately. If no data is available, it will return NOTHING.

If positive timeout value is passed, then the method reads all data that is currently available up to the count passed in bytes parameter and then returns immediately. If no data is available, it will sleep until timeout and then try to read. If there is still no data, it will return.

This method does not guarantee that any data will be read or that bytes count of bytes will be read.

Parameters

bytes	a maximum count of bytes to read
timeout	timeout in milliseconds; if 0 or negative, the method will return immediately if there is no data available

Exceptions

PROCESS-CHECK-ERROR	in case child handle was not properly initialized
PROCESS-READ-ERROR	in case of read error

Returns: string with data or NOTHING if no data is available

◆ running()

bool Qore::Process::Process::running ( )

Check if the child process is running.

Returns: True if the child is running

Exceptions

PROCESS-CHECK-ERROR in case child handle was not properly initialized

See also: Process::checkPid()

◆ searchPath() [1/2]

static *string Qore::Process::Process::searchPath ( string command )

static

Search for full path of command in current process's PATH.

Parameters

command command name

Returns: string with full path of the command

Exceptions

PROCESS-SEARCH-PATH-ERROR in case the command is not found in given PATH

◆ searchPath() [2/2]

static *string Qore::Process::Process::searchPath	(	string	command,
		hash	opts
	)

static

Search for full path of command in current process's PATH.

Parameters

command	command name
opts	a hash with process options. Process Options - `path` is important here

Returns: string with full path of the command

Exceptions

PROCESS-SEARCH-PATH-ERROR in case the command is not found in given PATH

◆ terminate() [1/2]

nothing Qore::Process::Process::terminate ( )

Terminate the child process.

This function will cause the child process to unconditionally and immediately exit. It is implemented with SIGKILL on posix and TerminateProcess on windows.

Exceptions

PROCESS-CHECK-ERROR in case child handle was not properly initialized

◆ terminate() [2/2]

static nothing Qore::Process::Process::terminate ( int pid )

static

terminate a process unconditionally given its PID

Parameters

pid	PID of the process to terminate

Exceptions

PROCESS-TERMINATE-ERROR	insufficient permissions to terminate process
PROCESS-INVALID-PID	invalid PID
PROCESS-TERMINATE-UNSUPPORTED-ERROR	this exception is thrown if there is no implementation for this method on the current platform

Note: this method will also clean up any child processes if necessary (i.e. on Unix-like platforms) in case the process killed is a child of the current process

See also

◆ valid()

bool Qore::Process::Process::valid ( )

Check if this handle holds a child process.

That does not mean, that the process is still running. It only means, that the handle does or did exist.

Returns: True in case of valid child handle

Exceptions

PROCESS-CHECK-ERROR in case child handle was not properly initialized

◆ wait() [1/2]

bool Qore::Process::Process::wait ( )

Wait for the child process to exit.

Exceptions

PROCESS-CHECK-ERROR in case child handle was not properly initialized

Returns: always returns True to keep compatibility with wait(timeout) version

Example:

Process p("sleep", 3);
p.wait(); # a blocking/wait call
printf("Sleep finished with code: %d\n", p.exitCode());

◆ wait() [2/2]

bool Qore::Process::Process::wait ( timeout t )

Wait for the child process to exit.

Parameters

t	a timeout to wait

Exceptions

PROCESS-CHECK-ERROR in case child handle was not properly initialized

Returns: True if child exited while waiting, False in case of timeout

Example:

Process p("sleep", 3);
while (!p.wait(1)) {
    printf("I'm doing something here...\n");
}
printf("Sleep finished with code: %d\n", p.exitCode());

◆ waitForTermination()

static nothing Qore::Process::Process::waitForTermination ( int pid )

static

wait until a given PID terminates

Parameters

pid	PID of the process to wait for

Exceptions

PROCESS-WAITFORTERMINATION-UNSUPPORTED-ERROR this exception is thrown if there is no implementation for this method on the current platform

See also

◆ write() [1/5]

nothing Qore::Process::Process::write ( string s )

Write into child's stdin.

Parameters

s	a string data to be writen

Exceptions

PROCESS-CHECK-ERROR in case child handle was not properly initialized

◆ write() [2/5]

nothing Qore::Process::Process::write ( binary b )

Write into child's stdin.

Parameters

b	a binary data to be writen

Exceptions

PROCESS-CHECK-ERROR in case child handle was not properly initialized

◆ write() [3/5]

nothing Qore::Process::Process::write ( int i )

Write into child's stdin.

Parameters

i	an integer to be writen

Exceptions

PROCESS-CHECK-ERROR in case child handle was not properly initialized

◆ write() [4/5]

nothing Qore::Process::Process::write ( float f )

Write into child's stdin.

Parameters

f	a float to be writen

Exceptions

PROCESS-CHECK-ERROR in case child handle was not properly initialized

◆ write() [5/5]

nothing Qore::Process::Process::write ( number n )

Write into child's stdin.

Parameters

n	a number to be writen

Exceptions

PROCESS-CHECK-ERROR in case child handle was not properly initialized

The documentation for this class was generated from the following file:

QC_Process.dox.h

Public Member Methods

Static Public Member Methods

Detailed Description

Process Options

Member Function Documentation

◆ checkPid()

◆ constructor() [1/5]

◆ constructor() [2/5]

◆ constructor() [3/5]

◆ constructor() [4/5]

◆ constructor() [5/5]

◆ copy()

◆ detach()

◆ exitCode()

◆ getLoadAvg()

◆ getMemorySummaryInfo() [1/3]

◆ getMemorySummaryInfo() [2/3]

◆ getMemorySummaryInfo() [3/3]

◆ id()

◆ readStderr()

◆ readStdout()

◆ running()

◆ searchPath() [1/2]

◆ searchPath() [2/2]

◆ terminate() [1/2]

◆ terminate() [2/2]

◆ valid()

◆ wait() [1/2]

◆ wait() [2/2]

◆ waitForTermination()

◆ write() [1/5]

◆ write() [2/5]

◆ write() [3/5]

◆ write() [4/5]

◆ write() [5/5]