# EXAMPLES

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

## RoundTrip

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

### 1) Description

The Roundtrip example allows the measurement of roundtrip duration when sending and receiving back a single message.

### 2) Design

It consists of 2 units :

- pong : Waits for messages from ping and sends the same message back
- ping : Sends a message to pong and waits for its return

### 3) Scenario

A message is sent by the ping executable on the "PING" partition, which the pong executable is waiting for. The pong executable sends the same message back on the "PONG" partition, which the ping executable is waiting for. This sequence is repeated a configurable number of times.

The ping executable measures:

- writeAccess time: time the write() method took.
- readAccess time: time the take() method took.
- roundTrip time: time between the call to the write() method and the return of the take() method.
- ping also calculates min/max/average statistics on these values over a configurable number of samples and/or time out period

Configurable:

- payloadSize: the size of the payload in bytes
- numSamples: the number of samples to send
- timeOut: the number of seconds ping should run for

## 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

- ping
- pong
- libISO_Cxx_V2_RoundTrip_Impl.so
- libISO_Cxx_V2_RoundTrip_Types.so

For C++

- ping
- pong
- libSA_Cxx_RoundTrip_Impl.so
- libSA_Cxx_RoundTrip_Types.so

For C

- ping
- pong
- libSA_C_RoundTrip_Impl.so
- libSA_C_RoundTrip_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_RoundTrip_Ping.jar
- Saj_RoundTrip_Pong.jar
- Saj_RoundTrip_Types.jar

For Java5

- java5_ping.jar
- java5_pong.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. Setup 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 ping and pong

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

        pong usage:
          ./pong

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

        ping usage (parameters must be supplied in order):
          ./ping [payloadSize (bytes, 0 - 655536)] [numSamples (0 = infinite)] [timeOut (seconds, 0 = infinite)]
          ./ping quit - ping sends a quit signal to pong.
        defaults:
          ./ping 0 0 0

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

        pong usage:
          taskset -c 0 chrt -f 80 ./pong
        ping usage:
          taskset -c 1 chrt -f 80 ./ping [payloadSize (bytes, 0 - 655536)] [numSamples (0 = infinite)] [timeOut (seconds, 0 = infinite)]

### Running C/C++/ISO C++ 2/Java examples 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 Examples
- Java examples

#### 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, C++ and ISO C++ 2

- ping.exe
- pong.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:

- Saj_RoundTrip_Ping.jar
- Saj_RoundTrip_Pong.jar
- Saj_RoundTrip_Types.jar

#### Running the C/C++/ISO C++ 2/Java 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 standalone 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

- In the first terminal start pong by running either
  - pong.exe for C/C++/ISO C++ 2
  - java -classpath "%OSPL_HOME%\jar\dcpssaj.jar";classes pong for Java
  - java -jar pong/java5_pong.jar for Java5

        pong usage:
          pong.exe

- In the second terminal start ping by running either
  - ping.exe for C/C++/ISO C++ 2
  - java -classpath "%OSPL_HOME%\jar\dcpssaj.jar";classes ping for Java
  - java -jar ping/java_ping.jar for Java5

          ping usage (parameters must be supplied in order):
            ping.exe [payloadSize (bytes, 0 - 655536)] [numSamples (0 = infinite)] [timeOut (seconds, 0 = infinite)]
            ping.exe quit - ping sends a quit signal to pong.
          defaults:
            ping.exe 0 0 0

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

          pong usage:
            START /affinity 0 /high cmd /k "pong.exe"
          ping usage:
            START /affinity 2 /high cmd /k "ping.exe" [payloadSize (bytes, 0 - 655536)] [numSamples (0 = infinite)] [timeOut (seconds, 0 = infinite)]

  ## 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 Roundtrip executable provides several command line options to manipulate the ping and pong processes, a short description of each is provided in the executable options -

      # Roundtrip --help

  Some common examples -

  - Running with defaults

        # Roundtrip

  - Running against isocpp2 api only

        # Roundtrip -I

  - Running against the sacpp and isocpp2 api

        # Roundtrip -S -I

  - Write to a different averages file

        # Roundtrip -o somefile.csv

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

        # Roundtrip --pingaffinity=0 --pongaffinity=4