OsPipelineChain
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
Answer a new initialized instance
Answers:
<OsPipelineChain>
Instance Methods
closeStreams
Close all stdio streams from all processes in the pipeline chain.
Ignore any exceptions
Answers:
<OsProcessStream>
commandLine
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>
errorStream
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>
exitCode
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>
initialProcess
Answer the initial process in the pipeline
or nil if not currently known
Answers:
<OsVastSubprocess>
inputStream
Answer the stdin stream of the pipeline chain (which is the stdin stream
of the lhs of the chain).
Answers:
<OsProcessStream>
isComplete
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>
kill
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
lhs
Answer the left-hand side relative to the operator
Answers:
<OsVastSubprocess | OsPipeline | OsPipelineChain>
onCompletion
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>
operator
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
outputStream
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
pids
Answer a keyed collection describing all the process ids
in the pipeline chain, with their associated processes
Answers
<KeyedCollection>
rhs
Answer the right-hand side relative to the operator
Answers:
<OsVastSubprocess | OsPipeline | OsPipelineChain>
terminalProcess
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
terminate
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
uids
Answer a keyed collection describing all the process ids
in the pipeline chain, with their associated processes
Answers
<KeyedCollection>
utf8CommandLine
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>
waitForCompletion
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
waitForCompletion:
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
Last modified date: 02/23/2021