org.erights.e.elib.eio
Interface InStream

All Superinterfaces:

Stream

public interface InStream

extends Stream

Untamed: For obtaining elements from a stream.

A client of an InStream is a consumer.

Author:

Mark S. Miller

See Also:

obtaining for more info.

Field Summary

static String	ADVANCE Enabled: proceed value: Advances the stream past the obtained data.
static String	ELEMENTS Enabled: report value: Return the obtained data.
static String	LATER Enabled: sched value: Registers a claim for the next atLeast..atMost elements, and returns a promise for them.
static String	NOW Enabled: sched value: The operation is performed immediately, whether or not sufficient elements are ready.
static String	QUERY Enabled: proceed value: Does not advance the stream.
static String	STATUS Enabled: report value: Ignore the obtained data and return termination status.
static String	WAIT Enabled: sched value: Warning: may block the vat and cause deadlock.

Method Summary

Object	becomesReady(int num) Enabled: Returns a vow that's resolved once the next num elements from the stream becomes ready.
Object	close() Enabled: Reliquish the ability to obtain any further elements from the stream, thereby allowing the stream and its upstream producers to release resources and avoid wasted effort.
Object	obtain(int atLeast, int atMost, String sched, String proceed, String report) Enabled: The generic obtain operation in which all the orthogonal dimensions are explicit parameters.
ConstList	peek(int atLeast, int atMost) Enabled: Immediately reads and returns, but does not consume, the next N elements of the stream, where N is in the range defined by atLeast..atMost.
ConstList	read(int atLeast, int atMost) Enabled: Immediately reads, consumes, and returns the next N elements of the stream, where N is in the range defined by atLeast..atMost.
ConstList	readAll() Enabled: Immediately reads, consumes, and returns all remaining elements of the stream.
Object	readAllLater() Enabled: Immediately reads, consumes, and returns all remaining elements of the stream.
ConstList	readLater(int atLeast, int atMost) Enabled: Immediately reads, consumes, and returns the next N elements of the stream, where N is in the range defined by atLeast..atMost.
Object	readOptOne() Enabled: Immediately reads, consumes, and returns the next element of the stream.
int	remaining() Enabled: How many elements remain in the stream?
Object	skip(int num) Enabled: Removes and discards the next num elements from the stream.
Object	terminates() Enabled: Reliquish the ability to obtain any further elements from the stream, thereby allowing the stream and its upstream producers to release resources and avoid wasted effort.

Methods inherited from interface org.erights.e.elib.eio.Stream

available, closex, fail, getElementType, isTerminated, maxAvailable, terminatesx, whenAvailable

Field Detail

NOW

public static final String NOW

Enabled: sched value: The operation is performed immediately, whether or not sufficient elements are ready.

If a sufficient number of elements cannot be obtained immediately, then an UnavailableException or other IOException is thrown. If an UnavailableException is thrown, then nothing was consumed and no side-effects should have happened. If another IOException is thrown, then any number up to atMost may have been consumed.

WAIT

public static final String WAIT

Enabled: sched value: Warning: may block the vat and cause deadlock.

If the operation can succeed immediately, it is performed immediately. Else, if insufficient elements are currently ready, and if this InStream supports waiting, then the calling vat/runner/thread is blocked until this operation can immediately complete. The wrappers of java.io streams support waiting.

m This should normally only be used when

• The programmer knows the source to be prompt even though the underlying java.io stream doesn't.
• This vat exists for the purpose of building one virtual device from some underlying non-prompt stream, as with a one-top-level-expr-at-a-time parser parsing an InStream of characters.

LATER

public static final String LATER

Enabled: sched value: Registers a claim for the next atLeast..atMost elements, and returns a promise for them.

When these characters become ready, the claim will be satisfied and the promise will be resolved.

ADVANCE

public static final String ADVANCE

Enabled: proceed value: Advances the stream past the obtained data.

QUERY

public static final String QUERY

Enabled: proceed value: Does not advance the stream.

A QUERY operation should ideally be side-effect free.

ELEMENTS

public static final String ELEMENTS

Enabled: report value: Return the obtained data.

STATUS

public static final String STATUS

Enabled: report value: Ignore the obtained data and return termination status.

Method Detail

obtain

public Object obtain(int atLeast,
                     int atMost,
                     String sched,
                     String proceed,
                     String report)
              throws UnavailableException,
                     IOException

Enabled: The generic obtain operation in which all the orthogonal dimensions are explicit parameters.

All other reading operations are specified by equivalence to a parameterization of obtain/5. Normally, one would call one of those other shorter operations instead.

At an InStream, a sequence of arriving elements is matched to a sequence of reading operations according to the order of the elements and the order in which the reading operations were invoked on the InStream.

Parameters:

atLeast - Must be >= 0 or EIO.ALL. Indicates the smallest number of elements this obtain operation may obtain and still report success. ALL means "All remaining elements in the stream until stream termination." Any other non-negative integer means "That many elements, or all remaining elements, whichever comes first."

atMost - Must be >= atLeast or EIO.ALL. Indicates the largest number of elements this obtain operation may obtain.

A sufficient number of elements is a number in the range of size that may be obtain according to atLeast..atMost by the above spec. A reading operation generally should obtain the largest sufficient number it can conveniently obtain.

sched - One of NOW, WAIT, or LATER.

proceed - Are the obtain elements consumed from the stream? If so, this relieves backpressure, thereby allowing further elements to continue flowing downstream.

If not, then this is a peeking operation and should be side-effect free.

report - Are the obtain elements gathered into a list and returned? If not, then this is a skipping operation. If both proceed and report are false, then this is an operation for checking when new data becomesReady.

Returns:

If sched is LATER, then return a vow for the result. Else return the result. If report is true, then the result will be a list of a sufficient number of elements; else the result will be null. If this operation fails, the vow should resolve to a reference broken by the problem that would have been thrown.

Throws:

UnavailableException - If sched==NOW, sufficient elements were not ready, and none were consumed.

IOException - If any other I/O problems occur, or if the stream has already failed. If this is thrown because the stream has already failed, this should be the stream's terminal problem.

read

public ConstList read(int atLeast,
                      int atMost)
               throws UnavailableException,
                      IOException

Enabled: Immediately reads, consumes, and returns the next N elements of the stream, where N is in the range defined by atLeast..atMost.

    i.read(atLeast,atMost)

is defined by equivalence to

    i.obtain(atLeast,atMost,NOW,true,true)

UnavailableException

IOException

readLater

public ConstList readLater(int atLeast,
                           int atMost)
                    throws UnavailableException,
                           IOException

Enabled: Immediately reads, consumes, and returns the next N elements of the stream, where N is in the range defined by atLeast..atMost.

    i.readLater(atLeast,atMost)

is defined by equivalence to

    i.obtain(atLeast,atMost,LATER,true,true)

UnavailableException

IOException

readOptOne

public Object readOptOne()
                  throws UnavailableException,
                         IOException

Enabled: Immediately reads, consumes, and returns the next element of the stream.

    i.readOptOne()

is defined by equivalence to

     def list := i.obtain(1,1,NOW,true,true)
     if (list.size() == 0) {
         null
     } else {
         list[0]
     }

In other words, if the stream is terminated, then return null. If null is also a valid element of this stream, readOptOne's caller must be aware that a null may be returned for either reason.

UnavailableException

IOException

readAll

public ConstList readAll()
                  throws UnavailableException,
                         IOException

Enabled: Immediately reads, consumes, and returns all remaining elements of the stream.

    i.readAll()

is defined by equivalence to

    i.obtain(ALL,ALL,NOW,true,true)

UnavailableException

IOException

readAllLater

public Object readAllLater()
                    throws UnavailableException,
                           IOException

Enabled: Immediately reads, consumes, and returns all remaining elements of the stream.

    i.readAllLater()

is defined by equivalence to

    i.obtain(ALL,ALL,LATER,true,true)

UnavailableException

IOException

peek

public ConstList peek(int atLeast,
                      int atMost)
               throws UnavailableException,
                      IOException

Enabled: Immediately reads and returns, but does not consume, the next N elements of the stream, where N is in the range defined by atLeast..atMost.

    i.peek(atLeast,atMost)

is defined by equivalence to

    i.obtain(atLeast,atMost,NOW,false,true)

UnavailableException

IOException

skip

public Object skip(int num)
            throws UnavailableException,
                   IOException

Enabled: Removes and discards the next num elements from the stream.

    i.skip(num)

is defined by equivalence to

    i.obtain(num,num,LATER,true,false)

UnavailableException

IOException

becomesReady

public Object becomesReady(int num)
                    throws IOException

Enabled: Returns a vow that's resolved once the next num elements from the stream becomes ready.

    i.becomesReady(num)

is defined by equivalence to

    i.obtain(num,num,LATER,false,false)

IOException

close

public Object close()
             throws IOException

Enabled: Reliquish the ability to obtain any further elements from the stream, thereby allowing the stream and its upstream producers to release resources and avoid wasted effort.

    i.close()

is defined by equivalence to

    i.obtain(ALL,ALL,LATER,true,false)

IOException

terminates

public Object terminates()
                  throws IOException

Enabled: Reliquish the ability to obtain any further elements from the stream, thereby allowing the stream and its upstream producers to release resources and avoid wasted effort.

    i.close()

is defined by equivalence to

    i.obtain(ALL,ALL,LATER,true,false)

IOException

remaining

public int remaining()

Enabled: How many elements remain in the stream?

Until this is known, the answer is ALL. When the stream is terminated, the answer is 0. When all remaining elements are known to be immediately available (as when reading a file), then

    available() == remaining()

.