OsNativeProcess
Description
Instances of <OsNativeProcess> are cross-platform handles to operating system processes.
An <OsNativeProcess> provides a unified cross-platform interface for working with and querying external operating system processes.
Process Information
All native processes can be asked for an #info object that gives #current detailed information about a native
process. Some of this information is static, such as OsProcessInfo>>commandLine. Other information is dynamic, such as OsProcessInfo>>totalCpuDuration.
Some #info objects will offer more detailed information than others, depending on the permissions of the user running the VAST process. For more information, @see the method comment in OsNativeProcess>>info as well as the class comments for <OsProcessInfo>.
If an <OsNativeProcess> object is referring to an operating system process that has terminated, then the process info will be inaccessible. This can be tested with OsProcessInfo>>isAccessible.
The following are some examples to get process information.
Get the info of the current VAST process: OsProcesses current info
Get the command line of the current VAST process: OsProcesses current commandLine
Get the process identifier of the current VAST process: OsProcesses current pid
Get the unique identifier of the current VAST process: OsProcesses current uid
Native Process Relationships
All native processes can also reflect on their relationship with other native processes.
For more information, see the method comments from the following methods in <OsNativeProcess>: #allChildren, #allParents, #children, #parent.
The following is a query that selects all running processes on the system that have child processes.
OsProcesses all select: [:process | process children notEmpty]
Lifecycle Status and Notification
The lifecycle of a native process is separate from that of VAST.
Methods exist in <OsNativeProcess> to allow VAST to query the completion status of a native process. VAST can also sign up to be notified when a native process exits using VAST's futures framework.
For more information, see the method comments from the following methods in <OsNativeProcess>: #exitCode, #isComplete, #onCompletion, #waitForCompletion, #waitForCompletion:
Check if a native process is complete:
OsProcesses current isComplete
Subscribe for completion of a native process:
(OsProcessStarter startShell: 'echo "love smalltalk"') onCompletion then: [:p | Transcript show: 'Completed!'].
Get the exit code:
(OsProcessStarter startShell: 'echo "love smalltalk"') waitForCompletion; exitCode
Command and Control
Depending on the permissions of the user that started VAST, a native process object can be requested to kill or
terminate. On Windows, kill and terminate are aliases of one another. On Unix, a kill will be a more forceful signal than a more graceful terminate.
For more information, see the method comments from the following methods in <OsNativeProcess>: #kill, #terminate
Kill/Terminate a native process:
(OsProcessStarter startShell: 'echo "love smalltalk"') kill
@see the native process's IPC-API categorized methods for more information.
Class Methods
<details> addInfoExtensionBlock:
<pre><code> Set a 0, 1 or 2 argument block that runs when the
#info method is called on an OsNativeProcess instance.
This provides users the ability to further customize the process
information being collected up.
Examples:
addInfoExtensionBlock: [Logger log: '#info was called'].
addInfoExtensionBlock: [:info | info at: ##argumentCount put: (info arguments ifNil: [0] ifNotNil: [:args | args size])]
addInfoExtensionBlock: [:info :process | info at: ##virtualMemInUse put: (self getVirtualMemInUse: process pid)]
Arguments:
aBlock - <Block> 0-Argument
1-Argument <OsProcessInfo> info
2-Argument <OsProcessInfo> info <OsNativeProcess> process
</code></pre> </details>
<details> all
<pre><code> Answer all native processes running in the system at the time of this call. This will be a pid sorted array that will contain a mixture OsNativeProcess and subclasse:
OsVastProcess: This vast process
OsVastSubprocess: Current spawned child processes of vast
OsNativeProcesses: All other processes that are not a vast process or subprocess
Answers:
<Array> of <OsNativeProcess> sorted by pids
</code></pre> </details>
<details> removeInfoExtensionBlock:
<pre><code> Remove the info extension block. Answer true if it was removed, false otherwise
Arguments:
aBlock - <Block> info extension block
Answes:
<Boolean>
</code></pre> </details>
Instance Methods
<details> =
<pre><code> Answer true if the native processes are equal, false otherwise.
Equality is based on three attributes of a process, the native
process class, the pid and process creation time. The pid and
creation time are needed to establish equality since operating
systems will recycle pids meaning we could be comparing 2
different processes that share the same pid.
Answers:
<Boolean>
</code></pre> </details>
<details> allChildren
<pre><code> Answers an array of native processes, sorted by pid, that are the children, and decendents of children recursivley, of this process. If this process has no children, an empty array is answered Based on the state of this process, which can change at any time (i.e. process died), it may not be possible to get all the children. In this case, an empty array is answered.
Answers:
<Array> of <OsNativeProcess>
</code></pre> </details>
<details> allParents
<pre><code> Answers all the parent processes of this native process, if accessible. Based on the state of the native process, which can change at any time (i.e. process died), it may not be possible to get the parents. The first element of the resulting array will be parent of this process. The next element will be the parent of the first element...and so on until the most accessible root parent is reached which is the last element
Answers:
<Array> of <OsNativeProcess>
</code></pre> </details>
<details> children
<pre><code> Answers an array of native processes, sorted by pid, that are the direct children of this process. If this process has no children, an empty array is answered. Based on the state of this process, which can change at any time (i.e. process died), it may not be possible to get the children. In this case, an empty array is answered.
Answers:
<Array> of <OsNativeProcess>
</code></pre> </details>
<details> commandLine
<pre><code> Answer the command line of the native process. If not accessible (i.e. permissions), then answer nil
By default, this is expressed in the current code page
A primitive failure will occur if the name is not
a byte object
A primitive failure will occur if the args is not
nil or an Array
Answers:
<String> or nil
</code></pre> </details>
<details> exitCode
<pre><code> Answer an integer representing the receiver's exitCode, if the process has not completed answer nil.
Note: This is operating system dependent.
Answers:
<Integer>
</code></pre> </details>
<details> info
<pre><code> Answers information about the process at the time this call was made. Included in this are customized user actions which may be used to decorate the info.
@see OsNativeProcess class>>addInfoExtensionBlock:
for more information on how to add customized info
Note: The strings from the info are converted from UTF-8
to the current code page. If you want UTF-8, call #utf8Info
instead
Answers:
<OsProcessInfo>
Raises:
<OsProcessException>
</code></pre> </details>
<details> isComplete
<pre><code> Answer true if the receiver process has completed, false otherwise
Answers:
<Boolean>
</code></pre> </details>
<details> isNativeProcess
<pre><code> Object check
Answers:
<Boolean> true
</code></pre> </details>
<details> kill
<pre><code> Kill the process immediatley, bypassing any graceful shutdown that may be offerred by the OS.
This semantics of 'kill' vs 'terminate' are OS dependent.
Windows - terminate and kill are equivalent
Unix - SIGKILL is used here. (SIGTERM for terminate)
@see OsNativeProcess>>terminate: for further details
Answers:
<Boolean> true if terminated, false otherwise
</code></pre> </details>
<details> onCompletion
<pre><code> Answer a future that represents the eventual completion of this process
Answers:
<EsFuture>
</code></pre> </details>
<details> parent
<pre><code> Answers the parent of this native process, if accessible. Based on the state of the native process, which can change at any time (i.e. process died), it may not be possible to get the parent. In this case, nil is answered
Answers:
<OsNativeProcess> or nil
</code></pre> </details>
<details> pid
<pre><code> Answer the native process identifier assigned by the operating system
Answers:
<Integer>
</code></pre> </details>
<details> terminate
<pre><code> Terminate the process, gracefully if the OS supports it. @see OsNativeProcess>>terminate: for further details
This semantics of 'kill' vs 'terminate' are OS dependent.
Windows - terminate and kill are equivalent
Unix - SIGTERM is used here. (SIGKILL for kill)
Answers:
<Boolean> true if terminated, false otherwise
</code></pre> </details>
<details> uid
<pre><code> Answer the unique identifier assigned by VAST. This id will be unique for the duration of the VAST instance
Answers:
<Integer>
</code></pre> </details>
<details> utf8CommandLine
<pre><code> Answer the command line of the process. If not accessible (i.e. permissions), then answer nil
Answers:
<String> or nil
</code></pre> </details>
<details> utf8Info
<pre><code> Answers information about the process at the time this call was made. Included in this are customized user actions which may be used to decorate the info.
@see OsNativeProcess class>>addInfoExtensionBlock:
for more information on how to add customized info
Note: The strings from the info are UTF-8
If you want string in the current code page,
then call #info instead
Answers:
<OsProcessInfo>
Raises:
<OsProcessException>
</code></pre> </details>
<details> waitForCompletion
<pre><code> Convenience Method: From a completion future, request to wait for the process to complete and answer the exit code. The calling smalltalk process will block until the process completes
Answers:
<Integer> - exit code
</code></pre> </details>
<details> waitForCompletion:
<pre><code> Convenience Method: From a completion future, request to wait for the process to complete and answer the exit code. The calling smalltalk process will block until the process completes or the wait duration (@aDurationOrMs) elapses. Answers the <Integer> exit code if the process completes before the elapsed time. Otherwise, answer nil if the duration time elapses
Arguments:
aDurationOrMs - <Duration>duration object
<Integer> duration in milliseconds
Answers:
<Integer> - exit code
<UndefinedObject> - nil if the duration elapsed before the process exited
</code></pre> </details>