for_loop (nst man page)

NAME

for_loop -- unit to iterate operands

PROTOTYPE

unitptr for_loop( int nu, int nr, char *pcFmt, unitptr uHost)

ARGUMENTS

int nu: ABS(nu)=number of successor units to iterate. The sign of nu determines, whether the condition for premature termination ( CTL\_in[0]==0 ) is always checked before ( nu>0 ) or after ( nu<0 ) each iteration.
int nr: initial 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.
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[1]: break field: if during iteration of the for-unit this field changes (!) from zero to a positive value, the loop will terminate after completion of the current exec call of the current operand. If adaptation is specified too, all adaptations for the performed exec's will be carried out. Note that an initial positive value of the break field does not prevent the for loop from being started!

CTL_in[1]: control input: iteration count limit. Operation of the for_loop unit requires a non-zero value at this pin. When the value is equal or lower than the current iteration count (at X_out[0]), 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[0]: current iteration count

DESCRIPTION:

This unit is provided to perform repeated iterations of the following nu units in the exec-queue. These will become operands of the for_loop unit. This unit and its options is similar to the iterator unit. The main difference is the absence of any saving and feeding fields and the dynamically changeable number of iterations.

EXECUTION:

An exec call to the for_loop unit will have the effect to call the chain of its nu successors nr times in sequence. Before the i-th call is made, the for_loop checks whether its iteration count is equal or larger than CTL_in[0]. If yes, operation of the for_loop unit terminates prematurely. By specifying the %a option (``exec+adapt'' in NEO), the for-iterations will include adaptation steps according to the pattern


   for (i=0; i<ABS(nr); i++) {
       exec_unit(Operand_1) ... exec_unit(Operand_nu);
       adapt_unit(Operand_nu) ... adapt_unit(Operand_1);
   }

In this case, no further adaptation calls to the operands will be made during the adapt_unit() call for the for_loop.

ADAPTATION:

Usually, the for_loop unit does not adapt its operand units. Adaptation must be explicitly enabled by setting options. As explained above, the %a will provide adaptation during the exec_unit call for the for_loop unit. The following two options will enable adaptation for the operands of the for_loop unit when the adapt_unit call is made.

%A: (``adapt1'' in NEO) adapt_unit() acts as if


   for (i=0; i<ABS(nr); i++) {
       adapt_unit(Operand_nu) ... adapt_unit(Operand_1);
   }

%p: (``adapt2'' in NEO) modifies %A-option by prefixing each adapt_unit(operand) with a exec_unit(operand), ie. now adapt_unit() acts as if


   for (i=0; i<ABS(nr); i++) {
       exec_unit(Operand_nu); adapt_unit(uOperand_nu)
       ...
       exec_unit(Operand_1); adapt_unit(Operand_1)
   }

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. If neither of %A or %p is present, the adapt_unit() call is without any effect.

VIRTUAL MODE:

If the option string contains the token %v, the for_loop unit operates in a special mode, similar to a virtual_unit: it then uses as its operands the iOperands successor units of its host unit. This facilitates to build operator units that iterate their operands.

FILE

/homes/jontrup/nst5/man/../o.sol2//../nstsrc/nst_misc.c