fpp/docs/spec/Definitions/Component-Instance-Definitions.adoc

=== Component Instance Definitions

A *component instance definition* defines an instance
of a
<<Definitions_Component-Definitions,component>>
that you can refer to in a
<<Definitions_Topology-Definitions,topology definition>>.

==== Syntax

`instance`
<<Lexical-Elements_Identifiers,_identifier_>>
`:`
<<Scoping-of-Names_Qualified-Identifiers,_qual-ident_>>
`base` `id` <<Expressions,_expression_>>
_[_
`type` <<Expressions_String-Literals,_string-literal_>>
_]_
_[_
`at` <<Expressions_String-Literals,_string-literal_>>
_]_
_[_
`queue` `size` <<Expressions,_expression_>>
_]_
_[_
`stack` `size` <<Expressions,_expression_>>
_]_
_[_
`priority` <<Expressions,_expression_>>
_]_
_[_
`cpu` <<Expressions,_expression_>>
_]_
_[_
`{` _init-specifier-sequence_ `}`
_]_

_init-specifier-sequence_ is an
<<Element-Sequences,element sequence>> in
which each element is an
<<Specifiers_Init-Specifiers,init specifier>>,
and the terminating punctuation is a semicolon.

==== Semantics

. The identifier names the component instance.

. The qualified identifier must
<<Scoping-of-Names_Resolution-of-Qualified-Identifiers,refer to>>
a
<<Definitions_Component-Definitions,component definition _D_>>.
This component definition _D_ is called the component definition
*associated with* the component instance _I_.
We also say that _I_ is an instance of _D_.

. The expression following the keywords `base` `id` must have a
<<Types_Internal-Types_Numeric-Types,numeric type>>.
It associates a base identifier with the component instance.

.. The base identifier must evaluate to a nonnegative integer after
<<Type-Checking_Type-Conversion,type conversion>>.

.. For each component instance, for each
command, event, telemetry, or parameter identifier,
the identifier associated with the component instance
is computed by adding the base identifier specified here to the relative
identifier specified in the component.
For this purpose, command opcodes are identifiers.

.. For each component instance, this procedure creates a range of identifiers,
from the base identifier to the largest identifier associated
with the component instance.
If the component has no identifiers, then this range is empty.

.. No component instance may have a base identifier that lies within
the identifier range of another component instance.

. If present, the string literal following the keyword `type`
names the implementation type of the component instance.
The type must be a valid type in the target language (e.g., a type name
in {cpp}).
If the implementation type is not present, then the code generator
infers the name of the implementation type from the component name when
generating the constructor for the component instance.
For example:

.. Suppose an FPP model has a component `C` defined in module `M`.
Suppose _I_ is a component instance of component `M.C`.
By default, the implementation type associated with _I_ is `M::C`.

.. Specifying `type "M::D"` causes FPP to generate a
constructor for _I_ with name `"M::D"` instead of `"M::C"`.

+
Specifying an implementation type is useful in cases where the name
of the component implementation does not match the component
name, e.g., because there are several implementations of the
same FPP component.

. If present, the string literal following the keyword `at`
must specify a file path, relative to the
<<Translation-Units-and-Models_Locations,location>>
of the component instance definition.
The file path must name a file in the target language (e.g., a {cpp}
header file)
that provides the implementation associated with the instance.
If no such path is given, then the translator uses the location
of the component instance and the name of the component to generate
a default implementation path.

. If present, the expression following the keywords `queue` `size` must
have a <<Types_Internal-Types_Numeric-Types,numeric type>>
and must evaluate to a nonnegative integer after
<<Type-Checking_Type-Conversion,type conversion>>.
It specifies the queue size for active and queued components.
The queue size is required for active and queued components
and is not allowed for passive components.

. If present, the expression following the keywords `stack` `size` must
have a <<Types_Internal-Types_Numeric-Types,numeric type>>
and must evaluate to a nonnegative integer after
<<Type-Checking_Type-Conversion,type conversion>>.
It specifies the stack size in bytes for active components.
The stack size is optional for active components and is not allowed
for queued or passive components.

. If present, the expression following the keyword `priority` must
have a <<Types_Internal-Types_Numeric-Types,numeric type>>.
It specifies the thread priority for active components.
The priority is optional for active components and is not allowed
for queued or passive components.

. If present, the expression following the keyword `cpu` must
have a <<Types_Internal-Types_Numeric-Types,numeric type>>.
It specifies the CPU affinity for active components.
The CPU affinity is optional for active components and is not allowed
for queued or passive components.

. If present, the init specifiers govern {cpp} code generation for
the component instance being defined.
See the section on
<<Specifiers_Init-Specifiers,init specifiers>>
for further information.

==== Examples

[source,fpp]
----
instance commandDispatcher: Svc.CommandDispatcher \
  base id 0x100 \
  queue size 10 \
  stack size 4096 \
  priority 30 \
  cpu 0
----

This example defines a component instance `commandDispatcher`
of component `Svc.CommandDispatcher`.
It specifies the base identifier, queue size, stack size,
priority, and CPU.

[source,fpp]
----
instance timer: Svc.Timer at "../../Timers/HardwareTimer.hpp"
----

This example defines a component instance `timer` of component `Svc.Timer`.
It specifies that the component implementation is located at
path `../../Timers/HardwareTimer.hpp` instead of in the default location for the
component.
The path is resolved relative to the location of the component instance definition.