File

In this tutorial the very same stream as in Simple is constructed. However, this time it is deserialized from an XML file instead of manually assembled by runtime library functions. The XML file which encodes this stream looks as follows:

<?xml version="1.0" encoding="UTF-8" ?>

<Stromx version="0.1.0">
    <Stream>
        <Operator id="0" package="runtime" type="Counter" version="0.1.0"/>
        <Operator id="1" package="runtime" type="PeriodicDelay" version="0.1.0">
            <Parameter id="2">
                <Data type="UInt32" package="runtime" version="0.1.0">1000</Data>
            </Parameter>
            <Input id="0" operator="0" output="0"/>
        </Operator>
        <Thread>
            <InputConnector operator="1" input="0"/>
        </Thread> 
    </Stream>
</Stromx>

A stream is described as a list of all its operators and its threads. Each operator must be assigned a unique ID which is used to refer to the same operator when defining connections between operators and when assiging operator connectors to threads. The type of an operator is identified by the a combination of package and type. This allows the use of operators which are defined in third party packages but are not known to the runtime library. Parameters of operators can be set by the respective Parameter element. This element contains exactly one Data element which contains the value of the parameter. The type of the data is also specified by the combination of package and type. Again this allows allows to set parameters whose type is defined in an external library and thus not know to runtime runtime.

In addition to parameters the Operator element contains a list of its inputs and the outputs these inputs are connected to. As in program in the previous tutorial input and output connectors are identified by the operator the belong to (via the operator ID) and the ID of the respective input or output. In the above example the input 0 of the second operator (ID 1) is connected to the output 0 of the first operator (ID 1).

The same principle holds for the list of input connector elements of a Thread element. Here, the only thread in the stream operates the input connector 0 of the operator with ID 1. The code which reads this XML file is explained in the following:

Again the programs starts by importing all required header files. In addition to headers which were also included in the last tutorial two more files from the runtime library are required. On the other hand, the inclusion of the operator headers in the example library is not required anymore. The file example/Example.h is the only one which is needed from this library.

As a first step a factory is instantiated. The factory will be used to instantiate all operators and data types which appear in the XML file. After construction the factory is empty, i.e. it does not know any operator or data type. Only after registering a runtime package the factory can produce operators or data types from this package.

Note

If the above way of registering a package is used the package must be known at compile time. However, a package can be used even later if the library which contains its code is loaded dynamically during program execution. If the package MyPackage was loaded this way then the function registerMyPackage() would have to be called to allow the import of XML files which use MyPackage.

In the next step a stream is instantiated according the XML file using a runtime::XmlReader. Note that the previously configured factory is passed to the constructor of runtime::XmlReader. This way it knows which classes to instantiate if operators or data types are defined by combinations of package and type names. Because the complete configuration of the stream is given in the file the stream is ready to be started after it has been read. In other words, all operators have automatically been initialized, the connections between them have been established and each thread has been informed about its input connectors.

So far a stream was build and started without knowing anything about its internal structure. To have a look at the processed data a specific operator must obviously be addressed. The above line obtains a pointer to the second operator in the stream. Note that second refers to the zero-exampled position of the operator in the XML file not its ID there.

The rest of the code is exactly the same as in the previous example.

This program illustrates that it is possible to define and operate a stream without knowledge of the exact data types of its operators and their parameters. It is only necessary to either link to the library which contains these types or to dynamically load this library at runtime. In other words, the runtime runtime is designed work with any operator which are defined in external packages. The tutorial Operator shows how to implement such an operator in a custom package.