ibis.ipl
Interface ReceivePort

public interface ReceivePort

A receiveport maintains connections to one or more sendports. When creating a receiveport, it is possible to pass a ReceivePortConnectUpcall object. Ibis will call the ReceivePortConnectUpcall.gotConnection(ReceivePort, SendPortIdentifier) upcall of this object when a sendport tries to initiate a new connection to the receiveport. When a connection is lost for some reason (normal close or link error), the ReceivePortConnectUpcall.lostConnection(ReceivePort, SendPortIdentifier, Exception) upcall is performed. Both upcalls are completely asynchronous, but Ibis ensures that at most one is active at any given time. If no ReceivePortConnectUpcall is registered, the user is NOT informed of connections that are created or lost. No exceptions are thrown by the read message when a connection is lost. It is the user's own responsibility to use the lostConnections() method to poll for connections that are lost. The newConnections() method can be used to find out about new connections. Only one upcall is alive at a one time, this includes BOTH normal (message) upcalls AND ConnectUpcalls. Only one message is alive at one time for a given receiveport. This is done to prevent flow control problems. A receiveport can be configured to generate upcalls or to support blocking receive, but NOT both! The message object is always destroyed when the upcall is finished; it is thus not correct to put it in a global variable / queue.

Method Summary

void	close() Frees the resources held by the receiveport.
void	close(long timeoutMillis) Frees the resources held by the receiveport, with timeout.
SendPortIdentifier[]	connectedTo() Returns the set of sendports this receiveport is connected to .
void	disableConnections() Disables the accepting of new connections.
void	disableUpcalls() Prohibits message upcalls.
void	enableConnections() Enables the accepting of new connections.
void	enableUpcalls() Allows message upcalls to occur.
long	getCount() Returns the number of bytes read from this receiveport.
ReceivePortIdentifier	identifier() Returns the ReceivePortIdentifier of this receiveport.
SendPortIdentifier[]	lostConnections() Returns the connections that were lost.
java.lang.String	name() Returns the name of the receiveport.
SendPortIdentifier[]	newConnections() Returns the new connections accepted by this receiveport.
ReadMessage	poll() Asynchronous explicit receive.
DynamicProperties	properties() Returns the DynamicProperties of this port.
ReadMessage	receive() Explicit blocking receive.
ReadMessage	receive(long timeoutMillis) Explicit blocking receive with timeout.
void	resetCount() Resets the counter for the number of bytes read from this receive port to zero.

Method Detail

receive

public ReadMessage receive()
                    throws java.io.IOException

Explicit blocking receive. This method blocks until a message arrives on this receiveport. When a receiveport is configured to generate upcalls, using this method is NOT allowed; in that case an IOException is thrown.

Returns:

the message received.

Throws:

java.io.IOException - is thrown when the receiveport is configured to use upcalls, or something else is wrong.

receive

public ReadMessage receive(long timeoutMillis)
                    throws java.io.IOException

Explicit blocking receive with timeout. This method blocks until a message arrives on this receiveport, or the timeout expires. When an receiveport is configured to generate upcalls, using this method is NOT allowed. The receive blocks at most timeoutMillis, but it might be shorter! A timeoutMillis less than or equal to 0 means just do a blocking receive.

Parameters:

timeoutMillis - timeout in milliseconds.

Returns:

the message received.

Throws:

ReceiveTimedOutException - is thrown when the timeout expires and no message arrives.

java.io.IOException - is thrown when the receiveport is configured to use upcalls, or something else is wrong.

poll

public ReadMessage poll()
                 throws java.io.IOException

Asynchronous explicit receive. Returns immediately, wether or not a message is available. Also works for ports configured for upcalls, in which case it is a normal poll: it will always return null, but it might generate an upcall.

Returns:

the message received, or null.

Throws:

java.io.IOException - on IO error.

getCount

public long getCount()

Returns the number of bytes read from this receiveport. A receiveport maintains a counter of how many bytes are used for messages. Each time a message is being finished, this counter is updated.

Returns:

the number of bytes read.

resetCount

public void resetCount()

Resets the counter for the number of bytes read from this receive port to zero.

properties

public DynamicProperties properties()

Returns the DynamicProperties of this port. The user can set some implementation-specific dynamic properties of the port, by means of the DynamicProperties.set method.

identifier

public ReceivePortIdentifier identifier()

Returns the ReceivePortIdentifier of this receiveport.

Returns:

the identifier.

name

public java.lang.String name()

Returns the name of the receiveport. When the receiveport was created anonymously, a system-invented name will be returned.

Returns:

the name.

enableConnections

public void enableConnections()

Enables the accepting of new connections. When a receiveport is created it will not accept connections, until this method is invoked. This is done to avoid upcalls during initialization. After this method returns, connection upcalls may be triggered.

disableConnections

public void disableConnections()

Disables the accepting of new connections. It is allowed to invoke enableConnections() again after invoking this method. After this method returns, no more connection upcalls will be given.

enableUpcalls

public void enableUpcalls()

Allows message upcalls to occur. This call is meaningless (and a no-op) for receiveports that were created for explicit receive. Upon startup, message upcalls are disabled. They must be explicitly enabled to receive message upcalls.

disableUpcalls

public void disableUpcalls()

Prohibits message upcalls. After this call, no message upcalls will occur until enableUpcalls() is called. The disableUpcalls/enableUpcalls mechanism allows the user to selectively allow or disallow message upcalls during program run. Note: the disableUpcalls/enableUpcalls mechanism is not necessary to enforce serialization of Upcalls for this port. Ibis already guarantees that only one message per port is active at any time.

close

public void close()
           throws java.io.IOException

Frees the resources held by the receiveport. Important: this method blocks until all sendports that are connected to it have been closed.

Throws:

java.io.IOException

close

public void close(long timeoutMillis)
           throws java.io.IOException

Frees the resources held by the receiveport, with timeout. Like close(), but blocks at most timeout milliseconds. When the close does not succeed within the timeout, this operation does a forced close. Important: this call does not block until all sendports that are connected to it have been freed. Therefore, messages may be lost! Use this with extreme caution! When this call is used, and this port is configured to maintain connection administration, it updates the administration and thus may generate lostConnection upcalls.

Parameters:

timeoutMillis - timeout in milliseconds. When zero, the call is equivalent to a close(); when less than zero, the port is closed immediately.

Throws:

java.io.IOException

connectedTo

public SendPortIdentifier[] connectedTo()

Returns the set of sendports this receiveport is connected to .

Returns:

the sendport identifiers.

lostConnections

public SendPortIdentifier[] lostConnections()

Returns the connections that were lost. Connections can be lost due to an error, or because the sender disconnected. Returns the changes since the last lostConnections call, or, if this is the first call, all connections that were lost since the port was created. This call only works if this port is configured to maintain connection administration. If not, null is returned.

Returns:

the lost connections.

newConnections

public SendPortIdentifier[] newConnections()

Returns the new connections accepted by this receiveport. Returns the changes since the last newConnections call, or, if this is the first call, all connections that were created since the port was created. This call only works if this port is configured to maintain connection administration. If not, null is returned.

Returns:

the new connections.