Description
Distributors (DBXs) are a frequently used CDL object and can be thought of as broadcasting each consumed event, to each connected consumer. The consumed event could be an atomic or compound event and remains open until the last consumer has indicated completion by closing. This provides CDL with an equivalent of automatic data and enables compose-able thread-safe communication by reference.
Creation Attributes
Name
Instance name (see Object Names)
Dimensions
Instance dimensionality (see Object Dimensionality)
Presence
Instance presence flag (see Object Presence)
Reentrancy
Instance reentrancy (see Object Reentrancy)
Visibility
Instance visibility flag (see Object Visibility)
Connection Attributes
Event propagator objects have two types of connection. Those that provide events to their consuming faces, and those that consume events from their providing faces. The attributes associated with any particular connection therefore depend on the providing and consuming object types (see Automatic Connections).
All automatic connections require;
Timeout
This attribute determines whether the connection will poll or block (see Connection Timeout).
Signature
This attribute is a string that describes the mapping from elements in the consumer, to elements in the provider. See Connection Mappings.
Dimensions
This attribute determines the dimensionality of the connection array owned by each consuming element. By default, this will provide the consuming element with one connection for each provider element. Collector, Multiplexor and Manual connection consumers can have multi-dimensional connection arrays, but in all other cases, this attribute will be '1'. See Connection Mappings.
Repeat Count
This attribute determines the number of times that each 'provider element to consumer element' connection is repeated. If the repeat count is greater then one, then the Dimensions attribute (above), and the resulting connection access functions, will both have an 'extra' dimension. Only Collector, Multiplexor and Manual connection consumers can have repeat counts that are greater than '1'. See Connection Mappings.
Name
This attribute determines the connection's 'name' which is used to construct access function names (see Connection Names).
There are no specific attributes required for connections that provide events to a distributor's consuming face.
Manual Connections
Manual connections provide a means of directly accessing target objects. These are created automatically from CDL diagrams and accessed using their access function names (see Manual Connections).
Distributor connections provide the following member functions;
WaitEvent()
This member function issues an 'open' request to the distributor (see DBX WaitEvent function).
Close()
This member function closes a previously opened distributor (see DBX Close function).
Automatic and Manual Connections
The following member functions can be used to retrieve information from both automatic and manual connections;
IsOpen()
This member function returns TRUE if the connection is 'Open' or FALSE otherwise.
EventNum()
This member function returns the retrieved event's sequence number. Numbering starts from zero (the first retrieved event).
LinkNum()
This member function returns the consuming connection's link number.
Notes
Each time a new connection is made to a distributor, output is shared. If the logic requires that a given distributor output is to be 'competed for', then a competer object should connected to the distributor and the competing consumers connected to the competer object.
Distributors that have reentrancy greater than 1 will allow their more-zealous consumers to run-ahead of their less-zealous consumers. This is particularly useful when a real time system provides data to a mixture of timely and untimely consumers. For example, it could be that a given data stream is sent to a GUI for screen update, and also sent to a mass storage device to be logged. Typically, the screen update will need to be timely, whilst the storage device will probably experience transient delays when flushing caches. Distributor reentrancy can therefore be used to ensure that the stricter timeliness requirements of one stream are not compromised by the less deterministic execution of adjacent sharing consumers.
Example
In the example above, a transient store event stream is distributed to a data logger, and display call-back. In practice, the logger device is likely to use a cache mechanism and will therefore experience transient loads. The display call-back on the other hand will execute in the GUI thread and is therefore required to execute in a far more timely manner (to avoid 'jitter'). In order for the display to update in a timely manner, it needs to be de-coupled from the logger, and the distributor's reentrancy determines the permissible event advance/lag that the two consuming chains can experience without affecting the other. The larger the reentrancy, the less coupled the chains are, but the more buffers that the store needs to provide, and hence the larger the memory requirement.