Qore process Module  1.0.1
Qore::Process::Process Class Reference

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< auto > opts)
 Construct a child from given arguments and launch it. More...
 
 constructor (string command, softlist< softstring > arguments)
 Construct a child from given arguments and launch it. More...
 
 constructor (string command, softlist< softstring > arguments, hash< auto > opts)
 Construct a child from given arguments and launch it. More...
 
 copy ()
 Copy method - instance of this class cannot be copied. More...
 
 destructor ()
 Destroys the object; rethrows any pending exceptions thrown in background threads. 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< MemorySummaryInfogetMemorySummaryInfo ()
 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...
 
*binary readStderrBinary (int bytes, timeout timeout=0)
 Read from child process's standard error output and return a binary value. More...
 
*string readStdout (int bytes, timeout timeout=0)
 Read from child process's standard output. More...
 
*binary readStdoutBinary (int bytes, timeout timeout=0)
 Read from child process's standard output and return a binary value. 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 timeout_ms)
 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< MemorySummaryInfogetMemorySummaryInfo ()
 Returns process information for the current process. More...
 
static hash< MemorySummaryInfogetMemorySummaryInfo (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< auto > 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 or OutputStream object; standard output of the process will be redirected to this objec. In case an OutputStream object is used here, the readStdout() and readStdoutBinary() methods cannot be called, or a PROCESS-STREAM-ERROR exception will be thrown.
  • stderr: an opened Qore File or OutputStream object; standard error output of the process will be redirected to this object. In case an OutputStream object is used here, the readStdout() and readStdoutBinary() methods cannot be called, or a PROCESS-STREAM-ERROR exception will be thrown.
  • on_success: a code/call closure with prototype sub (hash<auto> e). This handler is invoked if launching the process has succeeded.
  • on_setup: a code/call closure with prototype sub (hash<auto> e). This handler is invoked before the process in launched, to setup parameters
  • on_error: a code/call closure with prototype sub (hash<auto> e). This handler is invoked if an error during launch occured.
  • on_fork_error: a code/call closure with prototype sub (hash<auto> e). This handler is invoked if the fork failed. Posix only.
  • on_exec_setup: a code/call closure with prototype sub (hash<auto> e). This handler is invoked if the fork succeeded. Posix only.
  • on_exec_error: a code/call closure with prototype sub (hash<auto> e). This handler is invoked if the exec call errored. Posix only.

Option example:

%new-style
%requires process
sub executor_func(hash<auto> e) {
printf("on_setup: %y\n", e);
}
hash<auto> opts = {
"env": {"FOO": "bar"},
"cwd": "/tmp",
"on_success": sub (hash<auto> e) { # a closure is used
printf("on_success: %y\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: {name: "on_setup", exe: "/opt/local/libexec/gnubin/true", pid: -1, exit: 127, error_code: 0, error_message: "Undefined error: 0", error_category: "system"}
on_success: {name: "on_success", exe: "/opt/local/libexec/gnubin/true", pid: 49313, exit: 127, error_code: 0, error_message: "Undefined error: 0", error_category: "system"}
Note
  • If streams are used to capture process output, the streams will be unassociated with the calling thread and reassociated with the I/O thread used to capture process output. Any exceptions thrown in stream operations in the I/O thread will be rethrown in the calling thread when the process exits, either in the wait() call or in the destructor(). When a thread waits on the process to terminate, any stream objects will be reassigned to the calling thread.
  • This class will attempt to provide complete character output in the output read methods; if the string encoding used is a multibyte encoding (like the default, UTF-8), then any partial characters read at the end of string will be saved in a temporary buffer and prepended to the next read call. If invalid character data is read from stdout or stderr, this can result in output being buffered and not returned. In such cases use a single-character encoding (like ASCII) or use the binary read methods instead. If a stream is used instead, even if the object is a string stream, binary writes are made to the stream and this class makes no effort to return valid multi-byte character data.

Member Function Documentation

◆ checkPid()

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

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

Parameters
pidthe PID of the process
Returns
True if the process is running, False if not
Exceptions
PROCESS-CHECKPID-UNSUPPORTED-ERRORthis 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
idthe 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
commanda 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-ERRORin case of error. Exception desc contains the additional information
PROCESS-SEARCH-PATH-ERRORin case the command is not found in given PATH

◆ constructor() [3/5]

Qore::Process::Process::constructor ( string  command,
hash< auto >  opts 
)

Construct a child from given arguments and launch it.

Parameters
commanda string with program to be run; can be either an absolute path or a simple command to be found in the search path
optsa hash with additional options for the child process Process Options
Exceptions
PROCESS-CONSTRUCTOR-ERRORin case of error. Exception desc contains the additional information
PROCESS-OPTION-ERRORin case invalid option is passed
PROCESS-SEARCH-PATH-ERRORin case the command is not found in given PATH

◆ constructor() [4/5]

Qore::Process::Process::constructor ( string  command,
softlist< softstring >  arguments 
)

Construct a child from given arguments and launch it.

Parameters
commanda string with program to be run; can be either an absolute path or a simple command to be found in the search path
argumentsa list with additiona command arguments
Exceptions
PROCESS-CONSTRUCTOR-ERRORin case of error. Exception desc contains the additional information
PROCESS-SEARCH-PATH-ERRORin case the command is not found in given PATH

◆ constructor() [5/5]

Qore::Process::Process::constructor ( string  command,
softlist< softstring >  arguments,
hash< auto >  opts 
)

Construct a child from given arguments and launch it.

Parameters
commanda string with program to be run; can be either an absolute path or a simple command to be found in the search path
argumentsa list with additiona command arguments
optsa hash with additional options for the child process. See Process Options
Exceptions
PROCESS-CONSTRUCTOR-ERRORin case of error. Exception desc contains the additional information
PROCESS-OPTION-ERRORin case invalid option is passed
PROCESS-SEARCH-PATH-ERRORin 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-ERRORCopying of Process objects is not supported

◆ destructor()

Qore::Process::Process::destructor ( )

Destroys the object; rethrows any pending exceptions thrown in background threads.

Exceptions
anyAny pending exception thrown in background I/O threads will be rethrown in the destructor

◆ detach()

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

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

Exceptions
PROCESS-CHECK-ERRORin 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-ERRORin 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-ERRORan 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<auto> of memory info
Exceptions
PROCESS-GETMEMORYINFO-ERRORan 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-ERRORthis exception is thrown if there is no implementation for this method on the current platform
PROCESS-CHECK-ERRORin 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-ERRORan 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-ERRORthis 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
pidthe PID of the process
Returns
a MemorySummaryInfo hash of memory info
Exceptions
PROCESS-GETMEMORYINFO-ERRORan 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-ERRORthis 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-ERRORin 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
bytesa maximum count of bytes to read
timeouttimeout in milliseconds; if 0 or negative, the method will return immediately if there is no data available
Exceptions
PROCESS-CHECK-ERRORin case child handle was not properly initialized
PROCESS-READ-ERRORin case of read error
PROCESS-STREAM-ERRORin case the stderr option was used with an OutputStream argument in the constructor()
Returns
string with data or NOTHING if no data is available; the length of the returned value can exceed the byte length requested in case of buffered partial multi-byte characters
Note
  • This method will throw a PROCESS-STREAM-ERROR if an OutputStream argument was used in the stderr option in the constructor()
  • This class will attempt to provide complete character output in the output read methods; if the string encoding used is a multibyte encoding (like the default, UTF-8), then any partial characters read at the end of string will be saved in a temporary buffer and prepended to the next read call. If invalid character data is read from stdout or stderr, this can result in output being buffered and not returned. In such cases use a single-character encoding (like ASCII) or use the binary read methods instead.

◆ readStderrBinary()

*binary Qore::Process::Process::readStderrBinary ( int  bytes,
timeout  timeout = 0 
)

Read from child process's standard error output and return a binary value.

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
bytesa maximum count of bytes to read
timeouttimeout in milliseconds; if 0 or negative, the method will return immediately if there is no data available
Exceptions
PROCESS-CHECK-ERRORin case child handle was not properly initialized
PROCESS-READ-ERRORin case of read error
PROCESS-STREAM-ERRORin case the stderr option was used with an OutputStream argument in the constructor()
Returns
a binary value with the raw data read data or NOTHING if no data is available
Note
This method will throw a PROCESS-STREAM-ERROR if an OutputStream argument was used in the stdout option in the constructor()

◆ 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
bytesa maximum count of bytes to read
timeouttimeout in milliseconds; if 0 or negative, the method will return immediately if there is no data available
Exceptions
PROCESS-CHECK-ERRORin case child handle was not properly initialized
PROCESS-READ-ERRORin case of read error
PROCESS-STREAM-ERRORin case the stdout option was used with an OutputStream argument in the constructor()
Returns
string with data or NOTHING if no data is available; the length of the returned value can exceed the byte length requested in case of buffered partial multi-byte characters
Note
  • This method will throw a PROCESS-STREAM-ERROR if an OutputStream argument was used in the stdout option in the constructor()
  • This class will attempt to provide complete character output in the output read methods; if the string encoding used is a multibyte encoding (like the default, UTF-8), then any partial characters read at the end of string will be saved in a temporary buffer and prepended to the next read call. If invalid character data is read from stdout or stderr, this can result in output being buffered and not returned. In such cases use a single-character encoding (like ASCII) or use the binary read methods instead.

◆ readStdoutBinary()

*binary Qore::Process::Process::readStdoutBinary ( int  bytes,
timeout  timeout = 0 
)

Read from child process's standard output and return a binary value.

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
bytesa maximum count of bytes to read
timeouttimeout in milliseconds; if 0 or negative, the method will return immediately if there is no data available
Exceptions
PROCESS-CHECK-ERRORin case child handle was not properly initialized
PROCESS-READ-ERRORin case of read error
PROCESS-STREAM-ERRORin case the stdout option was used with an OutputStream argument in the constructor()
Returns
a binary value with the raw data read data or NOTHING if no data is available
Note
This method will throw a PROCESS-STREAM-ERROR if an OutputStream argument was used in the stdout option in the constructor()

◆ running()

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

Check if the child process is running.

Returns
True if the child is running
Exceptions
PROCESS-CHECK-ERRORin 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
commandcommand name
Returns
string with full path of the command
Exceptions
PROCESS-SEARCH-PATH-ERRORin case the command is not found in given PATH

◆ searchPath() [2/2]

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

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

Parameters
commandcommand name
optsa hash with process options. Process Options - path is important here
Returns
string with full path of the command
Exceptions
PROCESS-SEARCH-PATH-ERRORin 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-ERRORin 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
pidPID of the process to terminate
Exceptions
PROCESS-TERMINATE-ERRORinsufficient permissions to terminate process
PROCESS-INVALID-PIDinvalid PID
PROCESS-TERMINATE-UNSUPPORTED-ERRORthis 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-ERRORin case child handle was not properly initialized

◆ wait() [1/2]

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

Wait for the child process to exit.

Example:
Process p("sleep", 3);
p.wait(); # a blocking/wait call
printf("Sleep finished with code: %d\n", p.exitCode());
Returns
always returns True to keep compatibility with wait(timeout) version
Exceptions
PROCESS-CHECK-ERRORin case child handle was not properly initialized
Note
Any exceptions thrown in the background I/O thread (if a stream was used) are rethrown here

◆ wait() [2/2]

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

Wait for the child process to exit.

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());
Parameters
timeout_msa timeout to wait
Returns
True if child exited while waiting, False in case of timeout
Exceptions
PROCESS-CHECK-ERRORin case child handle was not properly initialized
Note
Any exceptions thrown in the background I/O thread (if a stream was used) are rethrown here if the process terminates in the timeout period

◆ waitForTermination()

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

wait until a given PID terminates

Parameters
pidPID of the process to wait for
Exceptions
PROCESS-WAITFORTERMINATION-UNSUPPORTED-ERRORthis 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
sa string data to be writen
Exceptions
PROCESS-CHECK-ERRORin case child handle was not properly initialized

◆ write() [2/5]

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

Write into child's stdin.

Parameters
ba binary data to be writen
Exceptions
PROCESS-CHECK-ERRORin case child handle was not properly initialized

◆ write() [3/5]

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

Write into child's stdin.

Parameters
ian integer to be writen
Exceptions
PROCESS-CHECK-ERRORin case child handle was not properly initialized

◆ write() [4/5]

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

Write into child's stdin.

Parameters
fa float to be writen
Exceptions
PROCESS-CHECK-ERRORin case child handle was not properly initialized

◆ write() [5/5]

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

Write into child's stdin.

Parameters
na number to be writen
Exceptions
PROCESS-CHECK-ERRORin case child handle was not properly initialized

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