# EXAMPLES

- Summary
- PingPong
- Tutorial
- HelloWorld
- WaitSet
- Listener
- ContentFilteredTopic
- QueryCondition
- Lifecycle
- Durability
- Ownership
- BuiltInTopics
- NetworkPartitions
- RoundTrip
- Throughput

## Throughput

- Running of examples in Standalone Mode
- Running of examples with default values

### 1) Description

The Throughput example allows the measurement of data throughput when receiving samples from a publisher.

### 2) Design

It consists of 2 units :

- publisher : Sends samples at a specified size and rate
- subscriber : Receives samples and outputs statistics about throughput

### 3) Scenario

The publisher sends samples and allows you to specify a payload size in bytes as well as allowing you to specify whether to send data in bursts. The publisher will continue to send data forever unless a time out is specified.

Configurable:

- payloadSize: the size of the payload in bytes
- burstInterval: the time interval between each burst in ms
- burstSize: the number of samples to send each burst
- timeOut: the number of seconds the publisher should run for (0 infinite)
- partitionName: the name of the partition

The subscriber will receive data and output the total amount received and the data rate in bytes per second. It will also indicate if any samples were received out of order. A maximum number of cycles can be specified and once this has been reached the subscriber will terminate and output totals and averages.

The subscriber executable measures:

- transferred: the total data transferred in bytes
- outOfOrder: the number of samples that were received out of order
- transfer rate: the data transfer rate in bytes per second
- subscriber also calculates statistics on these values over a configurable number of cycles

Configurable:

- maxCycles: the number of times to output statistics before terminating
- pollingDelay:
- partitionName: the name of the partition

## Running of examples in Standalone Mode

- Running examples in Posix
- Running examples in Visual Studio

### Running the examples in a Posix environment

#### Environment Setup

Let's call OpenSplice_install_dir the OpenSplice installation directory.

The OpenSplice environment variables must be set in order for the examples to build/run correctly. To do this, open a terminal and source the "OpenSplice_install_dir/release.com" script supplied with the distribution.

- C/C++ ISO C++ 2 Examples
- Java examples

#### C, C++ and ISO C++ 2 Executables

Building the examples is described on the Summary page

Two executables and a two libraries are generated in the example directory when the example is built:

For ISO C++ 2

- publisher
- subscriber
- libISO_Cxx_V2_Throughput_Impl.so
- libISO_Cxx_V2_Throughput_Types.so

For C++

- publisher
- subscriber
- libSA_Cxx_Throughput_Impl.so
- libSA_Cxx_Throughput_Types.so

For C

- publisher
- subscriber
- libISO_C_Throughput_Impl.so
- libISO_C_Throughput_Types.so

#### Java executables

Building the examples is described on the Summary page

Three jars are generated in the example directory when the example is built:

For Java

- Saj_Throughput_Publisher.jar
- Saj_Throughput_Subscriber.jar
- Saj_Throughput_Types.jar

For Java5

- java5_Throughput_pub.jar
- java5_Throughput_sub.jar
- Saj5_Throughput_Types.jar

#### Running the example

Ensure that the environment for OpenSplice is set up correctly as described above for each new terminal used.

It is recommended that you run the subscriber and publisher in separate terminals to avoid mixing the output

Running in single process (heap memory) configuration : the application starts OpenSplice middleware

- OpenSplice is deployed in this mode by default.
- The OpenSplice daemon should not be started manually. Instead the OpenSplice middleware and optional services are implicitly started by the single process applications as required
- Open 2 terminals. Set up the environment and go to the example directory as described above

Running in multiple process shared memory configuration

To enable deployment in this mode, an OpenSplice configuration file must be selected that has shared memory support e.g. one of the ospl_shmem xml configuration files found in the OpenSplice_install_dir/etc/config directory.

- Open 2 terminals. In each terminal:
- Setup the environment and go to the example directory as described above
- Set the required configuration file e.g. OSPL_URI=file://$OSPL_HOME/etc/config/ospl_shmem_ddsi.xml
- Start the OpenSplice daemon. You can do this by typing ospl start

Starting the publisher and subscriber

- In the first terminal start the publisher by running either
  - publisher for C/C++/ISO C++ 2
  - java -classpath $OSPL_HOME/jar/dcpssaj.jar:classes publisher for Java
  - java -classpath $OSPL_HOME/jar/dcpssaj5.jar:classes publisher for Java5

        publisher usage (parameters must be supplied in order):
          ./publisher [payloadSize (bytes)] [burstInterval (ms)] [burstSize (samples)] [timeOut (seconds)] [partitionName]
        defaults:
          ./publisher 8192 0 1 0 "Throughput example"

- In the second terminal start the subscriber by running either
  - subscriber for C/C++
  - java -classpath $OSPL_HOME/jar/dcpssaj.jar:classes subscriber for Java
  - java -classpath $OSPL_HOME/jar/dcpssaj5.jar:classes subscriber for Java5

        subscriber usage:
          ./subscriber [maxCycles (0 = infinite)] [pollingDelay (ms, 0 = event based)] [partitionName]
        defaults:
          ./subscriber 0 0 "Throughput example"

To achieve optimal performance it is recommended to set the CPU affinity so that the publisher and subscriber run on separate CPU cores. You must have su privileges to run the following commands.

        publisher usage:
          taskset -c 0 chrt -f 80 ./publisher [payloadSize (bytes)] [burstInterval (ms)] [burstSize (samples)] [timeOut (seconds)] [partitionName]
        subscriber usage:
          taskset -c 1 chrt -f 80 ./subscriber [maxCycles (0 = infinite)] [pollingDelay (ms, 0 = event based)] [partitionName]

### Running C/C++/ISO C++ 2/Java on Windows

#### Environment Setup

Let's call OpenSplice_install_dir the OpenSplice installation directory.

The OpenSplice environment variables must be set in order for the examples to run correctly. To do this open an OpenSplice Command Prompt which will set up the environment variables for OpenSplice automatically. The OpenSplice Command Prompt can be selected from the start menu. Alternatively, open a windows Command Prompt and execute the "OpenSplice_install_dir\release.bat" batch script supplied with the distribution.

#### C/C++/ISO C++ 2

Building the examples is described on the Summary page

Two executables are generated in the example directory when the example is built:

For C and C++

- publisher.exe
- subscriber.exe

#### Java executables

Building the examples is described on the Summary page

Three jars are generated in the example directory when the example is built:

For Java

- Saj_Throughput_Publisher.jar
- Saj_Throughput_Subscriber.jar
- Saj_Throughput_Types.jar

For Java5

- java5_Throughput_pub.jar
- java5_Throughput_sub.jar

#### Running the C/C++/ISO C++ 2 Examples

Ensure that the environment for OpenSplice is set up correctly as described above for each new command prompt used.

The following steps describe how to run the examples:

Running in single process (heap memory) configuration : the application starts OpenSplice middleware

- OpenSplice is deployed in this mode by default.
- The OpenSplice daemon should not be started manually. Instead the OpenSplice middleware and optional services are implicitly started by the single process applications as required
- Open 2 OpenSplice Command Prompts and go to directory example as described above

Running in multiple process shared memory configuration

To enable deployment in this mode, an OpenSplice configuration file must be selected that has shared memory support e.g. one of the ospl_shmem xml configuration files found in the OpenSplice_install_dir\etc\config directory.

- Open 2 OpenSplice Command Prompts. In each window:
- Go to directory standalone as described above
- Set the required configuraton file e.g. set OSPL_URI=file://%OSPL_HOME%\etc\config\ospl_shmem_ddsi.xml
- Start the OpenSplice daemon. You can do this by typing ospl start

Starting the publisher and subscriber

- In the first terminal start the publisher by running either
  - publisher.exe for C/C++
  - java -classpath "%OSPL_HOME%\jar\dcpssaj.jar";classes publisher for Java
  - java -jar pub/java5_Throughput_pub.jar for Java5

        publisher usage (parameters must be supplied in order):
          publisher.exe [payloadSize (bytes)] [burstInterval (ms)] [burstSize (samples)] [timeOut (seconds)] [partitionName]
        defaults:
          publisher.exe 8192 0 1 0 "Throughput example"

- In the second terminal start the subscriber by running either
  - subscriber.exe for C/C++
  - java -classpath $OSPL_HOME/jar/dcpssaj.jar:classes subscriber for Java
  - java -jar sub/java5_Throughput_sub.jar for Java5

        subscriber usage:
          subscriber.exe [maxCycles (0 = infinite)] [pollingDelay (ms, 0 = event based)] [partitionName]
        defaults:
          subscriber.exe 0 0 "Throughput example"

To achieve optimal performance it is recommended to set the CPU affinity so that the publisher and subscriber run on separate CPU cores

        publisher usage:
          START /affinity 1 /high cmd /k "publisher.exe" [payloadSize (bytes)] [burstInterval (ms)] [burstSize (samples)] [timeOut (seconds)] [partitionName]
        subscriber usage:
          START /affinity 2 /high cmd /k "subscriber.exe" [maxCycles (0 = infinite)] [pollingDelay (ms, 0 = event based)] [partitionName]

## Running of examples with default values

There is a binary executable in examples/dcps/PerfomanceScripts which aims to run the selected ping and pong executables without prior configuration or command line arguments.

The executable by default will -

- Test a range of iterating payload values 0-64KB
- Test across APIs (c, sacpp, isocpp2)
- Log all results per API
  - Write all results to API/ping.csv
- Log averages
  - Write timestamped averages to averages.csv in current directory
- Set maximum process priority and set CPU affinity

The executable requires -

- Administrator or root privileges
- The example be compiled for the particular API being tested

Its also recommended that for best results the benchmark is run on a shared memory multiple process configuration.

The Throughput executable provides several command line options to manipulate the ping and pong processes, a short description of each is provided in the executable options -

    # Throughput --help

Some common examples -

- Running with defaults

      # Throughput

- Running against isocpp2 api only

      # Throughput -I

- Running against the sacpp and isocpp api

      # Throughput -S -I

- Write to a different averages file

      # Throughput -o somefile.csv

- Use two separate cores/processors note: best performance is achieved by using separate physical cores

      # Throughput --pingaffinity=0 --pongaffinity=4