NAME
use_method -- fast invocation of named unit
PROTOTYPE
unitptr use_method( char *pcName, int iNumInp, char **ppcInp, int iNumOut, char **ppcOut, char *pcOptions, unitptr uHost)
ARGUMENTS
- 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//../nstsrc/nst_method.c