NAME
use_named_unit -- call existing unit by name
PROTOTYPE
unitptr use_named_unit( char *pcName, int* piIDesc, int* piIRefs, int *piODesc, int* piORefs, unitptr uHost)
ARGUMENTS
- char *pcName
- name of unit to be called
- int* piIDesc
- nr of mirrored input fields and their dimensions
- int* piIRefs
- field numbers of mirrored input fields of referenced operand [array entries 1..\#InputFields, 0-entry not used]
- int *piODesc
- nr of mirrored output fields and their dimensions
- int* piORefs
- field numbers of mirrored output fields of referenced operand [array entries 1..\#OutputFields, 0-entry not used]
- unitptr uHost
- host unit
RETURN VALUE:
A pointer to the created unit or NULL in the case of an error.
INTERFACE OF CREATED UNIT:
A subset of the inputs and outputs of the unit that is referenced
by the name pcName. For details, see MIRRORING FIELDS below.
DESCRIPTION:
The named_unit provides a mechanism to use another unit
(referred to as the referent of the named_unit ) in place of
the named_unit's position within a circuit. This is similar
to the virtual_unit. For a comparison, see USAGE
SELECTION OF A REFERENT UNIT:
To make an existing unit u available as a referent of a named_unit v,
u must have been given a string name with the name_unit() routine
(in Neo this can be done interactively with the Name command).
Thereafter, u can be referenced by this name from any named_unit
that is a (not necessarily direct) subunit of u's host unit.
EXECUTION AND ADAPTATION:
Whenever
the named_unit is executed or adapted this operation will
be carried out for its referent (even though it is located
somewhere else). The same referent can be referenced by several
named_units from different places. This provides a mechanism
to use the same unit in different places. The referent is selected
dynamically during each exec_unit or adapt_unit -call of the
named_unit, therefore, if a name that is used by a named_unit
has been re-used for a different unit, this new unit will be
referenced when the named_unit is executed.
MIRRORING FIELDS:
The named_unit can `mirror'' some (or all) of the input and/or
output fields of its referent. That means, that the named_unit
will inherit some of the fields of its referent. When the named_unit
is executed or adapted, data at the mirrored input fields will be
transported to the corresponding input fields of its referent unit,
then the referent unit will be adapted or executed, and any results
at the referent's output fields will be transported back to any corresponding
`mirrorred'' output fields of the named_unit. Thus, by
mirroring the required input/output fields, an
named_unit can invoke the data transformation effected
by the execution or adaptation of its referent unit at any location
within a circuit.
USAGE OF THE NAMED UNIT:
The named_unit and the virtual_unit share the feature of
allowing the execution of another unit that exists in
a different location. However, both units serve a different
purpose:
(1) a virtual_unit makes its direct host unit into an
operator and its referenced unit into an operand of this
operator. Therefore, the referenced operand becomes "invisible"
for normal exec_unit or adapt_unit calls.
In contrast, the referenced unit of a named_unit remains
a normal unit and its behavior under exec_unit or adapt_unit
calls is not changed. Likewise, the host unit of a named_unit
does not become an operator.
(2) A named_unit references its referent unit by a string
name and allows more freedom for the location of its
referenced unit. The referenced unit may be located in any
of the nested hierarchy of units that enclose the
considered named_unit.
In contrast, a virtual_unit requires its referenced unit
to be a successor unit of its direct host unit. The referenced
unit is specified by its successor position relative to
the virtual_unit's host unit.
(3) A named_unit requires that its referent has been given
a name with the name_unit routine. A virtual_unit
has no such requirement.
The bottom line of this is that the named_unit should be
preferred when the purpose is just to share an existing unit
in several different places, and that the virtual_unit
should be used when it is desired to make a composite unit
that has the property of being an operator that dynamically
binds to its successor unit(s).
EXAMPLE:
uCallByName = named\_unit("foo",[2,5,-10],[0,2,1],[1,3],[0,0],uHost);
...
name\_unit("foo",uMyunit);
will create a unit uCallByName that references the unit uMyunit
that is named foo. Note that the naming itself need not occur before
the creation of a named_unit that uses the name. It only must have been
done before the first exec_unit or adapt_unit call of any such
named_unit.
In the example above, the created named_unit will have 2 input fields
of dimensions 5 and -10 that will `mirror''
the two input fields with field numbers 2 and 1 of uMyunit
(assuming that uMyunit has these fields and that the dimensions
match. However, these conditions need only be satisfied later at
run-time, not when the named_unit is created). Further, the created
named_unit will have one output field with 3 pins, mirroring
output field 0 of uMyunit.
LOAD SAVE CONTROL:
The named_unit is invisible to the load_unit, save_unit
and ctrl_unit calls, i.e., no file entries are produced or read,
and no control calls are sent to the referenced operand.
An exception are control calls issued by a ctrl_op unit: these
are passed to the referenced unit, even if the reference proceeds
via one or several named_units [this is the same convention as
used by a virtual_unit].
[the non-effect of the control calls may be changed in later versions].
SEE ALSO:
virtual_unit, neo
FILE
/local/homes/rhaschke/nst7/man/../o.linx86_64//../nstsrc/nst_stdr.c