Qore process Module
1.0.1
|
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< 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... | |
*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< 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< 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... | |
System process wrapper.
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:
The opts
hash can hold following keys. All keys are optional.
env:
replace current process's ENV with a hash of env variables. Usecwd:
a string with initial "current working directory", a dir which child should take as its initial work dirpath:
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 parameterson_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:
output of the script will be:
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.
|
static |
Returns True if the process is running, False if not.
pid | the PID of the process |
PROCESS-CHECKPID-UNSUPPORTED-ERROR | this exception is thrown if there is no implementation for this method on the current platform |
PROCESS-CHECKPID-UNSUPPORTED-ERROR
exception is thrownQore::Process::Process::constructor | ( | int | pid | ) |
Construct the child from a PID.
id | the PID of the process. |
Qore::Process::Process::constructor | ( | string | command | ) |
Construct a child from given arguments and launch it.
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 |
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 |
Qore::Process::Process::constructor | ( | string | command, |
hash< auto > | opts | ||
) |
Construct a child from given arguments and launch it.
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 |
PROCESS-CONSTRUCTOR-ERROR | in case of error. Exception desc contains the additional information |
PROCESS-OPTION-ERROR | in case invalid option is passed |
PROCESS-SEARCH-PATH-ERROR | in case the command is not found in given PATH |
Qore::Process::Process::constructor | ( | string | command, |
softlist< softstring > | arguments | ||
) |
Construct a child from given arguments and launch it.
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 |
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 |
Qore::Process::Process::constructor | ( | string | command, |
softlist< softstring > | arguments, | ||
hash< auto > | opts | ||
) |
Construct a child from given arguments and launch it.
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 |
PROCESS-CONSTRUCTOR-ERROR | in case of error. Exception desc contains the additional information |
PROCESS-OPTION-ERROR | in case invalid option is passed |
PROCESS-SEARCH-PATH-ERROR | in case the command is not found in given PATH |
Qore::Process::Process::copy | ( | ) |
Copy method - instance of this class cannot be copied.
PROCESS-COPY-ERROR | Copying of Process objects is not supported |
Qore::Process::Process::destructor | ( | ) |
Destroys the object; rethrows any pending exceptions thrown in background threads.
any | Any pending exception thrown in background I/O threads will be rethrown in the destructor |
nothing Qore::Process::Process::detach | ( | ) |
Detach the child, i.e. let it run after this handle dies.
PROCESS-CHECK-ERROR | in case child handle was not properly initialized |
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.
PROCESS-CHECK-ERROR | in case child handle was not properly initialized |
|
static |
returns a list of three CPU load average values, giving the load average in the last 1, 5, and 15 minutes
PROCESS-GETLOADAVG-ERROR | an error occurred calling getloadavg() |
hash<MemorySummaryInfo> Qore::Process::Process::getMemorySummaryInfo | ( | ) |
Returns process information for the process managed by the current object.
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 |
PROCESS-GETMEMORYINFO-UNSUPPORTED-ERROR
exception is thrown"com.apple.system-task-ports"
entitlement
|
static |
Returns process information for the current process.
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-GETMEMORYINFO-UNSUPPORTED-ERROR
exception is thrown"com.apple.system-task-ports"
entitlement
|
static |
Returns process information for the given PID.
pid | the PID of the process |
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-GETMEMORYINFO-UNSUPPORTED-ERROR
exception is thrown"com.apple.system-task-ports"
entitlementint Qore::Process::Process::id | ( | ) |
Get the Process Identifier.
PROCESS-CHECK-ERROR | in case child handle was not properly initialized |
*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.
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 |
PROCESS-CHECK-ERROR | in case child handle was not properly initialized |
PROCESS-READ-ERROR | in case of read error |
PROCESS-STREAM-ERROR | in case the stderr option was used with an OutputStream argument in the constructor() |
PROCESS-STREAM-ERROR
if an OutputStream
argument was used in the stderr option in the constructor()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. *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.
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 |
PROCESS-CHECK-ERROR | in case child handle was not properly initialized |
PROCESS-READ-ERROR | in case of read error |
PROCESS-STREAM-ERROR | in case the stderr option was used with an OutputStream argument in the constructor() |
PROCESS-STREAM-ERROR
if an OutputStream
argument was used in the stdout option in the constructor() *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.
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 |
PROCESS-CHECK-ERROR | in case child handle was not properly initialized |
PROCESS-READ-ERROR | in case of read error |
PROCESS-STREAM-ERROR | in case the stdout option was used with an OutputStream argument in the constructor() |
PROCESS-STREAM-ERROR
if an OutputStream
argument was used in the stdout option in the constructor()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. *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.
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 |
PROCESS-CHECK-ERROR | in case child handle was not properly initialized |
PROCESS-READ-ERROR | in case of read error |
PROCESS-STREAM-ERROR | in case the stdout option was used with an OutputStream argument in the constructor() |
PROCESS-STREAM-ERROR
if an OutputStream
argument was used in the stdout option in the constructor() bool Qore::Process::Process::running | ( | ) |
Check if the child process is running.
True
if the child is runningPROCESS-CHECK-ERROR | in case child handle was not properly initialized |
|
static |
Search for full path of command in current process's PATH.
command | command name |
command
PROCESS-SEARCH-PATH-ERROR | in case the command is not found in given PATH |
|
static |
Search for full path of command in current process's PATH.
command | command name |
opts | a hash with process options. Process Options - path is important here |
command
PROCESS-SEARCH-PATH-ERROR | in case the command is not found in given PATH |
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.
PROCESS-CHECK-ERROR | in case child handle was not properly initialized |
|
static |
terminate a process unconditionally given its PID
pid | PID of the process to terminate |
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 |
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.
True
in case of valid child handlePROCESS-CHECK-ERROR | in case child handle was not properly initialized |
bool Qore::Process::Process::wait | ( | ) |
Wait for the child process to exit.
True
to keep compatibility with wait(timeout) versionPROCESS-CHECK-ERROR | in case child handle was not properly initialized |
bool Qore::Process::Process::wait | ( | timeout | timeout_ms | ) |
Wait for the child process to exit.
timeout_ms | a timeout to wait |
True
if child exited while waiting, False
in case of timeoutPROCESS-CHECK-ERROR | in case child handle was not properly initialized |
|
static |
wait until a given PID terminates
pid | PID of the process to wait for |
PROCESS-WAITFORTERMINATION-UNSUPPORTED-ERROR | this exception is thrown if there is no implementation for this method on the current platform |
nothing Qore::Process::Process::write | ( | binary | b | ) |
Write into child's stdin
.
b | a binary data to be writen |
PROCESS-CHECK-ERROR | in case child handle was not properly initialized |
nothing Qore::Process::Process::write | ( | float | f | ) |
Write into child's stdin
.
f | a float to be writen |
PROCESS-CHECK-ERROR | in case child handle was not properly initialized |
nothing Qore::Process::Process::write | ( | int | i | ) |
Write into child's stdin
.
i | an integer to be writen |
PROCESS-CHECK-ERROR | in case child handle was not properly initialized |
nothing Qore::Process::Process::write | ( | number | n | ) |
Write into child's stdin
.
n | a number to be writen |
PROCESS-CHECK-ERROR | in case child handle was not properly initialized |
nothing Qore::Process::Process::write | ( | string | s | ) |
Write into child's stdin
.
s | a string data to be writen |
PROCESS-CHECK-ERROR | in case child handle was not properly initialized |