NAME

iterator -- unit to iterate operands

PROTOTYPE

unitptr iterator( int nu, int nr, int nf, int ns, char *pcFmt, unitptr uHost)

ARGUMENTS

int nu
ABS(nu)=nr of successor units to iterate. The sign of nr determines, whether the condition for premature termination ( CTL\_in[0]==0 ) is always checked before ( nr>0 ) or after ( nr<0 ) each iteration.
int nr
nr (>=0) of iterations to be made. A value of 0 specifies an infinite loop that can only be broken if one of the units in the loop sets the CTL\_in field to zero.
int nf
nr of feeding fields for input
int ns
nr of saving fields for output
char *pcFmt
option string (see below)
unitptr uHost
host unit

RETURN VALUE:

A pointer to the created unit or NULL in the case of an error.

INTERFACE OF CREATED UNIT:

X_in[ns]
saving input. At the end of iteration step i, the value at pin j of this field will be copied into pin i of output field j.
in_1[nr]
first feeding input field. Before iteration i is started, the value at pin i of this field will be copied into pin 0 of feeding output field X_out[nf].
...
...
in_nf[nr]
last feeding input field. Before iteration i is started, the value at pin i of this field will be copied into pin nf-1 of feeding output field X_out[nf]. If needed by any attached operands, any necessary conversion operations are carried out for this field before each iteration starts.
CTL_in[1]
control input. Operation of the iterator unit requires a non-zero value at this pin. When the value is zero, operation of this unit terminates after completion of the current iteration. If the value is zero at the beginning, the unit does nothing (except for some internal bookkeeping, such as marking its operands).
X_out[nf]
feeding output. Before iteration i, this field will be initialized to a time slice of the nf feeding input fields. If needed by any attached operands, any necessary conversion operations are carried out for this field before each iteration starts. If nf=0, this field will have a single pin and hold the current iteration count. If nf=0 and option %v is given, this field will instead have nr pins, with pin i set to value one each others to zero at iteration i.
out_1[nr]
first saving output field. After iteration i, the value of pin 0 at saving input field X_in[ns] will be copied into the i-th pin of this field.
...
...
out_ns[nr]
last saving output field. After iteration i, the value of pin ns-1 at saving input field X_in[ns] will be copied into the i-th pin of this field.
out_ns+1[0]
(only present when nf!=0 or nf=0 and no %v-option is given) current iteration count i.

DESCRIPTION:

This unit is provided to perform nr iterations of the following nr units in the exec-queue. These will become operands of the iterator unit. This unit and its options is similar to the for_loop unit. The main difference is the availability of the saving and feeding fields, which impose the restriction of a fixed number of iterations. The iterator has its control field at position 0, and a counter output field at out_0 of one pin. The iterator has always at least two input and one output field(s). If ni!=0, the iterator will have ni input fields at field positions 1..abs(ni) of dimension ni, and the same number of output fields at corresponding field positions, each with a single pin. If no>0, the iterator will have in addition no input fields at field positions abs(ni)+1..abs(ni)+abs(no) of one pin, and the same number of corresponding output fields of dimension ni.

There are the following modes:

%a
after each exec-iteration (i.e., one exec_unit call for each operand), issue an immediate adapt-iteration (i.e., one adapt_unit call for each operand, in reverse order). The adapt_unit-call of the iterator unit will be without effect when this option is set.
%A
exec_unit just iterates exec steps, adapt_unit separately just iterates adaptation steps.
%p
modifies %A-option: each iterated adaptation step becomes prefixed by an exec_unit call (no effect, if specified without an %A).
%o
once-mode, i.e., iterate operands only during the first call of the iterator unit. All subsequent calls execute each operand only once, i.e., the iterator is then ignored. A NST_RESET, NST_INIT or NST_I_USER refreshes the effect of the o-option.
If none of these letters is given, any adaptation is disabled. An exec call to the iterator unit will have the effect to call the chain of its iNum successors nr times in sequence. Before the i-th call is made, the iterator checks whether its control input is zero. If it is zero, operation of the iterator unit terminates (this allows to have the effect of a break command in a loop). Otherwise, it takes the values at pin i of each of the ni input fields 1..ni and copies them to its outputs 1..ni. This makes the i-th timeslice of the input fields available to the iterated units. When the i-th iteration is finished, the iterator copies the no values at its no input fields ni+1..ni+no to the i-th pin at the respective output fields ni+1..ni+no. This allows to save results from the i-th iteration step at the i-th pin position in these output fields.

ADAPTATION:

The treatment of an adapt-call depends on the chosen mode (see above). If the iterated units contain an adaptable unit, each adapt should usually be prefixed by an exec-call, i.e., the %p - mode should be used.

SEE ALSO:

for_loop, one_op

FILE

/homes/jontrup/nst5/man/../o.sol2//../foldersrc/nst_util.c