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