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