Description
Connection prototypes are similar to function prototypes but whereas the latter ensure that functions are called with legitimate arguments and return legitimate 'types', connection prototypes ensure that circuitry is legitimately connected. In both cases however, they ensure that functions are correctly invoked.
Function prototypes usually specify a list of arguments, together with their respective data types and their argument passing conventions (by value, reference, pointer etc). They also typically specify the function's return type. Connection prototypes on the other hand, specify the structure of event trees that are subscribed-to, and published. They also define the 'types' of data in the tree, as well as dictating connector/connectee relationships.
In the diagram above the circuit has two connection prototypes; the subscription prototype constrains the event trees that the circuit can subscribe to (its input), and the publication prototype declares the event tree structure of its published events (output). In this example the circuit has one subscription prototype and one publication prototype but in the general case it could have any number of each. This is analogous to C++ classes which can have any number of member function entry points.
This section discusses circuit connection prototypes (as opposed to method or call-back function prototypes).
Publication and Subscription
It is important at this point to differentiate between event flow and data flow. A circuit could publish a store 'ready-for-read' event that allows a subscriber to read its data, but it could also publish a store 'ready-for-write' event that allowed a subscriber to write to one of the publisher's internal stores. Events flow from providers to consumers, but this is independent of the data flow direction (read/write). It is also important to distinguish subscriber/publisher from connector/connectee. The connector is the circuit that instigates the connection, and could be either a publisher, or a subscriber.
Publication points 'provide' events, whilst subscription points 'consume events'. Publication prototypes appear inside the circuit, and subscription prototypes appear outside the circuit (see example above). When two circuits are connected, the publisher is the circuit that owns the publication prototype.
Connections between circuits must comprise one publisher and one subscriber; and the two prototypes must be consistent. Circuit pairs can however have multiple connections, and it is legal for circuit A to publish to circuit B with one connection, and circuit B to publish to circuit A with another.
If circuit A connects to circuit B, and circuit B also connects to circuit A, then A and B are referred to as 'peers'. Peer to peer connections are not allowed in the top-level container circuit.
Creating a Prototype
Connection prototypes are required for each circuit connection point. These points are created by adding Consumer or Provider pins to the edge of the circuit definition and connecting Reference connections to the associated objects. The pins are effectively extensions of the connection face for the object they are connected to, and hence a provider pin is required for a provider face and a consumer pin for a consumer face. The arrow inside the pin determines the direction of the event flow; inward implies subscription to an event, whilst outward implies publication of an event.
Example 1
The example above shows a simple circuit definition that contains a single store which the 'Service' method writes to. Two circuit connection points are shown; one connected to the matrix store and the other to the method. The 'Subscribe' connection point needs to be connected to a circuit that will deliver events for the 'Service' method to process, and the 'Publish' connection point can be 'connected-to' by a circuit that will read output from the 'Matrix' store. The publication prototype below will allow subscribers to read data from the circuit's 'Matrix' store.
The prototype is associated with its definition because they share the '{MatrixT}' type. The 'Publish' prototype is associated with the 'Publish' connection point by virtue of the fact that they share a label (in this case 'Publish'. The 'read' arrow on the prototype's store connection means that the subscriber must connect for read access only. The store's data type will be {MatrixT}. The store is shown with a gray background because it is public, and this means that the subscribing circuit is responsible for making the connection. Although it is less common, objects can appear in publication prototypes with white backgrounds, indicating that the publisher is responsible for making the connection. Finally, the prototype's connection pin is pointing outward because the circuit's store is 'providing' rather than 'consuming' events.
The subscription prototype below declares that the circuit must subscribe to a transient store that has data type {VectorT}, for read access. The name of the publishing store, and its connection point label are both irrelevant, and the only thing that matters is that instances of the {MatrixC} circuit definition subscribe to connection points that provide readable transient store events with data type {VectorT}.
Note that the Publish and Subscribe prototypes are shown separately above for convenience only; the final complete prototype is shown below;
Example 2
This second example illustrates how 'transparent' objects can be used to allow us to change the {MatrixC} circuit above without changing its prototype; and therefore preserve backward compatibility. The circuit below shows the new {MatrixC} circuit which has been modified in several ways. Firstly, a distributor has been inserted in between the 'Matrix' store and the 'Publish' connection point; and secondly, a method has been added that monitors the Matrix store's output stream but in this example, doesn't generate any output events. The store has become private because the distributor is now the actual connection point. The distributor is both public and transparent (see Object Scope and Object Visibility).
The new circuit will have a different prototype due to the addition of the distributor but because the distributor is transparent it is not seen by any consumer and so in most cases, as far as the consumer is concerned, the prototype is the same. The exception is when it is being directly consumed through a manual connection, in which case the type of the connectee is important. It is due to this exceptional case of connecting through a manual connection that the object being connected to must appear in the prototype even when transparent. All other transparent objects in the connection tree need not be published at all.
Inserting the transparent distributor also causes the appearance of any {MatrixC} circuit instances to change slightly so that the provider connection point will now appear with a distributor icon, instead of a transient store icon. The new instance is shown below. Note that the subscription point is unchanged and its icon is still a 'collector'. The icon is a collector because the 'Subscribe' connection point connects to a compound method (in this case the 'Service' method) and compound methods actually insert a 'secret' collector.
Blueprint will detect this change and highlight all existing instances of the {MatrixC} circuit. If the user 'confirms' the change then the circuits will be automatically updated. Following an update like this, existing connections may be dropped where there is no mapping to the new connection and a new connection must be created manually.