OpenSplice examples - Lifecycle

# EXAMPLES

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

## Lifecycle

- Running of examples in Standalone Mode

### 1) Description

The Lifecycle example is used to illustrate the different lifecycle states of the sample and the instance.

- The SampleState applies to an individual sample and is either READ or NOT_READ, depending on whether the sample has been accessed from this reader before.
- The ViewState applies to an individual instance (possibly containing of 1 or more samples) and is either NEW or NOT_NEW, depending on whether a sample belonging to the same instance has been accessed from this reader before.
- The InstanceState applies to an individual instance (possibly containing of 1 or more samples) and is either
  - ALIVE
  - NOT_ALIVE_DISPOSED
  - NOT_ALIVE_NO_WRITERS
  depending on whether the Lifecycle publisher has still registered the instance, has disposed it or has unregistered it.

The autodispose_unregistered_instances flag of the Lifecycle publisher determines whether an invocation of unregister_instance on this publisher will cause the instance to become disposed.

### 2) Design

It consists of 4 units:

- CheckStatus: provides return status checking
- DDSEntitiesManager: implements a class providing operations to setup DCPS entities (creation, deletion)
- LifecyclePublisher: implements the publisher's main (uses DDSEntitiesManager)
- LifecycleSubscriber: implements the subscriber's main (uses DDSEntitiesManager)

### 3) Scenario

The Publisher and the Subscriber processes communicate using the following topic:

       struct Msg
       {
          long userID;         // User ID
          string message;      // content;
          string writerStates; // the different state of the writer
        };

The writerStates field contains the different states of the writer :

- "SAMPLE_SENT -> INSTANCE_DISPOSED -> DATAWRITER_DELETED"
- "SAMPLE_SENT -> INSTANCE_UNREGISTERED -> DATAWRITER_DELETED"
- "SAMPLE_SENT -> DATAWRITER_DELETED"

      usage : LifecyclePublisher [autodispose_flag] [writer_action]
       autodispose_flag =  false | true
       writer_action = dispose | unregister | stoppub

The LifecyclePublisher : Depending on the user's choice as the second parameter passed on command line (dispose | unregister | stoppub), it will either: Case 1 : second parameter passed on command line "dispose" publish the Msg Sample. Dispose the instance. Delete the DataWriter. Stop the Subscriber. Case 2 : second parameter passed on command line "unregister" publish the Msg Sample. Unregister the instance. Delete the DataWriter. Stop the Subscriber. Case 3 : second parameter passed on command line "stoppub" publish the Msg Sample. Delete the DataWriter. Stop the Subscriber. For any of those actions, it will output on its console: "SAMPLE SENT" "INSTANCE DISPOSED" "INSTANCE UNREGISTERED" "DATAWRITER DELETED" "STOPPING SUBSCRIBER" | The LifecycleSubscriber : Reads the (same unique) Msg Topic Sample. Display the Sample's information: The 2 fields of Msg Topic : message and writerStates The States : The "sample_state", possible values are: "NOT_READ_SAMPLE_STATE" "READ_SAMPLE_STATE" The "view_state", possible values are: "NEW_VIEW_STATE" "NOT_NEW_VIEW_STATE" The "instance_state", possible values are "ALIVE_INSTANCE_STATE" "NOT_ALIVE_DISPOSED_INSTANCE_STATE" "NOT_ALIVE_NO_WRITERS"

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

#### C and C++ Executables

Building the examples is described on the Summary page

Two executables and a library are generated in the standalone directory when the example is built:

For C++

- sacpp_lifecycle_pub
- sacpp_lifecycle_sub
- libsacpp_lifecycle_types.so

For C

- sac_lifecycle_pub
- sac_lifecycle_sub
- libsac_lifecycle_types.so

#### Java executables

Building the examples is described on the Summary page

Three jars are generated in the java\standalone or java5 directory when the example is built:

For Java

- saj_lifecycle_sub.jar
- saj_lifecycle_pub.jar
- saj_lifecycle_types.jar

For Java5

- saj5_lifecycle_sub.jar
- saj5_lifecycle_pub.jar
- saj5_lifecycle_types.jar

#### ISO C++ 2 Executables

Building the examples is described on the Summary page

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

- publisher
- subscriber

#### 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 subscriber and publisher

- In the first terminal start the subscriber by running either
  - sac_lifecycle_sub for C
  - sacpp_lifecycle_sub for C++
  - java -jar saj_lifecycle_sub.jar for Java
  - java -jar saj5_lifecycle_sub.jar for Java5
  - subscriber for ISO C++ 2
- In the second terminal start the publisher by running either
  - sac_lifecycle_pub [autodispose_flag] [writer_action] for C
  - sacpp_lifecycle_pub [autodispose_flag] [writer_action] for C++
  - java -jar saj_lifecycle_pub.jar [autodispose_flag] [writer_action] for Java
  - java -jar saj5_lifecycle_pub.jar [autodispose_flag] [writer_action] for Java5
  - publisher [autodispose_flag] [writer_action] for ISO C++ 2

            usage : LifecycleDataPublisher [autodispose_flag] [writer_action]
                    Where
                    . autodispose_flag = false | true
                    . writer_action = dispose | unregister | stoppub

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

#### C/C++/C# Executables

Building the examples is described on the Summary page

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

For C

- sac_lifecycle_sub.exe
- sac_lifecycle_pub.exe

For C++

- sacpp_lifecycle_sub.exe
- sacpp_lifecycle_pub.exe

For C#

- sacs_lifecycle_sub.exe
- sacs_lifecycle_pub.exe

#### Java Executables

Building the examples is described on the Summary page

Three jars are generated in the java\standalone or java5 directory when the example is built:

For Java

- saj_lifecycle_sub.jar
- saj_lifecycle_pub.jar
- saj_lifecycle_types.jar

For Java5

- saj5_lifecycle_sub.jar
- saj5_lifecycle_pub.jar
- saj5_lifecycle_types.jar

#### ISO C++ 2 Executables

Building the examples is described on the Summary page

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

- publisher
- subscriber

#### Running the C/C++/C#/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 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 OpenSplice Command Prompts. In each window:
- Go to the example directory 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 subscriber and publisher

- In the first terminal start the subscriber by running either
  - sac_lifecycle_sub for C
  - sacpp_lifecycle_sub for C++
  - sacs_lifecycle_sub for C#
  - java -jar saj_lifecycle_sub.jar for Java
  - java -jar saj5_lifecycle_sub.jar for Java5
  - subscriber for ISO C++ 2
- In the second terminal start the publisher by running either
  - sac_lifecycle_pub [autodispose_flag] [writer_action] for C
  - sacpp_lifecycle_pub [autodispose_flag] [writer_action] for C++
  - sacs_lifecycle_pub [autodispose_flag] [writer_action] for C#
  - java -jar saj_lifecycle_pub.jar [autodispose_flag] [writer_action] for Java
  - java -jar saj5_lifecycle_pub.jar [autodispose_flag] [writer_action] for Java5
  - publisher [autodispose_flag] [writer_action] for ISO C++ 2

            usage : LifecycleDataPublisher [autodispose_flag] [writer_action]
                    Where
                    . autodispose_flag = false | true
                    . writer_action = dispose | unregister | stoppub