20 tips for opensplice newbies

20 Tips for OpenSplice Newbies

Angelo Corsaro, Ph.D.Chief Technology Officer OMG DDS Sig [email protected]

mailto:[email protected]


Domain

Copyrig

ht 2010, PrismTech – A

ll Rights Reserved.

Domains, Partitions, Topics¨ All DDS applications publish

and subscribe data on a Partition belonging to a given domain

¨ Partitions are defined by means for strings and can be matched with regular expressions

¨ If not explicitly specified the default partition in the default domain is automatically chosen

Domain (e.g. Domain 123)

Partitions (e.g. Partition “Telemetry”)

Topic Instances/Samples

Tip #0

Copyrig


ll Rights Reserved.

Partitions Matching

Domain

building-1.floor-3.room-5

building-1.floor-1.room-111 building-1.floor15-.room-51

building-1.floor-3.room-11

building-1.floor-10.room-100building-1.floor-1.room-1

...

......"building-1.floor-1.room-*"

"building-1.floor-3.room-51"

"building-1.floor-*.room-11?"

¨ Partitions are defined by means for strings and can be matched with regular expressions]

Tip #0

Configuration 101

Copyrig


ll Rights Reserved.

Choosing a Domain¨ In OpenSplice DDS v5.x a domain is selected by:

¨ 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

Tip #1

Copyrig


ll Rights Reserved.

Choosing a Domain

$ ospl start file:///some/path/myospl.xml

dpf.create_participant( “file:///some/path/myospl.xml”, qos, listener, mask);

dpf.create_participant( “MyDomainNameAsSpecifiedOnTheXMLFile”, qos, listener, mask);

Tip #1

dpf.create_participant( “”, qos, listener, mask);

Defining Domain Configuration at Startup

Default Domain

Domain specified via URI

Domain specified via a Domain Name

Copyrig


ll Rights Reserved.

Domains on OpenSplice v6.x¨ The DDS specification did not originally define the type for the

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);

Tip #1

Copyrig


ll Rights Reserved.

Start OpenSplice First

¨ 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:

Tip #2

$ ospl start

Copyrig


ll Rights Reserved.

Shared Memory Size¨ OpenSplice DDS shared memory size is defined in its

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

Tip #3

Copyrig


ll Rights Reserved.

Linux¨ The default value for the maximum shared memory segment is

32MBytes

¨ This default can be changed in several ways

(1) Adding this line to your /etc/rc.d/rc.local file:

(2) Changing the settings for the sys-limits (save changes on /etc/sysctl.conf to maintain them across reboots):

echo “your_max_shared_memory_size” > /proc/sys/kernel/shmmax

$ sysctl -w kernel.shmmax=yourMaxValue

Tip #3

Copyrig


ll Rights Reserved.

Windows

¨ The default maximum size for Shared Memory segments on Windows is 2GB

¨ To exend it, say to 3GB, add the /3GB the boot.ini as shown below:

[boot loader]timeout=30default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS[operating systems]multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NTWorkstation Version 4.00" /3GB

Tip #3

DDS Topics

Copyrig


ll Rights Reserved.

Topic Types & Keys

¨ 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

Tip #4

Copyrig


ll Rights Reserved.

Topic Types & KeysTip #4

enum TemperatureScale { CELSIUS, FAHRENHEIT, KELVIN};

struct TempSensorType { short id; float temp; float hum; TemperatureScale scale;};#pragma keylist TempSensorType id

struct UniversalConstants { double PI; double e; // Nepero Number double g; // Gravitational Constant double NA; // Avogadro Number double F; // Faraday Constant double K; // Boltzman Constant double c; // Light Speed };#pragma keylist UniversalConstants

KeylessKeyful

Copyrig


ll Rights Reserved.

Topic InstancesTip #5

Writer Reader

1 26.0 70.0 CELSIUS

2 26.0 70.0 CELSIUS 1 26.0 70.0 CELSIUS

2 26.0 70.0 CELSIUS


struct TempSensorType { short id; float temp; float hum; TemperatureScale scale;};#pragma keylist TempSensorType

Copyrig


ll Rights Reserved.

Topic InstancesTip #5

Writer Reader

1 26.0 70.0 CELSIUS

2 26.0 70.0 CELSIUS1 26.0 70.0 CELSIUS 2 26.0 70.0 CELSIUS


struct TempSensorType { short id; float temp; float hum; TemperatureScale scale;};#pragma keylist TempSensorType id

Copyrig


ll Rights Reserved.

Topic Instances Lifecycle

com.myco.VPos

com.myco.VPos

Tip #6

struct VehiclePosition { string plate; long x; long y; };#pragma keylist VehiclePosition plate

struct VehiclePosition { string plate; long x; long y; };#pragma keylist VehiclePosition

Copyrig


ll Rights Reserved.


com.myco.VPos

com.myco.VPos

“A01” 100 200

“A01” 100 200

New

New

Tip #6



Copyrig


ll Rights Reserved.


“A01” 100 200

“B41” 57 31

com.myco.VPos

“A01” 100 200“B41” 57 31

com.myco.VPos

New

New

Tip #6



Copyrig


ll Rights Reserved.

“A01” 100 200“B41” 57 31

com.myco.VPos

“A01” 110 210


“A01” 100 200

“B41” 57 31

com.myco.VPos

“A01” 110 210New

New

Tip #6



Copyrig


ll Rights Reserved.

“A01” 100 200“B41” 57 31

com.myco.VPos

“A01” 110 210


“A01” 100 200

“B41” 57 31

com.myco.VPos

“A01” 110 210“A01” 120 220

“A01” 120 220

New

New

Tip #6

Copyrig


ll Rights Reserved.

“A01” 100 200“B41” 57 31

com.myco.VPos

“A01” 110 210


“A01” 100 200

“B41” 57 31

com.myco.VPos

“A01” 110 210“A01” 120 220

“A01” 120 220

“B41” 47 19

“B41” 47 19

New

New

Tip #6

Copyrig


ll Rights Reserved.

“A01” 100 200“B41” 57 31

com.myco.VPos

“A01” 110 210


“A01” 100 200

“B41” 57 31

com.myco.VPos

“A01” 110 210“A01” 120 220

“A01” 120 220

“B41” 47 19

“B41” 47 19

New

New“B41” - -Disposed

Tip #6

Copyrig


ll Rights Reserved.

Default Lifecycle Settings

¨ The WriterDataLifecycle controls when instances are 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!

Tip #7

Copyrig


ll Rights Reserved.

Understand the QoS Model¨ DDS defines 22 QoS

policies that can be applied to communication entities to control their local as well as end-to-end behaviour

Tip #8

HISTORY

LIFESPAN

DURABILITY

DEADLINE

LATENCY BUDGET

TRANSPORT PRIO

TIME-BASED FILTER

RESOURCE LIMITS

USER DATA

TOPIC DATA

GROUP DATA

OWENERSHIP

OWN. STRENGTH

LIVELINESS

ENTITY FACTORY

DW LIFECYCLE

DR LIFECYCLE

PRESENTATION

RELIABILITY

PARTITION

DEST. ORDER

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

Copyrig


ll Rights Reserved.

History + Reliability Interplay¨ The History QoS controls the number of samples that

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!

Tip #9

Copyrig


ll Rights Reserved.

History + Reliability InterplayTip #9

Topic

DataReader

1 1

2 1

3 1

History Depth = 1 (DDS Default)

DataReader Cache

Topic

1 2

2 3

3 1


DataWriter Cache

DataWriter1 2

2 2 2 3

Network

struct Counter { int cID; int count;};#pragma keylist Counter cID

Reliability = Reliable History = KeepLast(1)

QoS Settings

Copyrig


ll Rights Reserved.



Topic

DataReader

1 2

2 2

3 1


DataReader Cache

Topic

1 2

2 3

3 1


DataWriter Cache

DataWriter2 3

Network


QoS Settings

Copyrig


ll Rights Reserved.




QoS Settings

Topic

DataReader

1 2

2 3

3 1


DataReader Cache

Topic

1 2

2 3

3 1


DataWriter Cache

DataWriter

Network

Copyrig


ll Rights Reserved.

Define Resource Limits¨ DDS Provides a QoS that allow to control the amount of resources used by

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

Tip #7Tip #10

Accessing the Data

Copyrig


ll Rights Reserved.

Read vs. Take¨ DataReader::read

iterates over the available sample instances

¨ Samples are not removed from the local cache as result of a read

¨ Read samples can be read again, by accessing the cache with the proper options (more later)

DataReader Cache

Topic

DataReader

1 1

2 1

3 1

2 2

Samples Read Samples not Read

1 2 1 3 1 4

2 3

3 2 3 3 3 4 3 5

Tip #11

struct Counter { int cID; int count;};#pragma keylist Counter cIDHistory = KeepLast(k)

QoS Settings

Copyrig


ll Rights Reserved.

Read vs. TakeTip #11


QoS Settings

DataReader Cache

Topic

Samples Read Samples not Read

DataReader

1 1

2 1

3 1

2 2

1 2 1 3 1 4

2 3

3 2 3 3 3 4 3 5

¨ DataReader::read iterates over the available sample instances

¨ Samples are not removed from the local cache as result of a read

¨ Read samples can be read again, by accessing the cache with the proper options (more later)

Copyrig


ll Rights Reserved.

Read vs. Take¨ DataReader::take


¨ Taken Samples are removed from the local cache as result of a take

Tip #11


QoS Settings

DataReader Cache

Topic

DataReader

1 1

2 1

3 1

2 2

Samples not Taken

1 2 1 3 1 4

2 3

3 2 3 3 3 4 3 5

Copyrig


ll Rights Reserved.




Tip #11


QoS Settings

DataReader Cache

Topic

Samples not Taken

DataReader 2 2

1 2 1 3 1 4

2 3

3 2 3 3 3 4 3 5

Copyrig


ll Rights Reserved.




Tip #11


QoS Settings

DataReader Cache

Topic

Samples not Taken

DataReader

1 3 1 4

2 3

3 3 3 4 3 5

Copyrig


ll Rights Reserved.

Sample, Instance, View StateTip #12

DataReader

History Depth = 2

DataReader Cache

Samples

1 1

2 2

3 1

1 2

2 3

SampleInfo

1

2

3

1

2

Topic

¨ Along with data samples, DataReaders provides state information allowing to detect relevant transitions in the life-cycle of data as well as data writers

¨ Sample State (READ | NOT_READ): Determines wether a sample has already been read by this DataReader or not.

¨ Instance State (ALIVE, NOT_ALIVE, DISPOSED). Determines wether (1) writer exist for the specific instance, or (2) no matched writers are currently available, or (3) the instance has been disposed

¨ View State (NEW, NOT_NEW). Determines wether this is the first sample of a new (or re-born) instance

Copyrig


ll Rights Reserved.

Beware of Invalid Samples!¨ For each data sample accessed via a read or take

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

Tip #13

Copyrig


ll Rights Reserved.

Reading Only “Fresh” Data Tip #14

dr.read(samples, infos, LENGTH_UNLIMITED, // read all available samples NOT_READ_SAMPLE_STATE, ANY_VIEW_STATE, ALIVE_INSTANCE_STATE);

Copyrig


ll Rights Reserved.

Reading All Data Tip #15

dr.read(samples, infos, LENGTH_UNLIMITED, // read all available samples ANY_SAMPLE_STATE, ANY_VIEW_STATE, ALIVE_INSTANCE_STATE);

Copyrig


ll Rights Reserved.

Getting EverythingTip #16

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

Copyrig


ll Rights Reserved.

Status vs. Read Condition

¨ 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

Tip #17

Copyrig


ll Rights Reserved.

Status vs. Read Condition

Guidelines

¨ 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

Tip #17

Memory Management

Copyrig


ll Rights Reserved.

Return Memory Loans

¨ 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!

Tip #18

Copyrig


ll Rights Reserved.

Return Memory LoansTip #18

Copyrig


ll Rights Reserved.

Beware of Strings Ownership¨ The DDS C++ API takes ownership of the string you pass

¨ 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

Tip #19

subQos.partition.name.length (1); subQos.partition.name[0] = DDS::string_dup (read_partition);

Concluding Tip

Copyrig


ll Rights Reserved.

Read, Write, Ask

¨ 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

Tip #20

Copyrig


ll Rights Reserved.

:: Connect with Us ::

¥ @prismtech

¥ @acorsaro

¥ youtube.com/opensplicetube ¥ slideshare.net/angelo.corsaro

¥ [email protected]¥ [email protected]

¥ opensplice.com ¥ forums.opensplice.org

¥ opensplice.org ¥ [email protected]

http://www.slideshare.net/angelo.corsaro

http://www.slideshare.net/angelo.corsaro





http://www.opensplice.com




http://forums.opensplice.org/

http://forums.opensplice.org/

http://www.opensplice.org








20 tips for opensplice newbies

Technology

domain configuration

topics domain

default configuration

mask default domain

given domain partitions

default partition

uri copyright

participant file