ibis.ipl
Interface ReadMessage

public interface ReadMessage

The Ibis abstraction for data to be read. A ReadMessage is obtained from a receiveport, either by means of an upcall, or by means of an explicit receive, which is accomplished by call to receive. A receiveport can be configured to generate upcalls or to support blocking receive, but NOT both! At most one ReadMessage is alive at one time for a given ReceivePort. For all read methods in this class, the invariant is that the reads must match the writes one by one. The only exception to this rule is that an array written with any of the writeArray methods of WriteMessage can be read by readObject(). In particular, an array written with writeObject cannot be read with readArray, because writeObject does duplicate detection, and may have written only a handle.

Field Summary

static long

INITIAL_SEQNO The first sequence number when communication is numbered.

Method Summary

long	finish() The finish operation is used to indicate that the reader is done with the message.
void	finish(java.io.IOException e) This method can be used to inform Ibis that one of the ReadMessage methods has thrown an IOException.
ReceivePort	localPort() Returns the receiveport of this ReadMessage.
SendPortIdentifier	origin() Returns the sendport identifier of the sender of this message.
void	readArray(boolean[] destination) Receives an array in place.
void	readArray(boolean[] destination, int offset, int size) Reads a slice of an array in place.
void	readArray(byte[] destination) See readArray(boolean[]) for a description.
void	readArray(byte[] destination, int offset, int size) See readArray(boolean[], int, int) for a description.
void	readArray(char[] destination) See readArray(boolean[]) for a description.
void	readArray(char[] destination, int offset, int size) See readArray(boolean[], int, int) for a description.
void	readArray(double[] destination) See readArray(boolean[]) for a description.
void	readArray(double[] destination, int offset, int size) See readArray(boolean[], int, int) for a description.
void	readArray(float[] destination) See readArray(boolean[]) for a description.
void	readArray(float[] destination, int offset, int size) See readArray(boolean[], int, int) for a description.
void	readArray(int[] destination) See readArray(boolean[]) for a description.
void	readArray(int[] destination, int offset, int size) See readArray(boolean[], int, int) for a description.
void	readArray(long[] destination) See readArray(boolean[]) for a description.
void	readArray(long[] destination, int offset, int size) See readArray(boolean[], int, int) for a description.
void	readArray(java.lang.Object[] destination) See readArray(boolean[]) for a description.
void	readArray(java.lang.Object[] destination, int offset, int size) See readArray(boolean[], int, int) for a description.
void	readArray(short[] destination) See readArray(boolean[]) for a description.
void	readArray(short[] destination, int offset, int size) See readArray(boolean[], int, int) for a description.
boolean	readBoolean() Reads a boolean value from the message.
byte	readByte() Reads a byte value from the message.
char	readChar() Reads a char value from the message.
double	readDouble() Reads a double value from the message.
float	readFloat() Reads a float value from the message.
int	readInt() Reads an int value from the message.
long	readLong() Reads a long value from the message.
java.lang.Object	readObject() Reads an Object value from the message.
short	readShort() Reads a short value from the message.
java.lang.String	readString() Reads a String value from the message.
long	sequenceNumber() Returns the sequence number of this message.

Field Detail

INITIAL_SEQNO

public static final long INITIAL_SEQNO

The first sequence number when communication is numbered.

See Also:

Constant Field Values

Method Detail

finish

public long finish()
            throws java.io.IOException

The finish operation is used to indicate that the reader is done with the message. After the finish, no more bytes can be read from the message. The thread reading the message (can be an upcall) is NOT allowed to block when a message is alive but not finished. Only after the finish is called can the thread that holds the message block. The finish operation must always be called when blocking receive is used. When upcalls are used, the finish can be avoided when the user is sure that the upcall never blocks or waits for a message to arrive. In that case, the message is automatically finished when the upcall terminates. This is much more efficient, because in this way, the runtime system can reuse the upcall thread!

Returns:

the number of bytes read from this message.

Throws:

java.io.IOException

finish

public void finish(java.io.IOException e)

This method can be used to inform Ibis that one of the ReadMessage methods has thrown an IOException. It implies a finish(). In a message upcall, the alternative way to do this is to have the upcall throw the exception.

Parameters:

e - the exception that was thrown.

localPort

public ReceivePort localPort()

Returns the receiveport of this ReadMessage.

Returns:

the receiveport of this ReadMessage.

sequenceNumber

public long sequenceNumber()

Returns the sequence number of this message. An Ibis implementation may choose to just return -1, in case it does not promise a specific ordering of the messages.

Returns:

a sequence number, or -1.

origin

public SendPortIdentifier origin()

Returns the sendport identifier of the sender of this message.

Returns:

the id of the sender of this message.

readBoolean

public boolean readBoolean()
                    throws java.io.IOException

Reads a boolean value from the message.

Returns:

the value read.

Throws:

java.io.IOException - an error occurred

readByte

public byte readByte()
              throws java.io.IOException

Reads a byte value from the message.

Returns:

the value read.

Throws:

java.io.IOException - an error occurred

readChar

public char readChar()
              throws java.io.IOException

Reads a char value from the message.

Returns:

the value read.

Throws:

java.io.IOException - an error occurred

readShort

public short readShort()
                throws java.io.IOException

Reads a short value from the message.

Returns:

the value read.

Throws:

java.io.IOException - an error occurred

readInt

public int readInt()
            throws java.io.IOException

Reads an int value from the message.

Returns:

the value read.

Throws:

java.io.IOException - an error occurred

readLong

public long readLong()
              throws java.io.IOException

Reads a long value from the message.

Returns:

the value read.

Throws:

java.io.IOException - an error occurred

readFloat

public float readFloat()
                throws java.io.IOException

Reads a float value from the message.

Returns:

the value read.

Throws:

java.io.IOException - an error occurred

readDouble

public double readDouble()
                  throws java.io.IOException

Reads a double value from the message.

Returns:

the value read.

Throws:

java.io.IOException - an error occurred

readString

public java.lang.String readString()
                            throws java.io.IOException

Reads a String value from the message.

Returns:

the value read.

Throws:

java.io.IOException - an error occurred

readObject

public java.lang.Object readObject()
                            throws java.io.IOException,
                                   java.lang.ClassNotFoundException

Reads an Object value from the message. Note: implementations should take care that an array, written with one of the writeArray variants, can be read with readObject.

Returns:

the value read.

Throws:

java.io.IOException - an error occurred

java.lang.ClassNotFoundException - is thrown when an object arrives of a class that cannot be loaded locally.

readArray

public void readArray(boolean[] destination)
               throws java.io.IOException

Receives an array in place. These methods are a shortcut for readArray(destination, 0, destination.length);

Parameters:

destination - where the received array is stored.

Throws:

java.io.IOException - is thrown when an IO error occurs.

readArray

public void readArray(byte[] destination)
               throws java.io.IOException

See readArray(boolean[]) for a description.

Throws:

java.io.IOException

readArray

public void readArray(char[] destination)
               throws java.io.IOException

See readArray(boolean[]) for a description.

Throws:

java.io.IOException

readArray

public void readArray(short[] destination)
               throws java.io.IOException

See readArray(boolean[]) for a description.

Throws:

java.io.IOException

readArray

public void readArray(int[] destination)
               throws java.io.IOException

See readArray(boolean[]) for a description.

Throws:

java.io.IOException

readArray

public void readArray(long[] destination)
               throws java.io.IOException

See readArray(boolean[]) for a description.

Throws:

java.io.IOException

readArray

public void readArray(float[] destination)
               throws java.io.IOException

See readArray(boolean[]) for a description.

Throws:

java.io.IOException

readArray

public void readArray(double[] destination)
               throws java.io.IOException

See readArray(boolean[]) for a description.

Throws:

java.io.IOException

readArray

public void readArray(java.lang.Object[] destination)
               throws java.io.IOException,
                      java.lang.ClassNotFoundException

See readArray(boolean[]) for a description.

Throws:

java.lang.ClassNotFoundException - when an object arrives of a class that cannot be loaded locally.

java.io.IOException

readArray

public void readArray(boolean[] destination,
                      int offset,
                      int size)
               throws java.io.IOException

Reads a slice of an array in place. No cycle checks are done.

Parameters:

destination - array in which the slice is stored

offset - offset where the slice starts

size - length of the slice (the number of elements)

Throws:

java.io.IOException - is thrown on an IO error.

readArray

public void readArray(byte[] destination,
                      int offset,
                      int size)
               throws java.io.IOException

See readArray(boolean[], int, int) for a description.

Throws:

java.io.IOException

readArray

public void readArray(char[] destination,
                      int offset,
                      int size)
               throws java.io.IOException

See readArray(boolean[], int, int) for a description.

Throws:

java.io.IOException

readArray

public void readArray(short[] destination,
                      int offset,
                      int size)
               throws java.io.IOException

See readArray(boolean[], int, int) for a description.

Throws:

java.io.IOException

readArray

public void readArray(int[] destination,
                      int offset,
                      int size)
               throws java.io.IOException

See readArray(boolean[], int, int) for a description.

Throws:

java.io.IOException

readArray

public void readArray(long[] destination,
                      int offset,
                      int size)
               throws java.io.IOException

See readArray(boolean[], int, int) for a description.

Throws:

java.io.IOException

readArray

public void readArray(float[] destination,
                      int offset,
                      int size)
               throws java.io.IOException

See readArray(boolean[], int, int) for a description.

Throws:

java.io.IOException

readArray

public void readArray(double[] destination,
                      int offset,
                      int size)
               throws java.io.IOException

See readArray(boolean[], int, int) for a description.

Throws:

java.io.IOException

readArray

public void readArray(java.lang.Object[] destination,
                      int offset,
                      int size)
               throws java.io.IOException,
                      java.lang.ClassNotFoundException

See readArray(boolean[], int, int) for a description.

Throws:

java.lang.ClassNotFoundException - when an object arrives of a class that cannot be loaded locally.

java.io.IOException