This presentation provides 20 Tips that help newbies to get into OpenSplice while avoiding the most common traps and pitfalls.

1. 20 Tips for
OpenSplice Newbies
Angelo Corsaro, Ph.D.
Chief Technology Officer
OMG DDS Sig Co-Chair
PrismTech
angelo.corsaro@prismtech.com

2. Domain

3. Tip #0
Domains, Partitions, Topics
Domain (e.g. Domain 123)
¨ All DDS applications publish
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
and subscribe data on a
Partition belonging to a
given domain
Partitions (e.g. Partition “Telemetry”)
¨ Partitions are defined by
means for strings and can Topic Instances/
be matched with regular Samples
expressions
¨ If not explicitly specified the
default partition in the
default domain is
automatically chosen

4. Tip #0
Partitions Matching
"building-1.floor-3.room-51"
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
"building-1.floor-1.room-*"
... building-1.floor-3.room-5 ...
¨ Partitions are
defined by means building-1.floor-1.room-111 building-1.floor15-.room-51
for strings and can
be matched with building-1.floor-3.room-11
regular building-1.floor-1.room-1 building-1.floor-10.room-100
expressions] ...
"building-1.floor-*.room-11?" Domain

5. Configuration 101

6. Tip #1
Choosing a Domain
¨ In OpenSplice DDS v5.x a domain is selected by:
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
¨ Defining the OSPL_URI environment variable
¨ Passing a URI pointing at the the domain XML configuration file at
OpenSplice startup
¨ Passing the URI of the configuration file as a string parameter of the
DomainParticipantFactory::create_participant method
¨ Passing the name of the domain as specified in the configuration file
to the DomainParticipantFactory::create_participant method
¨ Passing the empty string to represent the default domain to the
DomainParticipantFactory::create_participant method

7. Tip #1
Choosing a Domain
Domain specified via URI
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
Defining Domain Configuration at Startup
dpf.create_participant(
“file:///some/path/myospl.xml”,
$ ospl start file:///some/path/myospl.xml
qos,
listener,
mask);
Default Domain
dpf.create_participant( Domain specified via a Domain Name
“”,
qos, dpf.create_participant(
listener, “MyDomainNameAsSpecifiedOnTheXMLFile”,
mask); qos,
listener,
mask);

8. Tip #1
Domains on OpenSplice v6.x
¨ The DDS specification did not originally define the type for the
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
DomainId, as a result vendors where free to choose their on types
¨ As the DDSI/RTPS specification defines a DomainId with and integer it
makes sense to uniform the DDS API to use an integer DomainID
¨ As a result, starting with OpenSplice DDS the domain will be selected
specifying its associated id:
dpf.create_participant(
15,
qos,
listener,
mask);

9. Tip #2
Start OpenSplice First
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
¨ OpenSplice v5.x runs by default on a shared/
memory + daemon configuration
¨ As such, if you forget to start the infrastructure your
application will fail at start up
¨ Thus always recall to run:
$ ospl start

10. Tip #3
Shared Memory Size
OpenSplice DDS shared memory size is defined in its
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
¨
configuration file. The size defined by the default
configuration file is 10MBytes
¨ Beware that different OS have different limitations w.r.t. the
maximum shared memory segment that can be allocated
¨ If you want to go beyond the OS limits you need to change
the configuration of your kernel

11. Tip #3
Linux
¨ The default value for the maximum shared memory segment is
32MBytes
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
¨ This default can be changed in several ways
(1) Adding this line to your /etc/rc.d/rc.local file:
echo “your_max_shared_memory_size” > /proc/sys/kernel/shmmax
(2) Changing the settings for the sys-limits (save changes on /etc/
sysctl.conf to maintain them across reboots):
$ sysctl -w kernel.shmmax=yourMaxValue

12. Tip #3
Windows
The default maximum size for Shared Memory
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
¨
segments on Windows is 2GB
¨ To exend it, say to 3GB, add the /3GB the boot.ini
as shown below:
[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(1)WINDOWS
[operating systems]
multi(0)disk(0)rdisk(0)partition
(1)WINDOWS="Windows NT
Workstation Version 4.00"
/3GB

13. DDS Topics

14. Tip #4
Topic Types & Keys
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
¨ Topic Types can define some of their attributes as keys
¨ Yet, even when a Topic type does not define a key the
keylist directive has to be provided -- just to tell the IDL
compiler that this is a topic

15. Tip #4
Topic Types & Keys
Keyful Keyless
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
enum TemperatureScale {
CELSIUS,
FAHRENHEIT, struct UniversalConstants {
KELVIN double PI;
}; double e; // Nepero Number
double g; // Gravitational Constant
struct TempSensorType { double NA; // Avogadro Number
short id; double F; // Faraday Constant
float temp; double K; // Boltzman Constant
float hum; double c; // Light Speed
TemperatureScale scale; };
}; #pragma keylist UniversalConstants
#pragma keylist TempSensorType id

16. Tip #5
Topic Instances
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
enum TemperatureScale {
CELSIUS, Writer Reader
FAHRENHEIT,
KELVIN
};
2 26.0 70.0 CELSIUS 1 26.0 70.0 CELSIUS
struct TempSensorType { 1 26.0 70.0 CELSIUS 2 26.0 70.0 CELSIUS
short id;
float temp;
float hum;
TemperatureScale scale;
};
#pragma keylist TempSensorType

17. Tip #5
Topic Instances
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
enum TemperatureScale {
CELSIUS, Writer Reader
FAHRENHEIT,
KELVIN
};
2 26.0 70.0 CELSIUS
struct TempSensorType { 1 26.0 70.0 CELSIUS 2 26.0 70.0 CELSIUS
1 26.0 70.0 CELSIUS
short id;
float temp;
float hum;
TemperatureScale scale;
};
#pragma keylist TempSensorType id

18. Tip #6
Topic Instances Lifecycle
struct VehiclePosition {
string plate;
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
long x;
long y;
}; com.myco.VPos
#pragma keylist VehiclePosition plate
struct VehiclePosition {
string plate;
long x;
long y;
};
#pragma keylist VehiclePosition
com.myco.VPos

19. Tip #6
Topic Instances Lifecycle
struct VehiclePosition {
string plate; New
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
long x; “A01” 100 200
long y;
}; com.myco.VPos
#pragma keylist VehiclePosition plate
struct VehiclePosition {
string plate;
long x;
long y; New
};
#pragma keylist VehiclePosition “A01” 100 200
com.myco.VPos

20. Tip #6
Topic Instances Lifecycle
struct VehiclePosition {
string plate; New
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
long x; “A01” 100 200
long y;
}; New
#pragma keylist VehiclePosition plate “B41” 57 31
com.myco.VPos
struct VehiclePosition {
string plate;
long x;
long y;
};
#pragma keylist VehiclePosition “B41” 57 31 “A01” 100 200
com.myco.VPos

21. Tip #6
Topic Instances Lifecycle
struct VehiclePosition {
string plate; New
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
long x; “A01” 110 210 “A01” 100 200
long y;
}; New
#pragma keylist VehiclePosition plate “B41” 57 31
com.myco.VPos
struct VehiclePosition {
string plate;
long x;
long y;
};
#pragma keylist VehiclePosition “A01” 110 210 “B41” 57 31 “A01” 100 200
com.myco.VPos

22. Tip #6
Topic Instances Lifecycle
New
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
“A01” 120 220 “A01” 110 210 “A01” 100 200
New
“B41” 57 31
com.myco.VPos
“A01” 120 220 “A01” 110 210 “B41” 57 31 “A01” 100 200
com.myco.VPos

23. Tip #6
Topic Instances Lifecycle
New
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
“A01” 120 220 “A01” 110 210 “A01” 100 200
New
“B41” 47 19 “B41” 57 31
com.myco.VPos
“B41” 47 19 “A01” 120 220 “A01” 110 210 “B41” 57 31 “A01” 100 200
com.myco.VPos

24. Tip #6
Topic Instances Lifecycle
New
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
“A01” 120 220 “A01” 110 210 “A01” 100 200
New
“B41” Disposed -
- “B41” 47 19 “B41” 57 31
com.myco.VPos
“B41” 47 19 “A01” 120 220 “A01” 110 210 “B41” 57 31 “A01” 100 200
com.myco.VPos

25. Tip #7
Default Lifecycle Settings
The WriterDataLifecycle controls when instances are
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
¨
disposed. By default DDS disposes unregistered
instances
¨ Automatically disposing an instance perhaps is not
what your want to do when terminating your
application, as this would remove persistent data for
the given instance!

26. QoS

27. Tip #8
Understand the QoS Model
¨ DDS defines 22 QoS DURABILITY LIVELINESS DEST. ORDER TIME-BASED FILTER
policies that can be
HISTORY OWENERSHIP PARTITION RESOURCE LIMITS
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
LIFESPAN OWN. STRENGTH PRESENTATION
applied to RELIABILITY DW LIFECYCLE
communication USER DATA DEADLINE DR LIFECYCLE
entities to control their TOPIC DATA
GROUP DATA
LATENCY BUDGET
TRANSPORT PRIO
ENTITY FACTORY
local as well as end-
to-end behaviour RxO QoS Local QoS
¨ Most of the QoS Policies that control an end-to-end property
follow the so-called Request vs. Offered (RxO) Model based on
which the QoS requested by the Consumer should not exceed
the QoS Provided by the Producer

28. Tip #9
History + Reliability Interplay
¨ The History QoS controls the number of samples that
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
are maintained by DDS for a given topic
¨ DDS can keep the last n samples or keep all samples
up to when they are not taken by the application
¨ The History setting has an impact on the reliability of
data delivery as perceived by the application. Thus
beware of your settings!

29. Tip #9
History + Reliability Interplay
struct Counter { QoS Settings
int cID;
Reliability = Reliable
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
int count;
};
#pragma keylist Counter cID
History = KeepLast(1)
History Depth = 1 History Depth = 1
(DDS Default) (DDS Default)
Network
1 1 1 2
DataReader 2 1 1 2 2 3
DataWriter
3 1 2 2 2 3 3 1
Topic Topic
DataReader Cache DataWriter Cache

30. Tip #9
History + Reliability Interplay
struct Counter { QoS Settings
int cID;
Reliability = Reliable
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
int count;
};
#pragma keylist Counter cID
History = KeepLast(1)
History Depth = 1 History Depth = 1
(DDS Default) (DDS Default)
Network
1 2 1 2
DataReader 2 2 2 3
DataWriter
3 1 2 3 3 1
Topic Topic
DataReader Cache DataWriter Cache

31. Tip #9
History + Reliability Interplay
struct Counter { QoS Settings
int cID;
Reliability = Reliable
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
int count;
};
#pragma keylist Counter cID
History = KeepLast(1)
History Depth = 1 History Depth = 1
(DDS Default) (DDS Default)
Network
1 2 1 2
DataReader 2 3 2 3
DataWriter
3 1 3 1
Topic Topic
DataReader Cache DataWriter Cache

32. Tip #7
#10
Define Resource Limits
¨ DDS Provides a QoS that allow to control the amount of resources used by
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
DataReaders and DataWriters
¨ By default, DDS does not imposes any limit, with the results that if you have a
buggy application or an asymmetry in your system you might end-up
consuming unbounded amount of memory -- and in the OpenSplice DDS case
filling the Shared Memory
¨ To avoid this problem, always set appropriate Resource Limits for your
application by defining:
¨ max_samples
¨ max_instances
¨ max_samples_per_instance

33. Accessing the Data

34. Tip #11
Read vs. Take struct Counter {
int cID;
QoS Settings int count;
¨ DataReader::read };
iterates over the available History = KeepLast(k)
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
#pragma keylist Counter cID
sample instances
¨ Samples are not removed
from the local cache as 1 1 1 2 1 3 1 4
result of a read DataReader
2 1 2 2 2 3
3 1 3 2 3 3 3 4 3 5
¨ Read samples can be Topic
read again, by accessing
the cache with the Samples Read Samples not Read
proper options (more DataReader Cache
later)

35. Tip #11
Read vs. Take struct Counter {
int cID;
QoS Settings int count;
¨ DataReader::read };
iterates over the available History = KeepLast(k)
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
#pragma keylist Counter cID
sample instances
¨ Samples are not removed
from the local cache as 1 1 1 2 1 3 1 4
result of a read DataReader
2 1 2 2 2 3
3 1 3 2 3 3 3 4 3 5
¨ Read samples can be Topic
read again, by accessing
Samples not Read
the cache with the Samples Read
proper options (more DataReader Cache
later)

36. Tip #11
Read vs. Take struct Counter {
int cID;
QoS Settings int count;
¨ DataReader::read };
iterates over the available History = KeepLast(k)
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
#pragma keylist Counter cID
sample instances
¨ Samples are not removed
from the local cache as 1 1 1 2 1 3 1 4
result of a read DataReader
2 1 2 2 2 3
3 1 3 2 3 3 3 4 3 5
¨ Read samples can be Topic
read again, by accessing
Samples Read Samples not Read
the cache with the
proper options (more DataReader Cache
later)

37. Tip #11
Read vs. Take struct Counter {
int cID;
QoS Settings int count;
};
¨ DataReader::take History = KeepLast(k)
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
#pragma keylist Counter cID
iterates over the
available sample
instances
1 1 1 2 1 3 1 4
Taken Samples are
2 1 2 2 2 3
¨ DataReader
3 1 3 2 3 3 3 4 3 5
removed from the Topic
local cache as result Samples not Taken
of a take
DataReader Cache

38. Tip #11
Read vs. Take struct Counter {
int cID;
QoS Settings int count;
};
¨ DataReader::take History = KeepLast(k)
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
#pragma keylist Counter cID
iterates over the
available sample
instances
1 2 1 3 1 4
Taken Samples are
2 2 2 3
¨ DataReader
3 2 3 3 3 4 3 5
removed from the Topic
local cache as result Samples not Taken
of a take
DataReader Cache

39. Tip #11
Read vs. Take struct Counter {
int cID;
QoS Settings int count;
};
¨ DataReader::take History = KeepLast(k)
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
#pragma keylist Counter cID
iterates over the
available sample
instances
1 3 1 4
Taken Samples are
2 3
¨ DataReader
3 3 3 4 3 5
removed from the Topic
local cache as result Samples not Taken
of a take
DataReader Cache

40. Tip #12
Sample, Instance, View State
History Depth = 2
¨ Along with data samples, DataReaders provides
state information allowing to detect relevant
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
1 1
transitions in the life-cycle of data as well as data
writers
2 2
3 ¨ Sample State (READ | NOT_READ): Determines
DataReader
SampleInfo wether a sample has already been read by this
DataReader or not.
1 1 1 2 ¨ Instance State (ALIVE, NOT_ALIVE, DISPOSED).
2 2 2 3 Determines wether (1) writer exist for the specific
3 1 instance, or (2) no matched writers are currently
Samples available, or (3) the instance has been disposed
Topic ¨ View State (NEW, NOT_NEW). Determines wether this
is the first sample of a new (or re-born) instance
DataReader Cache

41. Tip #13
Beware of Invalid Samples!
¨ For each data sample accessed via a read or take
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
DDS provides you with a SampleInfo
¨ The SampleInfo contains meta-information about the
Sample, such as timestamp, lifecycle information, etc.,
but most importantly tells you if the data is valid or not!
¨ Data is not valid, when the sample you are receiving
notifies things like an instance being unregistered or
disposed

42. Tip #14
Reading Only “Fresh” Data
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
dr.read(samples,
infos,
LENGTH_UNLIMITED, // read all available samples
NOT_READ_SAMPLE_STATE,
ANY_VIEW_STATE,
ALIVE_INSTANCE_STATE);

43. Tip #15
Reading All Data
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
dr.read(samples,
infos,
LENGTH_UNLIMITED, // read all available samples
ANY_SAMPLE_STATE,
ANY_VIEW_STATE,
ALIVE_INSTANCE_STATE);

44. Tip #16
Getting Everything
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
dr.read(samples,
infos,
LENGTH_UNLIMITED, // read all available samples
ANY_SAMPLE_STATE,
ANY_VIEW_STATE,
ANY_INSTANCE_STATE);
NOTE: As explained on the Tip #13 in this case you might get invalid data
samples, thus have to check on their validity via the
SampleInfo.valid_data attribute

45. Tip #17
Status vs. Read Condition
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
¨ Both a Status as well as a Read Condition can be
used to wait for data to be available on a
DataReader
¨ The main difference is that a ReadCondition allows
to set the exact SAMPLE, VIEW and INSTANCE status
for which the condition should trigger, while the
StatusCondition triggers when a sample is received

46. Tip #17
Status vs. Read Condition
Guidelines
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
¨ If what you really care is getting a condition that triggers
for the state ANY_SAMPLE_STATE, ANY_VIEW_STATE and
ANY_INSTANCE_STATE than use a StatusCondition as this
is more efficient than a ReadCondition
¨ If you are interested in having a condition that triggers
for specific a status then use the ReadCondition

47. Memory Management

48. Tip #18
Return Memory Loans
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
¨ The DataReader read/take allocate loan memory
to the application when the length of the containers
passed for storing samples and info is zero
¨ In this case the loaned memory must be returned
via a return_loan operation!

49. Return Memory Loans
Tip #18
Copyright
2010,
PrismTech
–
All
Rights
Reserved.

50. Tip #19
Beware of Strings Ownership
¨ The DDS C++ API takes ownership of the string you pass
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
¨ As a result, you need to understand when it is necessary
to “duplicate” a string
¨ To this end, DDS provides the DDS:string_dup call to
facilitate this task
subQos.partition.name.length (1);
subQos.partition.name[0] = DDS::string_dup (read_partition);

51. Concluding Tip

52. Tip #20
Read, Write, Ask
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
¨ Read the Manuals and if possible the Specification
¨ Write your own code examples
¨ Don’t be shy to ask questions on the OpenSplice
mailing list

53. :: Connect with Us ::
Copyright
2010,
PrismTech
–
All
Rights
Reserved.
¥ opensplice.com ¥ forums.opensplice.org
¥ @acorsaro
¥ opensplice.org ¥ opensplicedds@prismtech.com ¥ @prismtech
¥ crc@prismtech.com
¥ sales@prismtech.com
¥ youtube.com/opensplicetube ¥ slideshare.net/angelo.corsaro