OsPipelineChain

Programmer Reference : Native Process Framework (OsProcess) : OsPipelineChain

OsPipelineChain

Description

An instance of <OsPipelineChain> is a collection of processes and pipelines that have been wired together with logic gates to create conditional flows. These are used if the user wants to control which future path of processes/pipelines should be executed based on an output condition from a previous process/pipeline.

A pipeline chain has a left-hand side (lhs) whose output exit code will be evaluated by a conditional operator or user-defined block. Depending on the conditional evaluation, the right-hand side (rhs) may or may not be evaluated. This means the terminal process is only known after conditional evaluation has occurred.

The exit code of the pipeline chain is the exit code of the (conditional) terminal process.

A user should use an <OsPipelineChainStarter> to construct an instance of an <OsPipelineChain>. @see the class comments of <OsPipelineChainStarter> for more information on how to do this.

Components

As mentioned, the pipeline chain is composed of the left-hand side, an operator and a right-hand side.

For more information, see the method comments from the following methods in <OsPipelineChain>: #lhs, #operator, #rhs

Processes

The user can get the left-hand side and right-hand side of the pipeline chain. Each of those may be a process, pipeline or pipeline chain.

The initial process is the very first process in the pipeline chain that will execute. The terminal process the last process in the chain to execute. Given that the chain operator may make this conditional, the terminal process
may not be available until the chain completes.

For more information, see the method comments from the following methods in <OsPipelineChain>: #initialProcess, #pids, #terminalProcess, #uids

Standard I/O

A pipeline chain can answer its stdin, stdout and stderr streams. A pipeline chain is an abstract concept relating to how real processes are conditionally linked together, but we can still map these standard I/O concepts in a way that makes sense.

Asking for the inputStream of a pipeline chain is the same as asking for the inputStream of its initial process. As mentioned, the initial process is the initial process of the chain's left-hand side (lhs). Asking for the output or error stream of a pipeline is the same as asking for the output or error stream of its terminal process. As mentioned, the terminal process can be conditionally evaluated, so these streams may not be available until the chain has completed execution.

For more information, see the method comments from the following methods in <OsPipelineChain>: #closeStreams, #errorStream, #inputStream, #outputStream

Lifecycle Status and Notification

A pipeline chain is considered complete when its terminal has been set and is complete.

A pipeline chain has an exitCode that is determined by the exitCode of the terminal process.

VAST can sign up to be notified when a pipeline chain exits using VAST's futures framework.

For more information, see the method comments from the following methods in <OsPipelineChain>: #exitCode, #isComplete, #onCompletion, #waitForCompletion, #waitForCompletion:

Command and Control

A pipeline chain can be terminated by sending either terminate (for graceful termination) or kill (for hard termination).

The pipeline chain will forward this request to the lhs and rhs. Once they have successfully terminated, then the pipeline chain will answer that isComplete.

For more information, see the method comments from the following methods in <OsPipelineChain>: #kill, #terminate

Class Methods

new

<pre><code> Answer a new initialized instance

 Answers:
    <OsPipelineChain>

</code></pre> </details>

Instance Methods

closeStreams

<pre><code> Close all stdio streams from all processes in the pipeline chain. Ignore any exceptions

 Answers:
    <OsProcessStream>

</code></pre> </details>

commandLine

<pre><code> Answer the resolved and quoted command line that will passed on to the native process start logic.

 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>

</code></pre> </details>

errorStream

<pre><code> A pipeline chain error stream is a null stream. The inputStream is the inputStream of the lhs The outputStream is the outputStream of the terminal And errorStream would need to represent the errorStreams of 1 or more of the processes Instead, the OsPipelineChainStarter can be configured to append all error out to a file (redirectErrorToFile:), or error can be merged with the output (#redirectErrorToOutput).

 Answers:
    <OsNullReadPipeStream>

</code></pre> </details>

exitCode

<pre><code> Answer an integer representing the exitCode of the last process in the pipeline chain. Depending on the chain operator, the last process may not be statically known. If the last process has not completed (or is not known), then answer nil.
Note: This is operating system dependent.

 Answers:
    <Integer>

</code></pre> </details>

initialProcess

<pre><code> Answer the initial process in the pipeline or nil if not currently known

 Answers:
    <OsVastSubprocess>

</code></pre> </details>

inputStream

<pre><code> Answer the stdin stream of the pipeline chain (which is the stdin stream of the lhs of the chain).

 Answers:
    <OsProcessStream>

</code></pre> </details>

isComplete

<pre><code> Answer true if the terminal (if one is set yet) has completed, false otherwise. A pipeline chain is complete when its terminal is complete.

 Answers:
    <Boolean>

</code></pre> </details>

kill

<pre><code> Kill the pipeline chain 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 OsPipelineChain>>terminate: for further details

 Answers:
    <Boolean> true if lhs and rhs were terminated successfully, false otherwise

</code></pre> </details>

lhs

<pre><code> Answer the left-hand side relative to the operator

 Answers:
    <OsVastSubprocess | OsPipeline | OsPipelineChain>

</code></pre> </details>

onCompletion

<pre><code> Answer a future that represents the eventual completion of this pipeline chain, as well as retrieving the result. A pipeline chain is considered complete when its terminal is complete

 Answers:
    <EsFuture>

</code></pre> </details>

operator

<pre><code> Answer the chaining operator to apply to the left and right-hand side.

 OsPorcessConstants::PipelineChainingAndOp
    Execute the rhs only if the lhs exits successfully.
    @see shouldEvalRhsBlock for definition of success

OsProcessConstants::PipelineChainingOrOp
    Execute the rhs only if the lhs exits unsuccessfully.
    @see shouldEvalRhsBlock for definition of success

OsProcessConstants::PipelineChainingSeqOp
    Execute the lhs.  Once the lhs completes, then
    execute the rhs

 Answers:
    <Symbol> one of the symbols above

</code></pre> </details>

outputStream

<pre><code> Answer the stdout stream of the pipeline chain (which is the stdout stream of the terminal in the pipeline chain).

 Answers:
    <OsProcessStream>stream of the terminal process
    <UndefinedObject> if the terminal process in not known yet

</code></pre> </details>

pids

<pre><code> Answer a keyed collection describing all the process ids in the pipeline chain, with their associated processes

 Answers
    <KeyedCollection>

</code></pre> </details>

rhs

<pre><code> Answer the right-hand side relative to the operator

 Answers:
    <OsVastSubprocess | OsPipeline | OsPipelineChain>

</code></pre> </details>

terminalProcess

<pre><code> Answer the final process in the pipeline child or nil if it is not currently known (due to the conditional operator)

 Answers:
    <OsVastSubprocess | OsPipeline | OsPipelineChain>
    <UndefinedObject> if not available yet

</code></pre> </details>

terminate

<pre><code> Terminate the pipeline chain, gracefully if the OS supports it. @see OsPipeline>>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 lhs and rhs were terminated successfully, false otherwise

</code></pre> </details>

uids

<pre><code> Answer a keyed collection describing all the process ids in the pipeline chain, with their associated processes

 Answers
    <KeyedCollection>

</code></pre> </details>

utf8CommandLine

<pre><code> Answer the resolved and quoted command line that will passed on to the native process start logic.

 This is expressed in UTF-8, which is the native internal
 representation that is used for the subprocess module.

 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>

</code></pre> </details>

waitForCompletion

<pre><code> Wait until the pipeline chain is complete. The calling smalltalk process will block until the pipeline chain completes

 Answers:
    <Integer> - exit code of the terminal in the pipeline

</code></pre> </details>

waitForCompletion:

<pre><code> Wait until the terminal in the pipeline completes and answer the exit code of the terminal process. The calling smalltalk process will block until the chain completes or the wait duration (@aDurationOrMs) elapses. Answers the <Integer> exit code if the pipeline chain 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 of the terminal process in the pipeline
    <UndefinedObject> - nil if the duration elapsed before the pipeline exited

</code></pre> </details>

Last modified date: 07/07/2022