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
addInfoExtensionBlock:
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
all
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
removeInfoExtensionBlock:
Remove the info extension block.
Answer true if it was removed, false otherwise
Arguments:
aBlock - <Block> info extension block
Answes:
<Boolean>
Instance Methods
=
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>
allChildren
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>
allParents
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>
children
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>
commandLine
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
exitCode
Answer an integer representing the receiver's exitCode,
if the process has not completed answer nil.
Note: This is operating system dependent.
Answers:
<Integer>
info
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>
isComplete
Answer true if the receiver process has completed, false otherwise
Answers:
<Boolean>
isNativeProcess
Object check
Answers:
<Boolean> true
kill
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
onCompletion
Answer a future that represents the
eventual completion of this process
Answers:
<EsFuture>
parent
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
pid
Answer the native process identifier assigned
by the operating system
Answers:
<Integer>
terminate
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
uid
Answer the unique identifier assigned
by VAST. This id will be unique for the
duration of the VAST instance
Answers:
<Integer>
utf8CommandLine
Answer the command line of the process.
If not accessible (i.e. permissions), then answer nil
Answers:
<String> or nil
utf8Info
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>
waitForCompletion
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
waitForCompletion:
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
Last modified date: 07/07/2022