eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'NonPositionableExternalStream':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: NonPositionableExternalStream


Inheritance:

   Object
   |
   +--Stream
      |
      +--PeekableStream
         |
         +--PositionableStream
            |
            +--WriteStream
               |
               +--ReadWriteStream
                  |
                  +--ExternalStream
                     |
                     +--NonPositionableExternalStream
                        |
                        +--PipeStream
                        |
                        +--SerialPort
                        |
                        +--Socket

Package:
stx:libbasic
Category:
Streams-External
Version:
rev: 1.119 date: 2019/03/13 19:16:25
user: stefan
file: NonPositionableExternalStream.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

Description:


This class provides common protocol for all non-positionable,
external streams. Concrete subclasses are terminal streams, pipe streams,
PrinterStreams, Sockets etc.

There are three special instances of this class, representing stdin,
stdout and stderr of the smalltalk/X process (see Unix manuals, if you
don't know what those are used for). These special streams are bound to
to globals Stdin, Stdout and Stderr at early initialization time
(see Smalltalk>>initializeStandardStreams).

The name of this class is a historical leftover - it should be called
'TTYStream' or similar.


Class protocol:

instance creation
o  forStderr
return a NonPositionableExternalStream object for writing to
Unixes standard error output file descriptor

o  forStdin
return a NonPositionableExternalStream object for reading from
Unixes standard input file descriptor

o  forStdout
return a NonPositionableExternalStream object for writing to
Unixes standard output file descriptor

o  makeBidirectionalPipe
return an array with two streams - the first one for reading,
the second for writing.
This is the higher level equivalent of OperatingSystem>>makeBidirectionalPipe
(which returns an array of file-descriptors).

o  makePTYPair
return an array with two streams - the first one is the master,
the second the slave of a ptym/ptys pair.
(actually, there is a third element, which is the slave-pty's name)
This is much like a bidirectional pipe, but allows signals &
control chars to be passed through the connection.
This is needed to execute a shell in a view.
This is the higher level equivalent of OperatingSystem>>makePTYPair
(which returns an array of file-descriptors).

usage example(s):

     ExternalStream makePTYPair.

o  makePipe
return an array with two streams - the first one for reading,
the second for writing.
This is the higher level equivalent of OperatingSystem>>makePipe
(which returns an array of file-descriptors).


Instance protocol:

accessing
o  buffered: aBoolean
do not allow to change to buffered mode - ignore true here

o  setCommandString: dummyString
dummy for PipeStream compatibility

error handling
o  errorNotOpen
report an error, that the stream has not been opened or has been closed.
Redefined to care for closed stdout and stderr,
which happens, if the console is closed while I am running.
In this case, we ignore the error.

o  positionError
notify that this stream has no concept of a position

usage example(s):

     Stderr positionError

o  writeError: errorNumber
report an error, that some write error occurred.
Redefined to care for writeErrors on stdout and stderr,
which happens under linux, if the console is closed while I am running.
In this case, we ignore the error.

initialization
o  initialize
non-positionable streams do not work well when buffered

inspecting
o  inspectorExtraMenuOperations
( an extension from the stx:libtool package )
extra operation-menu entries to be shown in an inspector.
Answers a collection of pairs contining aString and action aBlock.
aString is the label of the menu item.
aBlock is evaluated when the menu item is selected.
To be redefined in objects which think that it makes sense to offer
often used operations in an inspector.
See SerialPort as an example.

non homogenous reading
o  nextBytes: count into: anObject startingAt: start
read the next count bytes into an object and return the number of
bytes read or the number of bytes read, if EOF is encountered before.
An exception is raised if the connection is broken.

Redefined here to avoid blocking of ST/X when waiting for io.
Instead only the calling thread will block

o  nextInt16MSB: msbFlag
redefined to wait for data on pipes and sockets

o  nextInt32MSB: msbFlag
redefined to wait for data on pipes and sockets

o  nextInt64MSB: msbFlag
redefined to wait for data on pipes and sockets

o  nextUnsignedInt16MSB: msbFlag
redefined to wait for data on pipes and sockets

o  nextUnsignedInt32MSB: msbFlag
redefined to wait for data on pipes and sockets

o  nextUnsignedInt64MSB: msbFlag
redefined to wait for data on pipes and sockets

positioning
o  position

o  position: newPosition
there is no turning back

o  setToEnd
skip to the end of stream.

o  skip: numberToSkip
skip count bytes/characters, return the receiver.
Re-redefined since PositionableStream redefined it.

printing & storing
o  printOn: aStream
append a user printed representation of the receiver to aStream.
The format is suitable for a human - not meant to be read back.

o  storeOn: aStream
append a printed representation of the receiver on aStream, from
which the receiver can be reconstructed.

private
o  protected closeFile
make sure, that no select is performed on closed file descriptors

o  handleForStderr
return a stderr handle

o  handleForStdin
return a stdin handle

o  handleForStdout
return a stdout handle

o  initializeForStderr
setup for writing to stderr

o  initializeForStdin
setup for reading stdin

o  initializeForStdout
setup for writing to stdout

o  reOpen
reopen the stream after an image restart.
If I am one of the standard streams, reopen is easy

queries
o  atEnd
return true, if position is at end.
Notice: this is a blocking operation, as we do not know in advance,
if there will be anything to read
(i.e. if the partner will send more or close the stream).
If you want to check for available data,
use nextAvailable:, or canReadWithoutBlocking

o  collectionSize
we do not know our size

o  isPositionable
return true, if the stream supports positioning (this one is not)

o  remainingSize
we do not know our size

o  size
we do not know our size

reading
o  next
return the next element, if available.
If nothing is available, this does never raise a read-beyond end signal.
Instead, nil is returned immediately.

Redefined, to wait on pipes and sockets

o  nextByte
redefined, to wait on pipes and sockets

o  nextLine
return the characters upTo (but excluding) the next cr (carriage return)
character (i.e. read a single line of text).
If the previous-to-last character is a cr, this is also removed,
so it's possible to read alien (i.e. ms-dos) text as well.
Redefined to not block forever if no cr is read.

o  nextOrNil
like #next, this returns the next element, if available.
If nothing is available, this does never raise a read-beyond end signal.
Instead, nil is returned immediately.

Redefined, to wait on pipes and sockets

o  peek
Redefined, to wait on pipes and sockets

o  peekOrNil
like #peek, this returns the next element, if available.
If nothing is available, this does never raise a read-beyond end signal.
Instead, nil is returned immediately.

Redefined, to wait on pipes and sockets

o  upTo: anObject into: aStream
read a collection of all objects up-to anObject and append these
elements to aStream, but excluding anObject.
The next read operation will return the element after anObject.
(i.e. anObject is considered a separator, which is skipped)
Similar to #through:, but the matching object is not included in the returned collection.
If anObject is not encountered, all elements up to the end are read and returned.
Compare this with #through: which also reads up to some object
and also positions behind it, but DOES include it in the returned value.

testing
o  canReadWithoutBlocking
return true, if any data is available for reading (i.e.
a read operation will not block the smalltalk process), false otherwise.
We know, that error conditions do not block, so return true for errors.

o  canWriteWithoutBlocking
return true, if data can be written into the stream
(i.e. a write operation will not block the smalltalk process).
We know, that error conditions do not block, so return true for errors.

writing
o  nextPutAll: aCollection
nextPutBytes handles non-blocking io in receiver

o  nextPutAll: aCollection startingAt: start to: stop
redefined, to wait until stream is writable, to avoid blocking in a write

o  nextPutBytes: initialWriteCount from: buffer startingAt: initialOffset
redefined, to wait until stream is writable, to avoid blocking in a write

o  nextPutLine: aString
write the characters in aString and append an end-of-Line marker
(LF, CR or CRLF - depending in the setting of eolMode)



ST/X 7.2.0.0; WebServer 1.670 at bd0aa1f87cdd.unknown:8081; Fri, 29 Mar 2024 14:35:52 GMT