OsPipeline

Programmer Reference : Native Process Framework (OsProcess) : OsPipeline

OsPipeline

Description

An instance of <OsPipeline> represents a sequenceable collection of vast subprocesses wired together such that the output of one flows into the input of the next. This allows for a 'pipeline' style of concurrency, and the pipeline object is designed to be polymorphic with an <OsVastSubprocess>.

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

Process Enumeration

A pipeline can answer a sequenceable collection of all its processes, as well as providing simple accessors to the first and last in the pipeline. The first process is called the initial process, while the last process is called the terminal process.

For more information, see the method comments from the following methods in <OsPipeline>: #initialProcess, #processes, #terminalProcess

Standard I/O

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

Asking for the inputStream of a pipeline is the same as asking for the inputStream of its initial process, since that
serves as the entry point for input. 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.

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

Lifecycle Status and Notification

A pipeline is considered complete when ALL of its processes are also complete.

A pipeline has an exitCode that is determined by the exitCode of the terminal process. VAST can sign up to be notified when a pipeline exits using VAST's futures framework.

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

Command and Control

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

The pipeline will forward this request to all of its processes. Once all of them are successfully terminated, then the pipeline will answer that isComplete.

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

Class Methods

new

<pre><code> Answer a new initialized instance

 Answers:
    <OsPipeline>

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

Instance Methods

closeStreams

<pre><code> Close all stdio streams from all processes in the pipeline. 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 error stream is a null stream. The inputStream is the inputStream of the first process The outputStream is the outputStream of the last process And errorStream would need to represent the errorStreams of all the processes. Instead, the OsPipelineStarter 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. If the last process has not completed, then answer nil.
Note: This is operating system dependent.

 Answers:
    <Integer>

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

initialProcess

<pre><code> Answer the initial process in the pipeline.

 Answers:
    <OsVastSubprocess>

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

inputStream

<pre><code> Answer the stdin stream of the pipeline (which is the stdin stream of the first process in the pipeline).

 Answers:
    <OsProcessStream>

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

isComplete

<pre><code> Answer true if the receiver process has completed, false otherwise. A pipeline is complete when all of its processes are complete

 Answers:
    <Boolean>

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

kill

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

 Answers:
    <Boolean> true if all processes were successfully terminated, false otherwise

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

onCompletion

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

 Answers:
    <EsFuture>

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

outputStream

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

 Answers:
    <OsProcessStream>

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

pids

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

 Answers
    <KeyedCollection>

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

processes

<pre><code> Answers the collection of <OsVastSubprocess>s

 Answers:
    <SequenceableCollection>

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

terminalProcess

<pre><code> Answer the final process in the pipeline.

 Answers:
    <OsVastSubprocess>

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

terminate

<pre><code> Terminate the process, 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 all processes were successfully terminated, false otherwise

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

uids

<pre><code> Answer a keyed collection describing all the vast unique ids in the pipeline, 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 all processes in the pipeline complete. The calling smalltalk process will block until the pipeline completes

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

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

waitForCompletion:

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

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

Last modified date: 07/07/2022