OsReadPipeStream
Description
A read pipe stream is a pipe stream that reads data off the receiving side of the pipe. This stream is used to read streaming data from processes via os pipes in a blocking or non-blocking fashion.
Auto Fill
All read pipe streams support the concept of 'auto-fill' which is a policy to try and read as much data from the operating system pipes into the buffers. Users should not set that directly in <OsReadPipeStream>, but rather from #autoFill methods or setting the OsProcessStarter>>tuneForDeadlockAvoidance policy.
Blocking API
This stream conforms to the majority of the smalltalk stream apis. Most of these will be considered blocking operations meaning that these methods can block the calling process. @see the methods in category IPC-API (Blocking)
Non-Blocking API
This stream also includes many non-blocking calls that will tend to retrieve that information that is available at the time of the call, but not block waiting for more. @see the methods in category IPC-API (Non-Blocking)
Class Methods
None
Instance Methods
<details> atEnd
<pre><code> NON-BLOCKING Answer true if the pipe is at EOF, false otherwise. Note: The pipe is constantly being filled and drained, so keep in mind that atEnd may answer true in one invocation, and then answer false in a subsequent invocation because the pipe was filled up.
Answers:
<Boolean>
</code></pre> </details>
<details> autoFill
<pre><code> Answer true if this buffer should try and keep itself full during the process lifecycle, false if it fills only indirectly based on a request for more data than is in the buffer.
There are events (i.e. a write is about to be performed to stdin) that will trigger the
buffer to fill up in order to prevent well-known deadlock situations.
Answers:
<Boolean>
</code></pre> </details>
<details> autoFill:
<pre><code> Set a <Boolean> indicating if this buffer should try and keep itself full during the process lifecycle (true), or if it fills only indirectly based on a request for more data than is in the buffer (false).
Arguments:
aBoolean - <Boolean>
</code></pre> </details>
<details> available
<pre><code> NON-BLOCKING Return the number of bytes available to be read. This is the the bufferred data + data in pipe Subclasses determine if this is interpreted as available for reading or writing
Answers:
<Integer> num bytes available in the pipe
</code></pre> </details>
<details> availableInPipe
<pre><code> NON-BLOCKING Return the number of bytes available in the pipe. Subclasses determine if this is interpreted as available for reading or writing
Answers:
<Integer> num bytes available in the pipe
</code></pre> </details>
<details> fill
<pre><code> NON-Blocking: Preemptively attempt to fill the pipe buffer
Answers:
<Integer> number of bytes filled
</code></pre> </details>
<details> isBytes:
<pre><code> If true, adjust the buffers to store bytes. If false, adjust the buffers to store chars. Inform the @stream
Arguments:
aBoolean - <Boolean>
</code></pre> </details>
<details> next
<pre><code> BLOCKING Answer the next element in the pipe. Block until an element becomes available in the pipe. If the other side of the pipe closes, then a nil will be returned meaning End Of Pipe
Answers:
<Integer | Character> next element
Raises:
<ExCLDTIndexOutOfRange>
<OsProcessException>
</code></pre> </details>
<details> next:
<pre><code> BLOCKING Answer a collection containing the next @anInteger elements from the pipe. The caller will block until all @anInteger elements are available or End Of Pipe because the write end of the pipe was closed. If @anInteger < 1, an empty collection is answered
Arguments:
anInteger - <Integer>
Answers:
<ByteArray | String>
Raises:
<OsProcessException>
</code></pre> </details>
<details> next:into:
<pre><code> BLOCKING Insert the next @anInteger elements from the pipe into @aByteCollection starting at 1. The caller will block until all @anInteger elements are available or End Of Pipe because the write end of the pipe was closed. If @anInteger < 1, an empty collection is answered. An exception is raised if < anInteger elements are avaiable in this stream.
Arguments:
anInteger - <Integer>
aByteCollection - <ByteArray | String>
Answers:
<ByteArray | String> aByteCollection
Raises:
<OsProcessException>
</code></pre> </details>
<details> next:into:startingAt:
<pre><code> BLOCKING Insert the next @anInteger elements from the pipe into @aByteCollection starting at the 1-based @initialPosition The caller will block until all @anInteger elements are available or End Of Pipe because the write end of the pipe was closed. If @anInteger < 1, an empty collection is answered. An exception is raised if < anInteger elements are avaiable in this stream.
Arguments:
anInteger - <Integer>
aByteCollection - <ByteArray | String>
initialPosition - <Integer>
Answers:
<ByteArray | String> aByteCollection
Raises:
<ExCLDTIndexOutOfRange>
<OsProcessException>
</code></pre> </details>
<details> nextInto:
<pre><code> BLOCKING Insert the next @aByteCollection size number of elements from the pipe into @aByteCollection starting at 1 The caller will block until @abyteCollection size of elements are available or End Of Pipe because the write end of the pipe was closed. If @anInteger < 1, an empty collection is answered. An exception is raised if < anInteger elements are avaiable in this stream.
Arguments:
aByteCollection - <ByteArray | String>
Answers:
<ByteArray | String> aByteCollection
Raises:
<OsProcessException>
</code></pre> </details>
<details> nextLine
<pre><code> BLOCKING Answer the elements between the current position and the next lineDelimiter.
The caller will block until the next lineDelimiter is reached or End Of Pipe because the write end of the pipe was closed.
If #shouldSearchForAllStandardDelimiters answers false
(likely, the user has specified an explicit line delimiter via #lineDelimiter:)
then we ONLY search for that delimiter. However, if it answers true
(likely the stream current delimiter is the default one), then we try to look
for any of the standard delimiters: Cr, Lf, and CrLf. This is useful when we are
reading streams that could have been written on different platforms.
Answers:
<ByteArray | String>
</code></pre> </details>
<details> peek
<pre><code> NON-BLOCKING Answer the next byte or char from the pipe without removing it
Answers:
<Integer | Character>
</code></pre> </details>
<details> position
<pre><code> Answer the virtual stream position. The position can be determined by asking the buffers how many bytes have they consumed
Answers:
<Integer>
</code></pre> </details>
<details> skip:
<pre><code> BLOCKING Read and discard @anInteger number of elements from the pipe. The caller will block until all @anInteger elements are skipped or End Of Pipe because the write end of the pipe was closed. Fail if the number of elements in the pipe < @anInteger
Arguments:
anInteger - <Integer>
</code></pre> </details>
<details> skipTo:
<pre><code> BLOCKING Read and discard elements just past the occurrence of @aByteOrChar. The caller will block until @aByteOrChar is found or End Of Pipe because the write end of the pipe was closed.
Arguments:
aByteOrChar - <Integer | Character>
Answers:
<Boolean> true if found, false otherwise
</code></pre> </details>
<details> skipToAll:
<pre><code> BLOCKING Read and discard elements just past the occurrence of @aByteCollection. The caller will block until all occurrences in @aByteCollection are found or End Of Pipe because the write end of the pipe was closed.
Arguments:
aByteColletion - <ByteArray | String>
</code></pre> </details>
<details> skipToAny:
<pre><code> BLOCKING Read and discard elements beyond the next occurrence of an element that exists in @aSequentialCollection or if none, to the end of stream. The caller will block until any occurrences in @aByteCollection are found or End Of Pipe because the write end of the pipe was closed. Answer true if an element in @aSequentialCollection occurred, else answer false.
Arguments:
aSequentialCollection - <aSequentialCollection>
Answers:
<Boolean>
</code></pre> </details>
<details> tryNext
<pre><code> NON-BLOCKING Answer the next element in the pipe. Answer nil if the pipe is at the end.
Answers:
<Integer | Character> next element
<UndefinedObject> no more elements
</code></pre> </details>
<details> tryNext:
<pre><code> NON-BLOCKING Answer a collection containing UP TO @anInteger number of elements read from the pipe. If @anInteger < 1 or no more elements remain in this pipe, an empty collection is answered
Note: The try API does not raise an exception if there is < @anInteger number of
elements remaining.
Arguments:
anInteger - <Integer>
Answers:
<ByteArray | String>
</code></pre> </details>
<details> tryNext:into:
<pre><code> NON-BLOCKING Insert UP TO the next @anInteger elements from the pipe into @aByteCollection starting at 1
Note: The try API does not raise an exception if there is < @anInteger number of
elements remaining. It also answers the actual number of elements inserted
Arguments:
anInteger - <Integer>
aByteCollection - <ByteArray | String>
Answers:
<Integer> 0 if anInteger is 0
-1 if at end of stream
<n> actual number of elements inserted
</code></pre> </details>
<details> tryNext:into:startingAt:
<pre><code> NON-BLOCKING Insert UP TO the next @anInteger elements from the pipe into @aByteCollection starting at the 1-based @initialPosition
Note: The try API does not raise an exception if there is < @anInteger number of
elements remaining. It also answers the actual number of elements inserted
Arguments:
anInteger - <Integer> number of elements to insert
aByteCollection - <ByteArray | String> collection to insert into
initialPosition - <Integer> 1-based index to start inserting into @aByteCollection
Answers:
<Integer> 0 if anInteger is 0
-1 if at end of stream
<n> actual number of elements inserted
</code></pre> </details>
<details> tryNextAvailable
<pre><code> NON-BLOCKING Answer the available bytes This includes the bytes in the internal buffers, as well as the bytes in the pipe at the time the #available call was made.
Answers:
<ByteArray | String>
</code></pre> </details>
<details> tryNextInto:
<pre><code> NON-BLOCKING Insert UP TO the next @aByteCollection size number of elements into @aByteCollection starting at 1 Change the state of this stream such that these elements will no longer be accessible.
Note: The try API does not raise an exception if there is < @anInteger number of
elements remaining. It also answers the actual number of elements inserted
Arguments:
anInteger - <Integer>
Answers:
<Integer> 0 if anInteger is 0
-1 if at end of stream
<n> actual number of elements inserted
</code></pre> </details>
<details> trySkip:
<pre><code> NON-BLOCKING Attempt to read and discard @anInteger number of elements from the pipe. If the end of pipe is reached first, then answer the number of bytes actually skipped
Arguments:
anInteger - <Integer>
Answers:
<Integer> number actually skipped
</code></pre> </details>
<details> trySkipTo:
<pre><code> NON-BLOCKING Attempt to read and discard elements just past the occurrence of @aByteOrChar. Answer true if it was found, false if it was never found and the end of pipe was reached during this invocation.
Arguments:
aByteOrChar - <Integer | Character>
Answers:
<Boolean>
</code></pre> </details>
<details> trySkipToAll:
<pre><code> NON-BLOCKING Attempt to read and discard elements just past the occurrence of @aByteCollection.
Arguments:
aByteColletion - <ByteArray | String>
</code></pre> </details>
<details> trySkipToAny:
<pre><code> NON-BLOCKING Attempt to read and discard elements beyond the next occurrence of an element that exists in @aSequentialCollection or if none, to the end of stream. Answer true if an element in @aSequentialCollection occurred, else answer false.
Arguments:
aSequentialCollection - <aSequentialCollection>
Answers:
<Boolean>
</code></pre> </details>
<details> tryUpTo:
<pre><code> NON-BLOCKING Answers a collection of all of the objects in the pipe beginning from the current position up to, but not including, @aByteOrChar
Arguments:
aByteOrChar - <Integer | Character>
Answers:
<ByteArray or String>
</code></pre> </details>
<details> tryUpToAll:
<pre><code> NON-BLOCKING Answers a collection of all of the objects in the pipe beginning from the current position up to, but not including, @aByteCollection
Arguments:
aByteColletion - <ByteArray | String>
Answers:
<ByteArray or String>
</code></pre> </details>
<details> tryUpToAny:
<pre><code> NON-BLOCKING Answers a collection of all of the objects in the pipe up to, but not including, the next occurrence of the element that exists in @aSequenceableCollection. If the element that exists in @aSequenceableCollection is not found and the end of the pipe is encountered, an ordered collection of the objects read is returned.
Arguments:
aSequentialCollection - <aSequentialCollection>
Answers:
<SequenceableCollection>
</code></pre> </details>
<details> upTo:
<pre><code> BLOCKING Answers a collection of all of the objects in the pipe beginning from the current position up to, but not including, @aByteOrChar. The caller will block until @aByteOrChar is found or End Of Pipe because the write end of the pipe was closed.
Arguments:
aByteOrChar - <Integer | Character>
Answers:
<ByteArray or String>
</code></pre> </details>
<details> upToAll:
<pre><code> BLOCKING Answers a collection of all of the objects in the pipe beginning from the current position up to, but not including, @aByteCollection The caller will block until all occurrences in @aByteCollection are found or End Of Pipe because the write end of the pipe was closed.
Arguments:
aByteColletion - <ByteArray | String>
Answers:
<ByteArray or String>
</code></pre> </details>
<details> upToAny:
<pre><code> BLOCKING Answers a collection of all of the objects in the pipe up to, but not including, the next occurrence of the element that exists in @aSequenceableCollection. If the element that exists in @aSequenceableCollection is not found and the end of the pipe is encountered, an ordered collection of the objects read is returned. The caller will block until any occurrences in @aByteCollection are found or End Of Pipe because the write end of the pipe was closed.
Arguments:
aSequentialCollection - <aSequentialCollection>
Answers:
<SequenceableCollection>
</code></pre> </details>
<details> upToEnd
<pre><code> NON-BLOCKING Answer a collection containing UP TO the maximum number of elements read from the pipe. If there are no more bytes available to be read, then an empty collection is answered.
Since a <ByteArray> or <String> is being answered, the maximum number of elements is restricted
to be the largest index for a byte-shaped object.
Note: This method involves grabbing all remaining bytes IN THE READ PIPE, not
necessarily all remaining bytes the external program will ever generate.
Answers:
<ByteArray | String>
</code></pre> </details>