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.156 date: 2024/01/18 14:54:55
user: cg
file: NonPositionableExternalStream.st directory: libbasic
module: stx stc-classLibrary: libbasic

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).

copyright

COPYRIGHT (c) 1989 by Claus Gittinger All Rights Reserved This software is furnished under a license and may be used only in accordance with the terms of that license and with the inclusion of the above copyright notice. This software may not be provided or otherwise made available to, or used by, any other person. No title to or ownership of the software is hereby transferred.

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 for communication in both directions.
This is the higher level equivalent of OperatingSystem>>makeBidirectionalPipe
(which returns an array of file-descriptors).

Usage example(s):

     |pipe rs ws|

     pipe := NonPositionableExternalStream makeBidirectionalPipe.
     rs := pipe at:1.
     ws := pipe at:2.

     'read ...'.
     [
         1 to:10 do:[:i |
             Transcript showCR:rs nextLine
         ].
         rs close.
     ] forkAt:7.

     'write ...'.
     [
         1 to:10 do:[:i |
             ws nextPutAll:'hello world '; nextPutAll:i printString; cr
         ].
         ws close.
     ] fork.

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):

     UnixPTYStream makePTYPair.
     PipeStream 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).

Usage example(s):

     |pipe rs ws|

     pipe := NonPositionableExternalStream makePipe.
     rs := pipe at:1.
     ws := pipe at:2.

     'read ...'.
     [
         1 to:10 do:[:i |
             Transcript showCR:rs nextLine
         ].
         rs close.
     ] forkAt:7.

     'write ...'.
     [
         1 to:10 do:[:i |
             ws nextPutAll:'hello world '; nextPutAll:i printString; cr
         ].
         ws close.
     ] fork.


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 containing aString and action aBlock.
aString is the label of the menu item.
aBlock is evaluated when the menu item is selected.

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  confirm: prompt
only useful for scripts, and only allowed for Stdin, to ask for user input

Usage example(s):

     Stdin confirm:'are you happy?'.

o  getYesNo
read a yes/no answer; user must answer y or n; otherwise ask again.
This is useful for standalone console programs

Usage example(s):

    Stdin getYesNo:[:msg | Stderr nextPutAll:msg] default:nil
    Stdin getYesNo:[:msg | Stderr nextPutAll:msg] default:true.
    Stdin getYesNo.  

o  getYesNo: askAction default: default
read a yes/no answer;
if the default is non-nil, that is returned returned if return is pressed;
otherwise stay in the loop, asking again.
askAction is used to send a message to the user
(caller can choose, how to ask).
This is useful for standalone console programs

Usage example(s):

    Stdin getYesNo:[:msg | Stderr nextPutAll:msg] default:nil
    Stdin getYesNo:[:msg | Stderr nextPutAll:msg] default:true.
    Stdin getYesNo

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.
If at EOF
answer the data present (even if there is no CR).
but answer nil if there is no data present.

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.

Does not block in the moment, but will in the future.

o  peekOrNilNoWait
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.

It does not wait on pipes and sockets and returns only data, that is already present.

o  request: prompt
only useful for scripts, and only allowed for Stdin, to ask for user input

Usage example(s):

     Stdin request:'enter something, please:'.

o  request: prompt defaultAnswer: default
only useful for scripts, and only allowed for Stdin, to ask for user input

Usage example(s):

     Stdin request:'enter something, please:' defaultAnswer:'hello'.

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.

Usage example(s):

     |pipe|

     pipe := PipeStream readingFrom:'(sleep 10; echo hello)'.
     pipe canReadWithoutBlocking ifTrue:[
         Transcript showCR:'data available'
     ] ifFalse:[
         Transcript showCR:'no data available'
     ].
     pipe close

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.
Answer the 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.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Tue, 10 Dec 2024 21:01:29 GMT