Package ibis.ipl

This package describes the Ibis Portability Layer (IPL), which is to be implemented by Ibis implementations.

See:
Description

Interface Summary

ReadMessage	The Ibis abstraction for data to be read.
ReceivePort	A receiveport maintains connections to one or more sendports.
ReceivePortConnectUpcall	Connection upcall interface for receiveports.
ReceivePortIdentifier	Identifies a ReceivePort on the sending side.
Registry	A Registry provides methods for storing and retrieving ReceivePortIdentifiers or IbisIdentifiers with arbitrary names.
Replacer	Object replacer, used in object serialization..
ResizeHandler	Describes the upcalls that are generated for the Ibis group management of a run.
SendPort	Maintains connections to one or more receive ports.
SendPortConnectUpcall	Connection upcall interface for sendports.
SendPortIdentifier	Identifies a SendPort on the receiver side.
Upcall	Describes the interface for upcall based communication.
WriteMessage	The Ibis abstraction for data to be written.

Class Summary

DynamicProperties	Dynamic properties associated with a send or receive port.
Ibis	This class defines the Ibis API, which can be implemented by an Ibis implementation.
IbisIdentifier	Identifies an Ibis on the network.
PortType	A PortType represents a class of send and receive ports with specific properties and with a specific role in the program.
StaticProperties	Container for the properties of an Ibis or a PortType.

Exception Summary

AlreadyConnectedException	Signals that a connection has been refused, because it already exists.
BindingException	Signals that a request for binding/unbinding of a receiveport failed.
ConnectionClosedException	Signals that a connection has been closed.
ConnectionRefusedException	Signals that a connection has been refused.
ConnectionTimedOutException	Signals that an attempt to set up a connection timed out.
IbisConfigurationException	Signals that there was an error in the Ibis configuration.
IbisException	Like java.lang.Exception, but with a cause.
IbisIOException	Like java.io.IOException, but with a cause.
IbisRuntimeException	Like java.lang.RuntimeException, but with a cause.
NoMatchingIbisException	Signals that no matching Ibis could be found.
PortMismatchException	Signals an attempt to connect ports of different types.
ReceiveTimedOutException	Signals a timeout in a ReceivePort.receive(long) invocation.

Error Summary

IbisError

Like java.lang.Error, but with a cause.

Package ibis.ipl Description

This package describes the Ibis Portability Layer (IPL), which is to be implemented by Ibis implementations. Ibis is a new programming environment that combines Java's "run everywhere" portability both with flexible treatment of dynamically available networks and processor pools, and with highly efficient, object-based communication.
Communication is based on ReceivePorts and SendPorts of a certain PortType. A PortType can be created using the createPortType method, where a name is given to the port type (e.g. "satin porttype" or "RMI porttype"). Port properties are given to the port type (for example ports are "totally-ordered" and "reliable" and support "NWS"). For each port type there is a ReceivePort and a SendPort. Only receive ports and send ports of the same port type can communicate. Any number of receive ports and send ports can be created on a JVM (even of the same port type).
SendPorts and ReceivePorts are created by their PortType using the createSendPort and createReceivePort methods. When creating a ReceivePort, it can be supplied with an Upcall object. If so, upcalls are generated when messages arrive. If not, explicit receive must be used to read messages.
The system provides a globally unique ReceivePortIdentifier and SendPortIdentifier for every ReceivePort and SendPort. These identifiers are implementation specific and serializable (and can be sent over the network/saved in a file etc.). When a ReceivePort is created its ReceivePortIdentifier may be stored in a registry. The application storing the ReceivePortIdentifier is responsible for providing a globally unique name (key) that identifies the ReceivePortIdentifier in the registry.
A SendPort takes the initiative to connect to or disconnect from ReceivePorts (otherwise the one-way traffic scheme is violated). A SendPort can be connected to one or more ReceivePorts using their ReceivePortIdentifiers. These ReceivePortIdentifiers may be obtained using the registry, by sending them over the network, or any other way. Additional ReceivePorts may be connected at any time. A SendPort can be disconnected from one or more ReceivePorts using their ReceivePortIdentifiers. Additional ReceivePorts may be disconnected at any time When a SendPort is no longer used it must be closed using the close method. All connections the SendPort has are disconnected. When a ReceivePort is no longer used it must be closed using the close method. This call will block until connections to SendPorts are disconnected (by the SendPorts).
A message can be send from an SendPort to the set of ReceivePorts it is connected to. To do this, a WriteMessage write message is obtained from the SendPort (this allows streaming, as the destination is known). Data can be added to the message using "write" methods (this data may be immediately streamed to the ReceivePorts) of this message. the write message can be send using a send method. This allows the Ibis system to asynchronously start sending the message. The message can be finished using the finish method. When the finish returns, all data has been copied (and now may be changed), and the message may no longer be used.
When a message arrives at a ReceivePort, how it is handled depends on the way the ReceivePort was instantiated. If messages are to be handled by means of upcalls, a "new" thread is started and the upcall is invoked with this message as parameter. When the message is no longer used it MAY be returned to the system using the {ibis.ipl.ReadMessage#finish() finish} method (after which the message may no longer be used). If messages are to be handled by means of explicit receive calls, a message is delivered when the receive method is called. When the message is no longer used it MUST be returned to the system using the {ibis.ipl.ReadMessage#finish() finish} method (after which the message may no longer be used). This is done to free possible resources in the underlying implementation, as waiting for the GC may take too long.