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 {@link ibis.ipl.ReceivePort ReceivePorts} and {@link ibis.ipl.SendPort SendPorts} of a certain {@link ibis.ipl.PortType PortType}. A {@link ibis.ipl.PortType PortType} can be created using the {@link ibis.ipl.Ibis#createPortType(String, StaticProperties) 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 {@link ibis.ipl.ReceivePort ReceivePort} and a {@link ibis.ipl.SendPort 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 {@link ibis.ipl.PortType#createSendPort(String) createSendPort} and {@link ibis.ipl.PortType#createReceivePort(String) createReceivePort} methods. When creating a ReceivePort, it can be supplied with an {@link ibis.ipl.Upcall 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 {@link ibis.ipl.ReceivePortIdentifier ReceivePortIdentifier} and {@link ibis.ipl.SendPortIdentifier 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 {@link ibis.ipl.Registry 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 {@link ibis.ipl.SendPort#close() close} method. All connections the SendPort has are disconnected. When a ReceivePort is no longer used it must be closed using the {@link ibis.ipl.ReceivePort#close() close} method. This call will block until connections to SendPorts are disconnected (by the SendPorts).
A {@link ibis.ipl.WriteMessage message} can be send from an SendPort to the set of ReceivePorts it is connected to. To do this, a {@link ibis.ipl.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 {@link ibis.ipl.WriteMessage#send() send} method. This allows the Ibis system to asynchronously start sending the message. The message can be finished using the {@link ibis.ipl.WriteMessage#finish() 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 {@link ibis.ipl.ReadMessage 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 {@link 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 {@link ibis.ipl.ReceivePort#receive() receive} method is called. When the message is no longer used it MUST be returned to the system using the {@link 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.