This class supports exchanging data between entities via message passing. It can serve as an input port, an output port, or both. If it is an input port, then it contains some number of receivers, which are responsible for receiving data from remote entities. If it is an output port, then it can send data to remote receivers.
Its receivers are created by a director. It must therefore be contained by an actor that has a director. If it is not, then any attempt to read data or list the receivers will trigger an exception.
If this port is at the boundary of an composite actor, then it can have both inside and outside links, with corresponding inside and outside receivers if it opaque. The inside links are to relations inside the opaque composite actor, whereas the outside links are to relations outside. If it is not specified, then a link is an outside link.
The port has a width, which by default is constrained to be either zero or one. The width is the sum of the widths of the linked relations. A port with a width greater than one behaves as a bus interface, so if the width is w, then the port can simultaneously handle w distinct input or output channels of data.
In general, an input port might have more than one receiver for each channel. This occurs particularly for transparent input ports, which treat the receivers of the ports linked on the inside as its own. This might also occur for opaque ports in some derived classes. Each receiver in the group is sent the same data. Thus, an input port in general will have w distinct groups of receivers, and can receive w distinct channels.
By default, the maximum width of the port is one, so only one channel is handled. A port that allows a width greater than one is called a multiport. Calling setMultiport() with a true argument converts the port to a multiport.
The width of the port is not set directly. It is the sum of the widths of the relations that the port is linked to on the outside. The sum of the widths of the relations linked on the inside can be more or less than the width. If it is more, then the excess inside relations will be treated as if they are unconnected. If it is less, then the excess outside relations will be treated as if they are unconnected.
An IOPort can only link to instances of IORelation. Derived classes may further constrain links to a subclass of IORelation. To do this, they should override the protected methods _checkLink() and _checkLiberalLink() to throw an exception if their arguments are not of the appropriate type. Similarly, an IOPort can only be contained by a class derived from ComponentEntity and implementing the Actor interface. Subclasses may further constrain the containers by overriding the protected method _checkContainer().
@author Edward A. Lee, Jie Liu, Neil Smyth, Lukito Muliadi
@version $Id: IOPort.java,v 1.259.4.3 2008/03/25 23:11:08 cxh Exp $
@since Ptolemy II 0.2
@Pt.ProposedRating Green (eal)
@Pt.AcceptedRating Red (neuendor)