2. Introduction

2.1. Features

Vortex OpenSplice Streams API supports a common data-distribution pattern where continuous flows or streams of data have to be transported with minimal overhead and therefore maximal achievable throughput.

Vortex OpenSplice Streams API implements this streams pattern by transparent packing and queuing of data samples using auto-generated containers, thus minimizing the overhead normally associated with the management and distribution of individual DDS samples.

2.2. Getting Started

The Vortex OpenSplice Streams API is divided in two main components:

  • type-specific code that can be generated using the Vortex OpenSplice IDL Pre-Processor

  • a Streams library.

Applications that wish to use the Streams API are required to do two things:

  1. Link against one of the Vortex OpenSplice Streams libraries available within the Vortex OpenSplice distribution. There are separate libraries for either CORBA-Cohabitation mode or Standalone C++ mode.

  2. Annotate the data-model IDL file with #pragma stream directives for each data type for which a Stream needs to be created.

The Vortex OpenSplice Streams API is built on the DCPS API. Since the C++ bindings of Vortex OpenSplice are available in two flavours, so is the Streams API. In the following paragraphs the steps will be discussed to build a simple application that uses the following data-model:

Space.idl:

module Space {
    struct Foo {
        long long_1;
        long long_2;
    };
#pragma stream Foo

    struct Type2 {
      long long_1;
      long long_2;
      long long_3;
    };
#pragma stream Type2
#pragma keylist Type2 long_1

};

Using this model, both Foo and Type2 can be used with the Streams API. In addition Type2 can also be used as a regular DDS topic, with long_1 as key.

The following relevant Streams API classes are generated based on this model for Foo:

Space::FooStreamDataWriter
Space::FooStreamDataReader
Space::FooStreamBuf

It is recommended to use smart references to the StreamDataWriter and StreamDataReader classes in applications. The regular Vortex OpenSplice C++ smart-pointer <class>_var types are available for this purpose. See the section on Memory Management in the Vortex OpenSplice C++ Reference Guide for more information.

2.2.1. CORBA Cohabitation Mode

In CORBA Co-habitation mode, idlpp generates code that can be processed with any of the supported ORB compilers (OpenFusion TAO, Mico, etc.).

First idlpp is executed on the Space.idl file:

$ idlpp -I$OSPL_HOME/etc/idl -l cpp -C Space.idl

The standard Vortex OpenSplice IDL directory is referenced as include-path, since it contains definitions of some basic data-types and interfaces that are required if DDS Topics are created for any of the types in the IDL file. The other parameters are used to put idlpp in C++ CORBA-Cohabitation mode.

As usual when DDS topics are created, the above command generates, among other files, a file called SpaceDcps.idl. The file SpaceStreams.idl is also generated.

To proceed, idlpp should be executed on the ExampleStreams.idl file:

$ idlpp -I$OSPL_HOME/etc/idl -l cpp -C SpaceStreams.idl

This creates the descriptions of the DCPS entities that are required to manage the DDS topics that will be used for the Streams types, just like with the original IDL file, in a file called SpaceStreamsDcps.idl.

Now all four IDL files should be processed with the appropriate (ORB-specific) CORBA IDL processor. After this step all code and header files are generated to start using the Streams API in application code.

2.2.2. Standalone Mode

In Standalone C++ mode, the generated interfaces are not required to be processed by an IDL compiler. Instead, idlpp will use the cppgen code-generator that is part of the Vortex OpenSplice distribution. idlpp will automatically call cppgen to process certain files; the user is only required to execute idlpp, first on the original IDL file:

$ idlpp -I$OSPL_HOME/etc/idl -l cpp -S Space.idl

This creates SpaceStreams.idl, which in turn also needs to be processed by idlpp:

$ idlpp -I$OSPL_HOME/etc/idl -l cpp -S -i SpaceStreams.idl

The -i parameter is required because normally no code is generated for interfaces (for DDS topics, only datatypes are generated). In the case of streams, interfaces should not be ignored.