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


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



comments?