Smalltalk/X Webserver

Documentation of class 'NonPositionableExternalStream':

Class: NonPositionableExternalStream

Inheritance
Description
Class protocol
- instance creation
Instance protocol

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

copyrightCOPYRIGHT (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.

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.

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

buffered: aBoolean: do not allow to change to buffered mode - ignore true here
setCommandString: dummyString: dummy for PipeStream compatibility

error handling

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.

positionError

notify that this stream has no concept of a position

Usage example(s):

     Stderr positionError

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

initialize: non-positionable streams do not work well when buffered

inspecting

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

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
nextInt16MSB: msbFlag: redefined to wait for data on pipes and sockets
nextInt32MSB: msbFlag: redefined to wait for data on pipes and sockets
nextInt64MSB: msbFlag: redefined to wait for data on pipes and sockets
nextUnsignedInt16MSB: msbFlag: redefined to wait for data on pipes and sockets
nextUnsignedInt32MSB: msbFlag: redefined to wait for data on pipes and sockets
nextUnsignedInt64MSB: msbFlag: redefined to wait for data on pipes and sockets

positioning

position
position: newPosition: there is no turning back
setToEnd: skip to the end of stream.
skip: numberToSkip: skip count bytes/characters, return the receiver.
Re-redefined since PositionableStream redefined it.

printing & storing

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.
storeOn: aStream: append a printed representation of the receiver on aStream, from
which the receiver can be reconstructed.

private

protected closeFile: make sure, that no select is performed on closed file descriptors
handleForStderr: return a stderr handle
handleForStdin: return a stdin handle
handleForStdout: return a stdout handle
initializeForStderr: setup for writing to stderr
initializeForStdin: setup for reading stdin
initializeForStdout: setup for writing to stdout
reOpen: reopen the stream after an image restart.
If I am one of the standard streams, reopen is easy

queries

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
collectionSize: we do not know our size
isPositionable: return true, if the stream supports positioning (this one is not)
remainingSize: we do not know our size
size: we do not know our size

reading

confirm: prompt

only useful for scripts, and only allowed for Stdin, to ask for user input

Usage example(s):

     Stdin confirm:'are you happy?'.

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.

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

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

nextByte

redefined, to wait on pipes and sockets

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.

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

peek

Redefined, to wait on pipes and sockets

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.

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.

request: prompt

only useful for scripts, and only allowed for Stdin, to ask for user input

Usage example(s):

     Stdin request:'enter something, please:'.

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

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

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

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

nextPutAll: aCollection: nextPutBytes handles non-blocking io in receiver.
Answer the receiver
nextPutAll: aCollection startingAt: start to: stop: redefined, to wait until stream is writable, to avoid blocking in a write
nextPutBytes: initialWriteCount from: buffer startingAt: initialOffset: redefined, to wait until stream is writable, to avoid blocking in a write
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; Sat, 21 Dec 2024 18:39:02 GMT

Smalltalk/X Webserver

Documentation of class 'NonPositionableExternalStream':

Class: NonPositionableExternalStream

Inheritance:

Description:

copyright

Class protocol:

Instance protocol: