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
atEnd
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>
autoFill
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>
autoFill:
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>
available
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
availableInPipe
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
fill
NON-Blocking: Preemptively attempt to fill the pipe buffer
Answers:
<Integer> number of bytes filled
isBytes:
If true, adjust the buffers to store bytes.
If false, adjust the buffers to store chars.
Inform the @stream
Arguments:
aBoolean - <Boolean>
next
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>
next:
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>
next:into:
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>
next:into:startingAt:
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>
nextInto:
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>
nextLine
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>
peek
NON-BLOCKING
Answer the next byte or char from the pipe without
removing it
Answers:
<Integer | Character>
position
Answer the virtual stream position.
The position can be determined by asking the buffers how many
bytes have they consumed
Answers:
<Integer>
skip:
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>
skipTo:
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
skipToAll:
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>
skipToAny:
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>
tryNext
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
tryNext:
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>
tryNext:into:
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
tryNext:into:startingAt:
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
tryNextAvailable
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>
tryNextInto:
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
trySkip:
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
trySkipTo:
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>
trySkipToAll:
NON-BLOCKING
Attempt to read and discard elements just past the occurrence of @aByteCollection.
Arguments:
aByteColletion - <ByteArray | String>
trySkipToAny:
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>
tryUpTo:
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>
tryUpToAll:
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>
tryUpToAny:
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>
upTo:
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>
upToAll:
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>
upToAny:
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>
upToEnd
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>
Last modified date: 07/07/2022