ibis.ipl
Class Ibis

java.lang.Object
  ibis.ipl.Ibis

public abstract class Ibis

extends java.lang.Object

This class defines the Ibis API, which can be implemented by an Ibis implementation. Every JVM may run multiple Ibis implementations. The user can request a list of available implementations, query their properties, and then load the desired Ibis implementation at runtime. An Ibis implementation offers certain PortType properties. On startup, Ibis tries to load properties files in the following order:
- ibis.property.file;
- a file named "properties" in the classpath.
- current_dir/ibis_properties;
- home_dir/ibis_properties.

Constructor Summary

Ibis()

Method Summary

static Ibis	createIbis(StaticProperties reqprop, ResizeHandler r) Creates a new Ibis instance, based on the required properties, or on the system property "ibis.name", or on the staticproperty "name".
static Ibis	createIbis(java.lang.String name, java.lang.String implName, ResizeHandler resizeHandler) Deprecated. The prefered method for creating Ibis instances is createIbis(ibis.ipl.StaticProperties, ibis.ipl.ResizeHandler).
PortType	createPortType(java.lang.String nm, StaticProperties p) Creates a PortType.
abstract void	died(IbisIdentifier[] corpses) Notifies this Ibis instance that another Ibis instance has died.
abstract void	disableResizeUpcalls() Disables reception of ResizeHandler upcalls.
abstract void	enableResizeUpcalls() Allows reception of ResizeHandler upcalls.
abstract void	end() Returns all Ibis recources to the system.
abstract PortType	getPortType(java.lang.String nm) Returns the PortType corresponding to the given name.
java.lang.String	getVersion() Returns the current Ibis version.
abstract IbisIdentifier	identifier() Returns an Ibis identifier for this Ibis instance.
java.lang.String	implementationName() Returns the implementation name of this Ibis instance.
abstract void	joined(IbisIdentifier joinIdent) Notifies this Ibis instance that another Ibis instance has joined the run.
abstract void	left(IbisIdentifier leaveIdent) Notifies this Ibis instance that another Ibis instance has left the run.
static java.lang.String[]	list() Returns a list of available Ibis implementation names for this system.
static Ibis[]	loadedIbises() Returns a list of all Ibis implementations that are currently loaded.
static void	loadLibrary(java.lang.String name) Loads a native library with ibis.
java.lang.String	name() Deprecated. If you need the name of an Ibis instance, you can use IbisIdentifier.toString().
abstract void	poll() Polls the network for new messages.
StaticProperties	properties() Returns the properties of this Ibis implementation.
abstract Registry	registry() Returns the Ibis Registry.
static StaticProperties	staticProperties(java.lang.String implName) Returns the static properties for a certain implementation.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Ibis

public Ibis()

Method Detail

loadLibrary

public static void loadLibrary(java.lang.String name)
                        throws java.lang.SecurityException,
                               java.lang.UnsatisfiedLinkError

Loads a native library with ibis. It might not be possible to load libraries the normal way, because Ibis applications might override the bootclasspath when the classlibraries have been rewritten. In that case, the classloader will use the sun.boot.library.path which is not portable.

Parameters:

name - the name of the library to be loaded.

Throws:

java.lang.SecurityException - may be thrown by loadLibrary.

java.lang.UnsatisfiedLinkError - may be thrown by loadLibrary.

createIbis

public static Ibis createIbis(java.lang.String name,
                              java.lang.String implName,
                              ResizeHandler resizeHandler)
                       throws IbisException,
                              ConnectionRefusedException

Deprecated. The prefered method for creating Ibis instances is createIbis(ibis.ipl.StaticProperties, ibis.ipl.ResizeHandler).

Creates a new Ibis instance. Instances must be given a unique name, which identifies the instance. Lookups are done using this name. If the user tries to create two instances with the same name, an IbisException will be thrown.

Parameters:

name - a unique name, identifying this Ibis instance.

implName - the name of the implementation.

resizeHandler - will be invoked when Ibises join and leave, and may be null to indicate that resize notifications are not wanted.

Returns:

the new Ibis instance.

Throws:

IbisException - two Ibis instances with the same implName are created, or any IbisException the implementation throws at its initialization

java.lang.IllegalArgumentException - name or implName are null, or do not correspond to an existing Ibis implementation

ConnectionRefusedException - is thrown when the name turns out to be not unique.

loadedIbises

public static Ibis[] loadedIbises()

Returns a list of all Ibis implementations that are currently loaded. When no Ibises are loaded, this method returns an array with no elements.

Returns:

the list of loaded Ibis implementations.

createIbis

public static Ibis createIbis(StaticProperties reqprop,
                              ResizeHandler r)
                       throws IbisException

Creates a new Ibis instance, based on the required properties, or on the system property "ibis.name", or on the staticproperty "name". If the system property "ibis.name" is set, the corresponding Ibis implementation is chosen. Else, if the staticproperty "name" is set in the specified required properties, the corresponding Ibis implementation is chosen. Else, an Ibis implementation is chosen that matches the required properties. The currently recognized Ibis names are:
panda Ibis built on top of Panda.
tcp Ibis built on top of TCP (the current default).
nio Ibis built on top of Java NIO.
mpi Ibis built on top of MPI.
net.* The future version, for tcp, udp, GM.

Parameters:

reqprop - static properties required by the application, or null.

r - a ResizeHandler instance if upcalls for joining or leaving ibis instances are required, or null.

Returns:

the new Ibis instance.

Throws:

NoMatchingIbisException - is thrown when no Ibis was found that matches the properties required.

IbisException

list

public static java.lang.String[] list()

Returns a list of available Ibis implementation names for this system.

Returns:

the list of available Ibis implementations.

staticProperties

public static StaticProperties staticProperties(java.lang.String implName)

Returns the static properties for a certain implementation.

Parameters:

implName - implementation name of an Ibis for which properties are requested.

Returns:

the static properties for a given implementation, or null if not present.

enableResizeUpcalls

public abstract void enableResizeUpcalls()

Allows reception of ResizeHandler upcalls. If a ResizeHandler is installed, this call blocks until its joined() upcall for this Ibis is invoked.

disableResizeUpcalls

public abstract void disableResizeUpcalls()

Disables reception of ResizeHandler upcalls.

end

public abstract void end()
                  throws java.io.IOException

Returns all Ibis recources to the system.

Throws:

java.io.IOException

createPortType

public PortType createPortType(java.lang.String nm,
                               StaticProperties p)
                        throws java.io.IOException,
                               IbisException

Creates a PortType. A name is given to the PortType (e.g. "satin porttype" or "RMI porttype"), and Port properties are specified (for example ports are "totally-ordered" and "reliable" and support "NWS"). If no static properties are given, the properties that were requested from the Ibis implementation are used, possibly combined with properties specified by the user (using the -Dibis.<category>="..." mechanism). If static properties are given, the default properties described above are used for categories not specifiedby the given properties.

The name and properties together define the PortType. If two Ibis instances want to communicate, they must both create a PortType with the same name and properties. If multiple implementations try to create a PortType with the same name but different properties, an IbisException will be thrown. A PortType can be used to create ReceivePorts and SendPorts. Only ReceivePorts and SendPorts of the same PortType can communicate. Any number of ReceivePorts and SendPorts can be created on a JVM (even of the same PortType).

Parameters:

nm - name of the porttype.

p - properties of the porttype.

Returns:

the porttype.

Throws:

IbisException - is thrown when Ibis configuration, name or p are misconfigured

java.io.IOException - may be thrown for instance when communication with a nameserver fails.

getPortType

public abstract PortType getPortType(java.lang.String nm)

Returns the PortType corresponding to the given name.

Parameters:

nm - the name of the requested port type.

Returns:

a reference to the port type, or null if the given name is not the name of a valid port type.

registry

public abstract Registry registry()

Returns the Ibis Registry.

Returns:

the Ibis registry.

properties

public StaticProperties properties()

Returns the properties of this Ibis implementation.

Returns:

the properties of this Ibis implementation.

poll

public abstract void poll()
                   throws java.io.IOException

Polls the network for new messages. An upcall may be generated by the poll. There is one poll for the entire Ibis, as this can sometimes be implemented more efficiently than polling per port. Polling per port is provided in the receiveport itself.

Throws:

java.io.IOException - is thrown when a communication error occurs.

name

public java.lang.String name()

Deprecated. If you need the name of an Ibis instance, you can use IbisIdentifier.toString().

Returns the name of this Ibis instance.

Returns:

the name of this Ibis instance.

implementationName

public java.lang.String implementationName()

Returns the implementation name of this Ibis instance.

Returns:

the implementation name of this Ibis instance.

identifier

public abstract IbisIdentifier identifier()

Returns an Ibis identifier for this Ibis instance. An Ibis identifier identifies an Ibis instance in the network.

Returns:

the Ibis identifier of this Ibis instance.

getVersion

public java.lang.String getVersion()

Returns the current Ibis version.

Returns:

the ibis version.

joined

public abstract void joined(IbisIdentifier joinIdent)

Notifies this Ibis instance that another Ibis instance has joined the run. Note: used by the nameserver, do not call from outside Ibis.

Parameters:

joinIdent - the Ibis identifier of the Ibis instance joining the run.

left

public abstract void left(IbisIdentifier leaveIdent)

Notifies this Ibis instance that another Ibis instance has left the run. Note: used by the nameserver, do not call from outside Ibis.

Parameters:

leaveIdent - the Ibis identifier of the Ibis instance leaving the run.

died

public abstract void died(IbisIdentifier[] corpses)

Notifies this Ibis instance that another Ibis instance has died. Note: used by the nameserver, do not call from outside Ibis.

Parameters:

corpses - the Ibis identifiers of the Ibis instances that died.