spin is an experimental project and far from beeing available for commercial usage. If you are interrested in spin: mailto://spin@toem.de.

Introducing Spin 2 - Connectors

A port in spin is just a kind of connector. Connectors are elements that can be connected with the connectTo method. In spin there are no wiring elements like systemC signals. Instead connectors (e.g ports) are connected directly.

Adding Connectors

In the previous examples, connectors were created like this:

public IIn<Integer> in1;
public IOut<Integer> out;

But somebody who knows Java will immediately see that these lines do not create anything. In fact these lines just declare members of the surrounding class with the given name and type but do not create any objects. To declare a member AND create an object we usually need:

public IIn<Integer> in2 = new In<Integer>(null, this);

Nevertheless the line

public IIn<Integer> in1;

is fully ok in spin, as modules (derived from Module base class) fill all non-initialized connector members with instances.

A connector can either be declared with an interface or a class as base type:

public IIn<Integer> in1; // IIn is an interface
public IIn<Integer> in1; // In is a class implementing IIn interface

IIn is an interface, but In is a class implementing IIn interface (like Module class implementing IModule interface). In case of a class, the module instantiates the class with the module and the member name as parameter . In case of an interface, the module looks up the interface in the factory map of spin. For instrumentation purpose, the map can be modified.

public class InPlus<T> extends In<T>{

	public InPlus(String name, IModule module) {
		super(name, module);
	}

	@Override
	public T read() {
		log("I did it");
		return super.read();
	}
	
}

public static void main(String[] args) {
	Spin.setFactoryDefault(IIn.class,In.class);
	I2_Connectors modules = new I2_Connectors(); // toplevel module
	Spin.run();
}

Connecting connectors

Not much to say here:

module1.out.connectTo(module2.in1);
module1.out.connectTo(module2.in2);

To make it even more easy, the following form is also possible:

module1.out.connectTo(module2.in1,module2.in2);

Init connection

Usually in the initialize method of a process, connector or module, the driving connector (Out) shall init the connection, meaning that the initial value shall be set. If multiple connectors try to init or none, an error is thrown while starting up. Just in case of InOut, all ports need to be initialized with a value.

public void initialize() {
	out.init(0);
	sensitive(in1.changed(), in2.changed());
}

Connector basics

The connector base interface IConnector can be declared with two types:

Major or value type (T) The major type defines the type of the value object that is kept in a connection. The method val() returns this "current" value. This can be a simple type like Integer, Boolean or Logic, but also a fifo, an array or a list or any other complex object.
Minor or element type (E) The minor can be either identical with the major type in case of simple types, or the element type of a collection (e.g. fifo).

The connector zoo

Connectors that allow to be connected to other modules connectors are called ports. Ports are usually declared as public members.

Connectors

There are Ports, In Out and InOut conectors available similar to systemC. InOut are dedicated for ILogic derived types. These are Logic (0,1,Z,X), LInteger and LLong. Ports are meant to be used with a different major and minor type (e.g. Fifo) - similar to channels in systemC.

In
Interface / Implementation IIn / In
Types T==E:  extends Object
Usage Read access of current value
Notification Changed notification is received when other connector changes value

Out
Interface / Implementation IOut / Out
Types T==E:  extends Object
Usage Read, write and init access of current value
Notification Changed notification is sent to other connectors on write access

InOut
Interface / Implementation IInOut / InOut
Types T==E: extends ILogic
Usage Read, write and init access of current value
Notification Changed notification is sent to other connectors on write access, received when other connector changes value

Port
Interface / Implementation IPort / Port (abstract)
Types T: extends Object; E: extends Object
Usage Read access of current value
Notification Changed notification is received when other connector changes value

Primitive connectors

Major and minor type can only be interfaces or classes. To define connectors with primitive type, the default connectors need to be extended like this:

public class PrimByteIn extends In<byte[]> {

	public PrimByteIn(String name, IModule module) {
		super(name, module);
	}

	public byte pread() {
		return val()[0];
	}
}

Instead of byte[], it can be any other object holding a byte primitve. Primitive connectors provide a minor performance advantage. They should be just applied in special cases.

Define new connectors

To define a new complex connector, 3 steps have to be done:

1 Define the type interface

This interface is used for the connector itself but can also be (like in this example) used for the value type.

public interface IFifo<E> {
	boolean isEmpty();
	boolean isFull();
	boolean write(E e);
	E read();
}
2 Define the connector interface

This is a simple step. Define the connector with the new interface as major type, and as base interface for the connector itself.

public interface IFifoPort<T> extends IPort<IFifo<T>,T>, IFifo<T> {
	
}
3 Implement the connector interface

Now we need to implement the port. We derive from an existing port and implement all the new fifo methods by forwarding to the fifo value.

public class FifoPort<T extends IFifo<E>,E> extends AbstractInitConnector<T,E> implements IFifoPort<T,E>{
public FifoPort(String name, IModule module) { super(name, module); } @Override final public boolean isEmpty() { return connection.val().isEmpty(); } .... connection.notify(this, Occasion.modified); ....

When the value gets changed or modified, other connectors need to be notified. The notify method of the connection forwards this information to all other connectors.