NAME

use_method -- fast invocation of named unit

PROTOTYPE

unitptr use_method( const char *pcName, int iNumInp, char **ppcInp, int iNumOut, char **ppcOut, char *pcOptions, unitptr uHost)

ARGUMENTS

const char *pcName
name of referenced method. Any '|' chars indicate formatting but are ignored for the name
int iNumInp
optional interface specification: nr of input fields
char **ppcInp
input field descriptors
int iNumOut
optional interface specification: nr of output fields
char **ppcOut
output field descriptors
char *pcOptions
option string to set output policy (cf. OPTIONS below)
unitptr uHost
host unit

RETURN VALUE:

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

SYNOPSIS:

Allows to act as a `proxy'' instance to execute, adapt or control a named NST unit (the `referenced unit'') that may be located elsewhere in a circuit. The interface of the referenced unit is automatically inherited by the referencing method unit. Data transfer of output values can be chosen to be by reference, by redirection or by copy (the otherwise similar use_named unit is restricted to copy mode only, which is slower than the other two modes). Note that the three transfer modes differ in their semantics, e.g., with respect to side-effects.

INTERFACE OF CREATED UNIT:

If the referenced method exists at creation time of this unit, its interface will be inherited; otherwise, the unit will use the interface specification of its argument list. If none is specified ( ppcInp==NULL or ppcOut==NULL), the unit will be made with 0 input and 0 output fields. EXECUTION, ADAPTATION OR CTRL OF CREATED UNIT: If the use_method unit references a unit uRef and the reference is up-to-date (see below), execution (adaptation,ctrl) of the use_method unit will execute (adapt,ctrl) the referenced unit uRef, but with the inputs taken from the use_method unit. After execution (adaptation,ctrl) is completed, the computed output values will appear at the outputs of both uRef and the present unit. They will additionally appear at the outputs of any other use_method unit that references the same uRef and whose reference are up-to-date. Neither the input values of the referenced unit nor those of any method unit other than the executed (adapted,ctrl'd) method unit will have become changed as a result of the exec_unit ( adapt_unit,ctrl_unit) call. If the reference of the executed (adapted,ctrl'd) use_method unit is not up-to-date, the only effect of the exec_unit ( adapt_unit, ctrl_unit) call will be a corresponding warning message. A reference is up-to-date, if NST can find the referenced unit by the specified path name pcName and adjust the interface of the referencing use_method unit to the same structure as the interface of the referenced unit. Usually, NST tries to keep all references up-to-date, but it may happen that the necessary dimension adjustment to fields of a method unit cannot be done because of attached wires. In this case, the reference can become outdated. To bring the reference again up-to-date disconnect the unit from its attached units and remake it.

LOAD AND SAVE OPERATIONS:

These are not passed on, for similar reasons as with the use_named unit.

NAMING SYNTAX:

Follows the same rules as for the use_named unit. I.e., if pcName=this:that, the referenced unit must have name that and must be in a named container with name this. The referencing use_method unit must be located at the same level as this container, or deeper.

DATA TRANSFER POLICY:

Inputs:

Currently, the input policy cannot be set by the user. If the referenced unit has no subunits, access will be by reference, otherwise by temporarily swapping the input interfaces of both units. In both cases, the input values of the referenced method unit will appear unchanged after the call.

Outputs:

The default policy is BY_REFERENCE, i.e., the outputs of the use_method_unit behave as if they were connected to the corresponding outputs of the referenced unit. This is the fastest mode, but if there are several references to the same method subunit, they will affect each other by side-effects. In this case, it may be necessary to request in the option string the use of the BY_REDIRECTION or BY_COPY policy which allow the use_method unit to hold a private instance of the result

data of the invocation of its referenced method subunit:

%o:
sets transfer policy for output values to BY_REDIRECTION. This means that for the time of its invocation, the referenced method subunit is made to write its output values directly into the output interface of the referencing use_method unit This avoids the danger of side effects associated with the faster BY_REFERENCE policy (which is the default). Note that due to the output redirection, the outputs of the referenced method unit will not become changed. This may cause problems with method units that use their output pins as part of their state memory. In this case, one can resort to the (somewhat slower) policy BY_COPY below.
%O:
sets transfer policy for output values to BY_COPY. This means that the method subunit writes its results into its own output interface and then these values are copied into the output interface of the referencing use_method unit This mode is the safest, but also the slowest.

SIMILARITIES AND DIFFERENCES TO THE USE_NAMED UNIT:

There are two main differences with the use_named unit: (i) the use_method unit needs no interface specification; it always tries to follow the interface of the currently referenced unit, unless attached wires prevent this. When the referenced unit is deleted, renamed or moved out of scope of its referencing use_method unit, the use_method unit will keep its last interface. (ii) the use_named unit uses copy operations to first transfer its inputs into the input pins of the referenced unit (thereby changing their values), then it will execute (adapt, ctrl) the referenced unit, and finally it will copy back the result values. In contrast, the use_method unit is more flexible and -- when using its default policy BY_REFERENCE -- just passes the address of its input values to the referenced unit before its execution (adaptation, ctrl). In this case, all use_method units reference with their outputs directly the same memory locations that are also used by the referenced unit. This makes their outputs always stay `in sync'' and immediately reflect any change at the outputs of the referenced unit. As a result, the use_method unit can (i) operate much more efficiently as the use_named unit and (ii) never changes the input values of its referenced unit. NOTE: if an output field of a use_method unit is connected to an input field of a different type, the necessary type conversions will be carried out only when the use_method unit is actually executed, i.e., for these fields immediate synchronization will only be guaranteed for readers of the same data type.

EXAMPLES:

STATUS:

Preliminary.

SEE ALSO:

use_named

FILE

/local/homes/rhaschke/nst7/man/../o.linx86_64//../nstsrc/nst_method.c