C API (Component Interface)
The component information structure holds information about the component, as opposed to information about the module (cf.
ModuleInfo). This structure is returned to the framework by the module during EVENT_MODULE_CREATE.
Each pointer in the structure should be set to point to a persistent value (e.g. a module-level constant), since they may be accessed at any time in the future by the framework, not just immediately following the event call. All fields must be set, except where specified below.
- const char* cls
- The component class name.
- The component type.
- const struct
- The component version.
- See below.
- const char* additional
- Additional info, in the form
"key=val\nkey=val\n...". Human-readable information goes here, but this may be used to provide additional information to the framework in future releases.
- const char* libraries
- External libraries in the form
"name=version\nname=version\n...". Used to tag libraries loaded by the component outside of the SystemML infrastructure (not recommended, but may be unavoidable under some circumstances). See the 1258 bindings for an example.
- If set, the Engine will fire EVENT_INIT_CONNECT on the component only once, and on that call all its inputs will be available. Setting this flag indicates that the process needs to see all of its inputs before it can create any outputs. If set, the framework will not bother calling EVENT_INIT_CONNECT on the process until all of its inputs are available. By extension, that will be the only call to EVENT_INIT_CONNECT for that process and both
F_LAST_CALL will be set. This simplifies the flow logic of servicing EVENT_INIT_CONNECT. However, the process should not set this flag unless it really does need all its inputs to initialise, because doing so will lead to Deadlock in situations where it was not logically necessary.
- If set, the Engine will not allow an input to be passed to the process that does not match its sample rate.
- If set, the Engine will not allow the process to create an output that does not match its sample rate.
- Union of F_INPUTS_SAME_RATE and F_OUTPUTS_SAME_RATE. If both these flags are set, then all inputs and outputs must have the same sample rate as the process. In this case, all inputs and outputs will be Due on every call to EVENT_RUN_SERVICE, simplifying code flow.
Module information is that that is common to all components a module can instantiate, as opposed to component information which is that that is specific to a component. Native modules can only instantiate a single component, so component information and module information are on the same level, but non-native modules (language bindings) can create multiple components.
In addition, ComponentInfo can be obtained by a peer Component, provided it has a handle to the component. Therefore, it must include all information that may be of interest to the peer. For instance,
type may always be module-level information from an implementational perspective (we shall see), but it may be useful information to the peer, so it belongs here in any case.