NAME
array_of - make array of units
PROTOTYPE
unitptr array_of( int iNumDim, int *piDim, unitptr *puArray, unitptr uHost)
ARGUMENTS
- int iNumDim
- nr of array dimensions
- int *piDim
- limits for the iNumDim array dimensions
- unitptr *puArray
- initializer array for array els
- unitptr uHost
- host unit
INTERFACE OF CREATED UNIT:
If pcOpt=NULL:
- X_in[iNumDim]:
- (input field 0) for each array dimension an index value.
- CTL_in[1]:
- (control field) a value of 0 switches the unit off.
DESCRIPTION OF CREATED UNIT:
Provide an array of units of the same type and interface as its successor
unit. The successor unit serves as a `moveable window'' into the
array: after each execution of the array_of unit, the operand
unit assumes the identity of one of the array elements. The array element
is selected by providing an index vector at input field X_in
of the array_of - unit.
The operand of an array_of unit may not be an operator
(however, it may be a virtual_unit, see below).
The array from which the array_of unit dynamically selects
an element (``mapping'' it onto its operand) can be specified
via argument parameter puArray.
To this end, puArray should specify a sufficient number of
pointers to NST-units that are all of the same type
and interface as the unit that is the operand of the array_of unit.
However, the array elements may not be any operators.
The array is assumed to have iNumDim dimensions.
The iNumDim index limits of the array must be specified in
piDim[0..iNumDim-1] when the unit is created.
The units themselves need not
exist already at creation time of the array_unit, however,
they must be created (and the addresses of their
unitptr's must be written into puArray)
as subunits of the array_of-unit
BEFORE the array_of unit is first accessed
with an exec_unit, ctrl_unit, load_unit or save_unit
call.
NOTE: to enforce that the created array unit takes notice
of the values in puArray, a ctrl_unit(NST_UPDATE_ARRAY,u)
call can be issued. The successor unit of the array_of unit
will be associated with the array index that was valid at
the input of the array_of unit when this call
was made. After this, the array puArray need not
be any longer maintained.
In NST, the operand unit of an array_of - unit
may not be changed after the array_of - unit was used
(executed, controlled, loaded, saved).
USE OF THE ARRAY_OF UNIT IN NEO:
In Neo, the array argument puArray is not used.
Instead, the array elements neither need to be specified
explicitly (.Neo simply makes the required nr of copies
of the operand unit) nor is the above restriction present.
Whenever the array_of unit is used and its operand has
changed, it will remove its non-selected array elements and make
a set of new ones (only the currently selected array element
will not be removed; it survives in the previous operand
of the array_of unit onto which it is still mapped).
A unit that ceases to be operand of
an array_of - unit (e.g., because the array_of unit
is moved away or deleted) keeps its identity as the array
element that was most recently selected by the array_of
unit. A unit that newly becomes operand of an array_of
unit (e.g., because the array_of unit is moved in front
of it) is used as the array element with the index value
at X_in of the array_of unit when the array_of unit
is used for the first time after the change. At this
time, also the remaining
array elements are created by making copies of the operand
unit.
ARRAY OF A VIRTUAL UNIT:
If the operand is a virtual_unit, the array_of unit uses
as its `true operand'' the unit that is referenced by
the virtual_unit, not the virtual_unit itself.
In particular, the array elements are made from the
`true'' operand unit, not from the
virtual_unit (which would make little sense, since all
copies of the virtual_unit would reference only the same
NST-unit). Likewise, all mapping operations (including the mappings
that occur when the array_of unit is created, requeued
or removed) then refer to the unit that is referenced
by the virtual_unit.
IMPORTANT NOTE: the translation of an array_of
unit followed by a virtual_unit into NST source code
does not maintain Neo's dynamic referencing mechanism:
to make the array elements, the code generator inserts a
for - loop with a copy of the creation call that is generated
(subsequently) for the
NST unit referenced by the virtual_unit. Thus, to make later code
changes to the creation call of this referenced unit
(including any code modifications
that change the relative position of this referenced unit and the
container of its referencing virtual_unit) also take effect
for the array elements of its associated array_of unit requires
that corresponding changes are also made in the aforementioned
for - loop also [comments of this are are inserted
in appropriate locations of the generated code].
LOADING/SAVING:
Saving an array_of unit saves all the units of the associated
array.
Loading an array_of unit loads the data of the previously
saved array element units into the current array element
units. This requires that all elements of the array_of unit
have been instantiated before and are of the same type
and interface as was the case for the saved array_of unit.
CONTROL:
Any control call is sent to all non-selected array elements.
The additional control mode NST_UPDATE_ARRAY
enforces making/updating of the array elements according
to the current operand (in Neo) or the current values
in puArray (in NST). In both cases, the current operand
(=successor unit) of the array unit will be associated
with the index input that was present at the time of this
call (this applies even if in NST this operand come only
later).
FILE
/local/homes/rhaschke/nst7/man/../o.linx86//../nstsrc/nst_array.c