RTI Connext

Core Libraries and Utilities

User’s Manual

Part 2 — Core Concepts

Chapters 3-9

Version 5.0

© 2012 Real-Time Innovations, Inc.

All rights reserved.

Printed in U.S.A. First printing.

August 2012.

Trademarks

Real-Time Innovations, RTI, DataBus, and Connext are trademarks or registered trademarks of Real-Time Innovations, Inc. All other trademarks used in this document are the property of their respective owners.

Copy and Use Restrictions

No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form (including electronic, mechanical, photocopy, and facsimile) without the prior written permission of Real- Time Innovations, Inc. The software described in this document is furnished under and subject to the RTI software license agreement. The software may be used or copied only under the terms of the license agreement.

Third-Party Copyright Notices

Note: In this section, "the Software" refers to third-party software, portions of which are used in Connext; "the Software" does not refer to Connext.

This product implements the DCPS layer of the Data Distribution Service (DDS) specification version 1.2 and the DDS Interoperability Wire Protocol specification version 2.1, both of which are owned by the Object Management, Inc. Copyright 1997-2007 Object Management Group, Inc. The publication of these specifications can be found at the Catalog of OMG Data Distribution Service (DDS) Specifications. This documentation uses material from the OMG specification for the Data Distribution Service, section 7. Reprinted with permission. Object Management, Inc. © OMG. 2005.

Portions of this product were developed using ANTLR (www.ANTLR.org). This product includes software developed by the University of California, Berkeley and its contributors.

Portions of this product were developed using AspectJ, which is distributed per the CPL license. AspectJ source code may be obtained from Eclipse. This product includes software developed by the University of California, Berkeley and its contributors.

Portions of this product were developed using MD5 from Aladdin Enterprises.

Portions of this product include software derived from Fnmatch, (c) 1989, 1993, 1994 The Regents of the University of California. All rights reserved. The Regents and contributors provide this software "as is" without warranty.

Portions of this product were developed using EXPAT from Thai Open Source Software Center Ltd and Clark Cooper Copyright (c) 1998, 1999, 2000 Thai Open Source Software Center Ltd and Clark Cooper Copyright (c) 2001, 2002 Expat maintainers. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

Technical Support

Real-Time Innovations, Inc.

232 E. Java Drive

Sunnyvale, CA 94089

Phone:

(408) 990-7444

Email:

support@rti.com

Website:

https://support.rti.com/

Contents, Part 2

3 Data Types and Data Samples

3-1

3.1 Introduction to the Type System

3-3

3.1.1

Sequences

3-4

3.1.2 Strings and Wide Strings

3-4

3.1.3

Introduction to TypeCode

3-4

 

3.1.3.1 Sending TypeCodes on the Network

3-5

3.2 Built-in Data Types

3-5

3.2.1

Registering Built-in Types

3-6

3.2.2 Creating Topics for Built-in Types

3-6

 

3.2.2.1

Topic Creation Examples

3-7

3.2.3 Creating ContentFilteredTopics for Built-in Types

3-8

 

3.2.3.1

ContentFilteredTopic Creation Examples

3-8

3.2.4

String Built-in Type

3-9

 

3.2.4.1 Creating and Deleting Strings

3-9

 

3.2.4.2

String DataWriter

3-10

 

3.2.4.3

String DataReader

3-11

3.2.5

KeyedString Built-in Type

3-13

 

3.2.5.1 Creating and Deleting Keyed Strings

3-14

 

3.2.5.2

Keyed String DataWriter

3-14

 

3.2.5.3

Keyed String DataReader

3-17

3.2.6

Octets Built-in Type

3-20

 

3.2.6.1 Creating and Deleting Octets

3-21

 

3.2.6.2

Octets DataWriter

3-21

 

3.2.6.3

Octets DataReader

3-23

3.2.7

KeyedOctets Built-in Type

3-26

 

3.2.7.1 Creating and Deleting KeyedOctets

3-26

 

3.2.7.2

Keyed Octets DataWriter

3-27

 

3.2.7.3

Keyed Octets DataReader

3-30

3.2.8 Managing Memory for Built-in Types

3-33

 

3.2.8.1 Examples—Setting the Maximum Size for a String Programmatically

3-34

3.2.9 Type Codes for Built-in Types

3-36

3.3 Creating User Data Types with IDL

3-37

3.3.1

Variable-Length Types

3-39

 

3.3.1.1

Sequences

3-39

 

3.3.1.2 Strings and Wide Strings

3-39

3.3.2

Value Types

3-40

iii

3.3.3

TypeCode and rtiddsgen

3-40

3.3.4 rtiddsgen Translations for IDL Types

3-41

3.3.5

Escaped Identifiers

3-54

3.3.6 Referring to Other IDL Files

3-55

3.3.7

Preprocessor Directives

3-55

3.3.8

Using Custom Directives

3-55

 

3.3.8.1

The @key Directive

3-56

 

3.3.8.2 The @copy and Related Directives

3-57

 

3.3.8.3

The @resolve-name Directive

3-58

 

3.3.8.4

The @top-level Directive

3-60

3.4 Creating User Data Types with Extensible Markup Language (XML)

3-61

3.5 Creating User Data Types with XML Schemas (XSD)

3-66

3.5.1

Primitive Types

3-78

3.6 Using rtiddsgen

3-78

3.6.1

rtiddsgen Command-Line Arguments

3-80

 

3.6.1.1

Optimizing Typedefs (-optimization)

3-83

3.7 Using Generated Types without Connext (Standalone)

3-85

3.7.1 Using Standalone Types in C

3-85

3.7.2 Using Standalone Types in C++

3-85

3.7.3 Standalone Types in Java

3-86

3.8 Interacting Dynamically with User Data Types

3-86

3.8.1

Introduction to TypeCode

3-86

3.8.2

Defining New Types

3-87

3.8.3 Sending Only a Few Fields

3-89

3.8.4 Type Extension and Versioning

3-90

3.8.5 Sending Type Codes on the Network

3-90

 

3.8.5.1 Type Codes for Built-in Types

3-91

3.9 Working with Data Samples

3-92

3.9.1 Objects of Concrete Types

3-92

3.9.2 Objects of Dynamically Defined Types

3-93

4 Entities

 

4-1

4.1 Common Operations for All Entities

4-2

4.1.1 Creating and Deleting Entities

4-2

4.1.2

Enabling Entities

4-3

 

4.1.2.1 Rules for Calling enable()

4-3

4.1.3 Getting an Entity’s Instance Handle

4-4

4.1.4 Getting Status and Status Changes

4-5

4.1.5 Getting and Setting Listeners

4-5

4.1.6

Getting the StatusCondition

4-5

4.1.7 Getting and Setting QosPolicies

4-6

 

4.1.7.1 Changing the QoS Defaults Used to Create Entities: set_default_*_qos()

4-6

 

4.1.7.2 Setting QoS During Entity Creation

4-7

 

4.1.7.3 Changing the QoS for an Existing Entity

4-8

 

4.1.7.4 Default Values

4-8

4.2 QosPolicies

4-9

4.2.1 QoS Requested vs. Offered Compatibility—the RxO Property

4-12

4.2.2 Special QosPolicy Handling Considerations for C

4-12

iv

4.3

Statuses

 

4-13

 

4.3.1 Types of Communication Status

4-14

 

 

4.3.1.1 Changes in Plain Communication Status

4-14

 

 

4.3.1.2 Changes in Read Communication Status

4-16

 

4.3.2 Special Status-Handling Considerations for C

4-18

4.4

Listeners

 

4-18

 

4.4.1

Types of Listeners

4-19

 

4.4.2 Creating and Deleting Listeners

4-20

 

4.4.3 Special Considerations for Listeners in C

4-20

 

4.4.4 Hierarchical Processing of Listeners

4-20

 

 

4.4.4.1 Processing Read Communication Statuses

4-21

 

4.4.5 Operations Allowed within Listener Callbacks

4-22

4.5

Exclusive Areas (EAs)

4-22

 

4.5.1 Restricted Operations in Listener Callbacks

4-25

4.6

Conditions and WaitSets

4-26

 

4.6.1 Creating and Deleting WaitSets

4-26

 

4.6.2

WaitSet Operations

4-28

 

4.6.3

Waiting for Conditions

4-28

 

 

4.6.3.1

How WaitSets Block

4-29

 

4.6.4 Processing Triggered Conditions—What to do when Wait() Returns

4-29

 

4.6.5 Conditions and WaitSet Example

4-30

 

4.6.6

GuardConditions

4-31

 

4.6.7

ReadConditions and QueryConditions

4-32

 

 

4.6.7.1 How ReadConditions are Triggered

4-32

 

 

4.6.7.2

QueryConditions

4-33

 

4.6.8

StatusConditions

4-33

 

 

4.6.8.1 How StatusConditions are Triggered

4-34

 

4.6.9 Using Both Listeners and WaitSets

4-35

5 Topics

 

 

5-1

5.1

Topics

 

 

5-1

 

5.1.1

Creating Topics

5-3

 

5.1.2

Deleting Topics

5-4

 

5.1.3

Setting Topic QosPolicies

5-4

 

 

5.1.3.1 Configuring QoS Settings when the Topic is Created

5-5

 

 

5.1.3.2 Changing QoS Settings After the Topic Has Been Created

5-6

 

5.1.4 Copying QoS From a Topic to a DataWriter or DataReader

5-7

 

5.1.5

Setting Up TopicListeners

5-7

 

5.1.6 Navigating Relationships Among Entities

5-7

 

 

5.1.6.1 Finding a Topic’s DomainParticipant

5-7

 

 

5.1.6.2 Retrieving a Topic’s Name or Type Name

5-8

5.2

Topic QosPolicies

5-8

 

5.2.1

TOPIC_DATA QosPolicy

5-8

 

 

5.2.1.1

Example

5-9

 

 

5.2.1.2

Properties

5-9

 

 

5.2.1.3

Related QosPolicies

5-9

 

 

5.2.1.4

Applicable Entities

5-9

 

 

5.2.1.5

System Resource Considerations

5-9

v

 

5.3 Status Indicator for Topics

5-9

 

 

5.3.1

INCONSISTENT_TOPIC Status

5-10

 

5.4

ContentFilteredTopics

5-10

 

 

5.4.1

Overview

5-10

 

 

5.4.2 Where Filtering is Applied—Publishing vs. Subscribing Side

5-11

 

 

5.4.3

Creating ContentFilteredTopics

5-12

 

 

5.4.4

Deleting ContentFilteredTopics

5-14

 

 

5.4.5

Using a ContentFilteredTopic

5-14

 

 

 

5.4.5.1

Getting the Current Expression Parameters

5-14

 

 

 

5.4.5.2

Setting Expression Parameters

5-14

 

 

 

5.4.5.3

Appending a String to an Expression Parameter

5-15

 

 

 

5.4.5.4

Removing a String from an Expression Parameter

5-15

 

 

 

5.4.5.5

Getting the Filter Expression

5-15

 

 

 

5.4.5.6

Getting the Related Topic

5-15

 

 

 

5.4.5.7

‘Narrowing’ a ContentFilteredTopic to a TopicDescription

5-16

 

 

5.4.6 SQL Filter Expression Notation

5-16

 

 

 

5.4.6.1

SQL Grammar

5-16

 

 

 

5.4.6.2

Token Expressions

5-17

 

 

 

5.4.6.3

Type Compatibility in the Predicate

5-19

 

 

 

5.4.6.4

SQL Extension: Regular Expression Matching

5-19

 

 

 

5.4.6.5

Composite Members

5-19

 

 

 

5.4.6.6

Strings

5-20

 

 

 

5.4.6.7

Enumerations

5-20

 

 

 

5.4.6.8

Pointers

5-20

 

 

 

5.4.6.9

Arrays

5-21

 

 

 

5.4.6.10

Sequences

5-21

 

 

 

5.4.6.11

Example SQL Filter Expressions

5-22

 

 

5.4.7 STRINGMATCH Filter Expression Notation

5-23

 

 

 

5.4.7.1

Example STRINGMATCH Filter Expressions

5-23

 

 

 

5.4.7.2

STRINGMATCH Filter Expression Parameters

5-23

 

 

5.4.8

Custom Content Filters

5-24

 

 

 

5.4.8.1

Filtering on the Writer Side with Custom Filters

5-24

 

 

 

5.4.8.2

Registering a Custom Filter

5-25

 

 

 

5.4.8.3

Unregistering a Custom Filter

5-26

 

 

 

5.4.8.4

Retrieving a ContentFilter

5-27

 

 

 

5.4.8.5

Compile Function

5-27

 

 

 

5.4.8.6

Evaluate Function

5-28

 

 

 

5.4.8.7

Finalize Function

5-28

 

 

 

5.4.8.8

Writer Attach Function

5-29

 

 

 

5.4.8.9

Writer Detach Function

5-29

 

 

 

5.4.8.10

Writer Compile Function

5-29

 

 

 

5.4.8.11

Writer Evaluate Function

5-29

 

 

 

5.4.8.12

Writer Return Loan Function

5-30

 

 

 

5.4.8.13

Writer Finalize Function

5-30

6

Sending Data

 

6-1

 

6.1 Preview: Steps to Sending Data

6-1

 

6.2

Publishers

 

6-2

 

 

6.2.1 Creating Publishers Explicitly vs. Implicitly

6-3

vi

6.2.2

Creating Publishers

6-5

6.2.3

Deleting Publishers

6-7

 

6.2.3.1

Deleting Contained DataWriters

6-7

6.2.4

Setting Publisher QosPolicies

6-7

 

6.2.4.1

Configuring QoS Settings when the Publisher is Created

6-8

 

6.2.4.2

Changing QoS Settings After the Publisher Has Been Created

6-10

 

6.2.4.3

Getting and Setting the Publisher’s Default QoS Profile and Library

6-11

 

6.2.4.4

Getting and Setting Default QoS for DataWriters

6-12

 

6.2.4.5

Other Publisher QoS-Related Operations

6-12

6.2.5

Setting Up PublisherListeners

6-13

6.2.6

Finding a Publisher’s Related Entities

6-14

6.2.7

Waiting for Acknowledgments in a Publisher

6-15

6.2.8

Statuses for Publishers

6-15

6.2.9

Suspending and Resuming Publications

6-15

6.3 DataWriters

 

6-15

6.3.1

Creating DataWriters

6-18

6.3.2

Getting All DataWriters

6-19

6.3.3

Deleting DataWriters

6-20

6.3.4

Setting Up DataWriterListeners

6-20

6.3.5

Checking DataWriter Status

6-21

6.3.6

Statuses for DataWriters

6-22

 

6.3.6.1

DATA_WRITER_CACHE_STATUS

6-22

 

6.3.6.2

DATA_WRITER_PROTOCOL_STATUS

6-22

 

6.3.6.3

LIVELINESS_LOST Status

6-25

 

6.3.6.4

OFFERED_DEADLINE_MISSED Status

6-25

 

6.3.6.5

OFFERED_INCOMPATIBLE_QOS Status

6-26

 

6.3.6.6

PUBLICATION_MATCHED Status

6-26

 

6.3.6.7

RELIABLE_WRITER_CACHE_CHANGED Status (DDS Extension)

6-27

 

6.3.6.8

RELIABLE_READER_ACTIVITY_CHANGED Status (DDS Extension)

6-28

6.3.7

Using a Type-Specific DataWriter (FooDataWriter)

6-28

6.3.8

Writing Data

6-29

 

6.3.8.1

Blocking During a write()

6-31

6.3.9

Flushing Batches of Data Samples

6-32

6.3.10 Writing Coherent Sets of Data Samples

6-32

6.3.11 Waiting for Acknowledgments in a DataWriter

6-33

6.3.12

Application Acknowledgment

6-33

 

6.3.12.1

Application Acknowledgment Kinds

6-34

 

6.3.12.2

Explicitly Acknowledging a Single Sample (C++)

6-34

 

6.3.12.3

Explicitly Acknowledging All Samples (C++)

6-34

 

6.3.12.4

Notification of Delivery with Application Acknowledgment

6-35

 

6.3.12.5

Application-Level Acknowledgment Protocol

6-35

 

6.3.12.6

Periodic and Non-Periodic AppAck Messages

6-36

 

6.3.12.7

Application Acknowledgment and Persistence Service

6-37

 

6.3.12.8

Application Acknowledgment and Routing Service

6-39

6.3.13

Required Subscriptions

6-39

 

6.3.13.1

Named, Required and Durable Subscriptions

6-40

 

6.3.13.2

Durability QoS and Required Subscriptions

6-40

 

6.3.13.3

Required Subscriptions Configuration

6-40

6.3.14 Managing Data Instances (Working with Keyed Data Types)

6-41

vii

 

6.3.14.1

Registering and Unregistering Instances

6-41

 

6.3.14.2

Disposing of Data

6-43

 

6.3.14.3

Looking Up an Instance Handle

6-43

 

6.3.14.4

Getting the Key Value for an Instance

6-43

6.3.15

Setting DataWriter QosPolicies

6-43

 

6.3.15.1

Configuring QoS Settings when the DataWriter is Created

6-46

 

6.3.15.2

Changing QoS Settings After the DataWriter Has Been Created

6-49

 

6.3.15.3

Using a Topic’s QoS to Initialize a DataWriter’s QoS

6-50

6.3.16 Navigating Relationships Among Entities

6-52

 

6.3.16.1

Finding Matching Subscriptions

6-52

 

6.3.16.2

Finding Related Entities

6-53

6.3.17

Asserting Liveliness

6-53

6.4 Publisher/Subscriber QosPolicies

6-53

6.4.1 ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension)

6-54

 

6.4.1.1

Properties

6-55

 

6.4.1.2

Related QosPolicies

6-55

 

6.4.1.3

Applicable Entities

6-55

 

6.4.1.4

System Resource Considerations

6-55

6.4.2

ENTITYFACTORY QosPolicy

6-55

 

6.4.2.1

Example

6-57

 

6.4.2.2

Properties

6-57

 

6.4.2.3

Related QosPolicies

6-57

 

6.4.2.4

Applicable Entities

6-57

 

6.4.2.5

System Resource Considerations

6-58

6.4.3 EXCLUSIVE_AREA QosPolicy (DDS Extension)

6-58

 

6.4.3.1

Example

6-59

 

6.4.3.2

Properties

6-59

 

6.4.3.3

Related QosPolicies

6-59

 

6.4.3.4

Applicable Entities

6-59

 

6.4.3.5

System Resource Considerations

6-59

6.4.4

GROUP_DATA QosPolicy

6-59

 

6.4.4.1

Example

6-60

 

6.4.4.2

Properties

6-60

 

6.4.4.3

Related QosPolicies

6-61

 

6.4.4.4

Applicable Entities

6-61

 

6.4.4.5

System Resource Considerations

6-61

6.4.5

PARTITION QosPolicy

6-62

 

6.4.5.1

Rules for PARTITION Matching

6-63

 

6.4.5.2

Pattern Matching for PARTITION Names

6-63

 

6.4.5.3

Example

6-64

 

6.4.5.4

Properties

6-66

 

6.4.5.5

Related QosPolicies

6-66

 

6.4.5.6

Applicable Entities

6-66

 

6.4.5.7

System Resource Considerations

6-66

6.4.6

PRESENTATION QosPolicy

6-67

 

6.4.6.1

Coherent Access

6-68

 

6.4.6.2

Ordered Access

6-68

 

6.4.6.3

Example

6-69

 

6.4.6.4

Properties

6-70

viii

 

6.4.6.5

Related QosPolicies

6-70

 

6.4.6.6

Applicable Entities

6-70

 

6.4.6.7

System Resource Considerations

6-71

6.5 DataWriter QosPolicies

6-71

6.5.1 AVAILABILITY QosPolicy (DDS Extension)

6-71

 

6.5.1.1

Availability QoS Policy and Collaborative DataWriters

6-72

 

6.5.1.2

Availability QoS Policy and Required Subscriptions

6-73

 

6.5.1.3

Properties

6-74

 

6.5.1.4

Related QosPolicies

6-74

 

6.5.1.5

Applicable Entities

6-74

 

6.5.1.6

System Resource Considerations

6-74

6.5.2 BATCH QosPolicy (DDS Extension)

6-75

 

6.5.2.1

Synchronous and Asynchronous Flushing

6-76

 

6.5.2.2

Batching vs. Coalescing

6-77

 

6.5.2.3

Batching and ContentFilteredTopics

6-78

 

6.5.2.4

Performance Considerations

6-78

 

6.5.2.5

Maximum Transport Datagram Size

6-78

 

6.5.2.6

Properties

6-78

 

6.5.2.7

Related QosPolicies

6-78

 

6.5.2.8

Applicable Entities

6-79

 

6.5.2.9

System Resource Considerations

6-79

6.5.3 DATA_WRITER_PROTOCOL QosPolicy (DDS Extension)

6-79

 

6.5.3.1

High and Low Watermarks

6-84

 

6.5.3.2

Normal, Fast, and Late-Joiner Heartbeat Periods

6-84

 

6.5.3.3

Disabling Positive Acknowledgements

6-85

 

6.5.3.4

Configuring the Send Window Size

6-86

 

6.5.3.5

Propagating Serialized Keys with Disposed-Instance Notifications

6-86

 

6.5.3.6

Virtual Heartbeats

6-87

 

6.5.3.7

Resending Over Multicast

6-87

 

6.5.3.8

Example

6-87

 

6.5.3.9

Properties

6-88

 

6.5.3.10

Related QosPolicies

6-88

 

6.5.3.11

Applicable Entities

6-88

 

6.5.3.12

System Resource Considerations

6-89

6.5.4 DATA_WRITER_RESOURCE_LIMITS QosPolicy (DDS Extension)

6-89

 

6.5.4.1

Example

6-90

 

6.5.4.2

Properties

6-90

 

6.5.4.3

Related QosPolicies

6-90

 

6.5.4.4

Applicable Entities

6-91

 

6.5.4.5

System Resource Considerations

6-91

6.5.5

DEADLINE QosPolicy

6-91

 

6.5.5.1

Example

6-92

 

6.5.5.2

Properties

6-92

 

6.5.5.3

Related QosPolicies

6-92

 

6.5.5.4

Applicable Entities

6-92

 

6.5.5.5

System Resource Considerations

6-93

6.5.6

DESTINATION_ORDER QosPolicy

6-93

 

6.5.6.1

Properties

6-94

 

6.5.6.2

Related QosPolicies

6-94

ix

 

6.5.6.3

Applicable Entities

6-94

 

6.5.6.4

System Resource Considerations

6-95

6.5.7

DURABILITY QosPolicy

6-95

 

6.5.7.1

Example

6-96

 

6.5.7.2

Properties

6-96

 

6.5.7.3

Related QosPolicies

6-96

 

6.5.7.4

Applicable Entities

6-97

 

6.5.7.5

System Resource Considerations

6-97

6.5.8

DURABILITY SERVICE QosPolicy

6-97

 

6.5.8.1

Properties

6-98

 

6.5.8.2

Related QosPolicies

6-98

 

6.5.8.3

Applicable Entities

6-99

 

6.5.8.4

System Resource Considerations

6-99

6.5.9 ENTITY_NAME QosPolicy (DDS Extension)

6-99

 

6.5.9.1

Properties

6-100

 

6.5.9.2

Related QosPolicies

6-100

 

6.5.9.3

Applicable Entities

6-100

 

6.5.9.4

System Resource Considerations

6-100

6.5.10

HISTORY QosPolicy

6-100

 

6.5.10.1

Example

6-102

 

6.5.10.2

Properties

6-102

 

6.5.10.3

Related QosPolicies

6-102

 

6.5.10.4

Applicable Entities

6-102

 

6.5.10.5

System Resource Considerations

6-103

6.5.11

LATENCYBUDGET QoS Policy

6-103

 

6.5.11.1

Applicable Entities

6-103

6.5.12

LIFESPAN QoS Policy

6-103

 

6.5.12.1

Properties

6-104

 

6.5.12.2

Related QoS Policies

6-104

 

6.5.12.3

Applicable Entities

6-104

 

6.5.12.4

System Resource Considerations

6-104

6.5.13

LIVELINESS QosPolicy

6-104

 

6.5.13.1

Example

6-106

 

6.5.13.2

Properties

6-106

 

6.5.13.3

Related QosPolicies

6-106

 

6.5.13.4

Applicable Entities

6-107

 

6.5.13.5

System Resource Considerations

6-107

6.5.14 MULTI_CHANNEL QosPolicy (DDS Extension)

6-107

 

6.5.14.1

Example

6-108

 

6.5.14.2

Properties

6-108

 

6.5.14.3

Related Qos Policies

6-109

 

6.5.14.4

Applicable Entities

6-109

 

6.5.14.5

System Resource Considerations

6-109

6.5.15

OWNERSHIP QosPolicy

6-109

 

6.5.15.1

How Connext Selects which DataWriter is the Exclusive Owner

6-110

 

6.5.15.2

Example

6-110

 

6.5.15.3

Properties

6-111

 

6.5.15.4

Related QosPolicies

6-111

 

6.5.15.5

Applicable Entities

6-111

 

6.5.15.6

System Resource Considerations

6-112

x

6.5.16

OWNERSHIP_STRENGTH QosPolicy

6-112

 

6.5.16.1

Example

6-112

 

6.5.16.2

Properties

6-112

 

6.5.16.3

Related QosPolicies

6-112

 

6.5.16.4

Applicable Entities

6-112

 

6.5.16.5

System Resource Considerations

6-112

6.5.17 PROPERTY QosPolicy (DDS Extension)

6-112

 

6.5.17.1

Properties

6-114

 

6.5.17.2

Related QosPolicies

6-114

 

6.5.17.3

Applicable Entities

6-114

 

6.5.17.4

System Resource Considerations

6-115

6.5.18 PUBLISH_MODE QosPolicy (DDS Extension)

6-115

 

6.5.18.1

Properties

6-117

 

6.5.18.2

Related QosPolicies

6-117

 

6.5.18.3

Applicable Entities

6-117

 

6.5.18.4

System Resource Considerations

6-117

6.5.19

RELIABILITY QosPolicy

6-117

 

6.5.19.1

Example

6-119

 

6.5.19.2

Properties

6-119

 

6.5.19.3

Related QosPolicies

6-120

 

6.5.19.4

Applicable Entities

6-120

 

6.5.19.5

System Resource Considerations

6-120

6.5.20

RESOURCE_LIMITS QosPolicy

6-120

 

6.5.20.1

Configuring Resource Limits for Asynchronous DataWriters

6-122

 

6.5.20.2

Configuring DataWriter Instance Replacement

6-122

 

6.5.20.3

Example

6-122

 

6.5.20.4

Properties

6-123

 

6.5.20.5

Related QosPolicies

6-123

 

6.5.20.6

Applicable Entities

6-123

 

6.5.20.7

System Resource Considerations

6-123

6.5.21

TRANSPORT_PRIORITY QosPolicy

6-123

 

6.5.21.1

Example

6-124

 

6.5.21.2

Properties

6-124

 

6.5.21.3

Related QosPolicies

6-124

 

6.5.21.4

Applicable Entities

6-124

 

6.5.21.5

System Resource Considerations

6-124

6.5.22 TRANSPORT_SELECTION QosPolicy (DDS Extension)

6-124

 

6.5.22.1

Example

6-125

 

6.5.22.2

Properties

6-125

 

6.5.22.3

Related QosPolicies

6-125

 

6.5.22.4

Applicable Entities

6-125

 

6.5.22.5

System Resource Considerations

6-125

6.5.23 TRANSPORT_UNICAST QosPolicy (DDS Extension)

6-125

 

6.5.23.1

Example

6-127

 

6.5.23.2

Properties

6-127

 

6.5.23.3

Related QosPolicies

6-127

 

6.5.23.4

Applicable Entities

6-127

 

6.5.23.5

System Resource Considerations

6-127

6.5.24 TYPESUPPORT QosPolicy (DDS Extension)

6-128

 

6.5.24.1

Properties

6-128

xi

 

 

 

6.5.24.2

Related QoS Policies

6-128

 

 

 

6.5.24.3

Applicable Entities

6-128

 

 

 

6.5.24.4

System Resource Considerations

6-128

 

 

6.5.25

USER_DATA QosPolicy

6-128

 

 

 

6.5.25.1

Example

6-129

 

 

 

6.5.25.2

Properties

6-129

 

 

 

6.5.25.3

Related QosPolicies

6-129

 

 

 

6.5.25.4

Applicable Entities

6-130

 

 

 

6.5.25.5

System Resource Considerations

6-130

 

 

6.5.26

WRITER_DATA_LIFECYCLE QoS Policy

6-130

 

 

 

6.5.26.1

Properties

6-131

 

 

 

6.5.26.2

Related QoS Policies

6-131

 

 

 

6.5.26.3

Applicable Entities

6-131

 

 

 

6.5.26.4

System Resource Considerations

6-132

 

6.6

FlowControllers (DDS Extension)

6-132

 

 

6.6.1 Flow Controller Scheduling Policies

6-133

 

 

6.6.2 Managing Fast DataWriters When Using a FlowController

6-134

 

 

6.6.3

Token Bucket Properties

6-134

 

 

 

6.6.3.1

max_tokens

6-135

 

 

 

6.6.3.2

tokens_added_per_period

6-135

 

 

 

6.6.3.3

tokens_leaked_per_period

6-135

 

 

 

6.6.3.4

period

6-135

 

 

 

6.6.3.5

bytes_per_token

6-136

 

 

6.6.4

Prioritized Samples

6-136

 

 

 

6.6.4.1

Designating Priorities

6-137

 

 

 

6.6.4.2

Priority-Based Filtering

6-137

 

 

6.6.5 Creating and Configuring Custom FlowControllers with Property QoS

6-138

 

 

 

6.6.5.1

Example

6-138

 

 

6.6.6 Creating and Deleting FlowControllers

6-140

 

 

6.6.7 Getting/Setting Default FlowController Properties

6-141

 

 

6.6.8 Getting/Setting Properties for a Specific FlowController

6-141

 

 

6.6.9 Adding an External Trigger

6-142

 

 

6.6.10

Other FlowController Operations

6-142

7

Receiving Data

7-1

 

7.1 Preview: Steps to Receiving Data

7-1

 

7.2

Subscribers

 

7-3

 

 

7.2.1 Creating Subscribers Explicitly vs. Implicitly

7-6

 

 

7.2.2

Creating Subscribers

7-6

 

 

7.2.3

Deleting Subscribers

7-7

 

 

 

7.2.3.1

Deleting Contained DataReaders

7-7

 

 

7.2.4

Setting Subscriber QosPolicies

7-8

 

 

 

7.2.4.1 Configuring QoS Settings when the Subscriber is Created

7-8

 

 

 

7.2.4.2

Changing QoS Settings After Subscriber Has Been Created

7-9

 

 

 

7.2.4.3

Getting and Settings the Subscriber’s Default QoS Profile and Library

7-11

 

 

 

7.2.4.4

Getting and Setting Default QoS for DataReaders

7-11

 

 

 

7.2.4.5

Subscriber QoS-Related Operations

7-12

 

 

7.2.5 Beginning and Ending Group-Ordered Access

7-12

 

 

7.2.6

Setting Up SubscriberListeners

7-13

xii

7.2.7 Getting DataReaders with Specific Samples

7-15

7.2.8 Finding a Subscriber’s Related Entities

7-15

7.2.9

Statuses for Subscribers

7-16

 

7.2.9.1

DATA_ON_READERS Status

7-16

7.3 DataReaders

 

7-16

7.3.1

Creating DataReaders

7-19

7.3.2

Getting All DataReaders

7-20

7.3.3

Deleting DataReaders

7-20

 

7.3.3.1

Deleting Contained ReadConditions

7-21

7.3.4

Setting Up DataReaderListeners

7-21

7.3.5 Checking DataReader Status and StatusConditions

7-22

7.3.6 Waiting for Historical Data

7-23

7.3.7

Statuses for DataReaders

7-23

 

7.3.7.1

DATA_AVAILABLE Status

7-24

 

7.3.7.2 DATA_READER_CACHE_STATUS

7-24

 

7.3.7.3 DATA_READER_PROTOCOL_STATUS

7-24

 

7.3.7.4

LIVELINESS_CHANGED Status

7-27

 

7.3.7.5

REQUESTED_DEADLINE_MISSED Status

7-28

 

7.3.7.6

REQUESTED_INCOMPATIBLE_QOS Status

7-28

 

7.3.7.7

SAMPLE_LOST Status

7-29

 

7.3.7.8

SAMPLE_REJECTED Status

7-30

 

7.3.7.9

SUBSCRIPTION_MATCHED Status

7-31

7.3.8

Setting DataReader QosPolicies

7-32

 

7.3.8.1 Configuring QoS Settings when the DataReader is Created

7-34

 

7.3.8.2 Changing QoS Settings After DataReader Has Been Created

7-34

 

7.3.8.3 Using a Topic’s QoS to Initialize a DataWriter’s QoS

7-35

7.3.9 Navigating Relationships Among Entities

7-36

 

7.3.9.1

Finding Matching Publications

7-36

 

7.3.9.2 Finding a DataReader’s Related Entities

7-37

 

7.3.9.3 Looking Up an Instance Handle

7-37

 

7.3.9.4 Getting the Key Value for an Instance

7-37

7.4 Using DataReaders to Access Data (Read & Take)

7-37

7.4.1 Using a Type-Specific DataReader (FooDataReader)

7-37

7.4.2 Loaning and Returning Data and SampleInfo Sequences

7-38

7.4.3 Accessing Data Samples with Read or Take

7-38

 

7.4.3.1

Read vs. Take

7-39

 

7.4.3.2 General Patterns for Accessing Data

7-41

 

7.4.3.3

read_next_sample and take_next_sample

7-41

 

7.4.3.4

read_instance and take_instance

7-42

 

7.4.3.5

read_next_instance and take_next_instance

7-42

 

7.4.3.6

read_w_condition and take_w_condition

7-43

 

7.4.3.7

read_instance_w_condition and take_instance_w_condition

7-44

 

7.4.3.8

read_next_instance_w_condition and take_next_instance_w_condition

7-44

7.4.4

Acknowledging Samples

7-44

7.4.5 The Sequence Data Structure

7-45

7.4.6

The SampleInfo Structure

7-46

 

7.4.6.1

Reception Timestamp

7-47

 

7.4.6.2

Sample States

7-47

 

7.4.6.3

View States

7-47

xiii

 

 

7.4.6.4

Instance States

7-47

 

 

7.4.6.5 Generation Counts and Ranks

7-48

 

 

7.4.6.6

Valid Data Flag

7-49

7.5

Subscriber QosPolicies

7-49

7.6

DataReader QosPolicies

7-49

 

7.6.1 DATA_READER_PROTOCOL QosPolicy (DDS Extension)

7-50

 

 

7.6.1.1

Receive Window Size

7-51

 

 

7.6.1.2 Round-Trip Time For Filtering Redundant NACKs

7-52

 

 

7.6.1.3

Example

7-53

 

 

7.6.1.4

Properties

7-53

 

 

7.6.1.5

Related QosPolicies

7-53

 

 

7.6.1.6

Applicable Entities

7-53

 

 

7.6.1.7

System Resource Considerations

7-54

 

7.6.2 DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension)

7-54

 

 

7.6.2.1

max_total_instances and max_instances

7-58

 

 

7.6.2.2

Example

7-58

 

 

7.6.2.3

Properties

7-58

 

 

7.6.2.4

Related QosPolicies

7-59

 

 

7.6.2.5

Applicable Entities

7-59

 

 

7.6.2.6

System Resource Considerations

7-59

 

7.6.3

READER_DATA_LIFECYCLE QoS Policy

7-59

 

 

7.6.3.1

Properties

7-60

 

 

7.6.3.2

Related QoS Policies

7-60

 

 

7.6.3.3

Applicable Entities

7-60

 

 

7.6.3.4

System Resource Considerations

7-60

 

7.6.4

TIME_BASED_FILTER QosPolicy

7-60

 

 

7.6.4.1

Example

7-62

 

 

7.6.4.2

Properties

7-62

 

 

7.6.4.3

Related QosPolicies

7-62

 

 

7.6.4.4

Applicable Entities

7-62

 

 

7.6.4.5

System Resource Considerations

7-62

 

7.6.5 TRANSPORT_MULTICAST QosPolicy (DDS Extension)

7-62

 

 

7.6.5.1

Example

7-64

 

 

7.6.5.2

Properties

7-64

 

 

7.6.5.3

Related QosPolicies

7-65

 

 

7.6.5.4

Applicable Entities

7-65

 

 

7.6.5.5

System Resource Considerations

7-65

 

7.6.6

TYPE_CONSISTENCY_ENFORCEMENT QosPolicy

7-65

 

 

7.6.6.1

Properties

7-67

 

 

7.6.6.2

Related QoS Policies

7-67

 

 

7.6.6.3

Applicable Entities

7-67

 

 

7.6.6.4

System Resource Considerations

7-67

8 Working with Domains

8-1

8.1

Fundamentals of Domains and DomainParticipants

8-1

8.2

DomainParticipantFactory

8-3

 

8.2.1 Setting DomainParticipantFactory QosPolicies

8-4

8.2.1.1Getting and Setting the DomainParticipantFactory’s Default QoS Profile and Library8-5

xiv

 

8.2.2

Getting and Setting Default QoS for DomainParticipants

8-5

 

8.2.3

Freeing Resources Used by the DomainParticipantFactory

8-6

 

8.2.4

Looking Up a DomainParticipant

8-6

 

8.2.5

Getting QoS Values from a QoS Profile

8-6

8.3

DomainParticipants

8-7

 

8.3.1

Creating a DomainParticipant

8-11

 

8.3.2

Deleting DomainParticipants

8-12

 

8.3.3

Deleting Contained Entities

8-12

 

8.3.4

Choosing a Domain ID and Creating Multiple Domains

8-13

 

8.3.5

Setting Up DomainParticipantListeners

8-13

 

8.3.6

Setting DomainParticipant QosPolicies

8-15

 

 

8.3.6.1

Configuring QoS Settings when the DomainParticipant is Created

8-16

 

 

8.3.6.2

Changing QoS Settings After the DomainParticipant Has Been Created

8-18

 

 

8.3.6.3

Getting and Setting the DomainParticipant’s Default QoS Profile and Library 8-

 

 

 

19

 

 

 

8.3.6.4

Getting and Setting Default QoS for Child Entities

8-19

 

8.3.7

Looking up Topic Descriptions

8-20

 

8.3.8

Finding a Topic

8-20

 

8.3.9

Getting the Implicit Publisher or Subscriber

8-21

 

8.3.10

Asserting Liveliness

8-22

 

8.3.11

Learning about Discovered DomainParticipants

8-22

 

8.3.12 Learning about Discovered Topics

8-22

 

8.3.13

Other DomainParticipant Operations

8-22

 

 

8.3.13.1

Verifying Entity Containment

8-22

 

 

8.3.13.2

Getting the Current Time

8-23

 

 

8.3.13.3

Getting All Publishers and Subscribers

8-23

8.4

DomainParticipantFactory QosPolicies

8-23

 

8.4.1

LOGGING QosPolicy (DDS Extension)

8-23

 

 

8.4.1.1

Example

8-23

 

 

8.4.1.2

Properties

8-24

 

 

8.4.1.3

Related QosPolicies

8-24

 

 

8.4.1.4

Applicable Entities

8-24

 

 

8.4.1.5

System Resource Considerations

8-24

 

8.4.2

PROFILE QosPolicy (DDS Extension)

8-24

 

 

8.4.2.1

Example

8-25

 

 

8.4.2.2

Properties

8-25

 

 

8.4.2.3

Related QosPolicies

8-25

 

 

8.4.2.4

Applicable Entities

8-25

 

 

8.4.2.5

System Resource Considerations

8-25

 

8.4.3

SYSTEM_RESOURCE_LIMITS QoS Policy (DDS Extension)

8-25

 

 

8.4.3.1

Example

8-26

 

 

8.4.3.2

Properties

8-26

 

 

8.4.3.3

Related QoS Policies

8-26

 

 

8.4.3.4

Applicable Entities

8-26

 

 

8.4.3.5

System Resource Considerations

8-26

8.5

DomainParticipant QosPolicies

8-27

 

8.5.1

DATABASE QosPolicy (DDS Extension)

8-27

 

 

8.5.1.1

Example

8-29

 

 

8.5.1.2

Properties

8-29

xv

8.5.1.3

Related QosPolicies

8-29

8.5.1.4

Applicable Entities

8-29

8.5.1.5

System Resource Considerations

8-29

8.5.2 DISCOVERY QosPolicy (DDS Extension)

8-29

8.5.2.1

Transports Used for Discovery

8-30

8.5.2.2

Setting the ‘Initial Peers’ List

8-30

8.5.2.3

Adding and Removing Peers List Entries

8-30

8.5.2.4

Configuring Multicast Receive Addresses

8-31

8.5.2.5

Meta-Traffic Transport Priority

8-31

8.5.2.6

Controlling Acceptance of Unknown Peers

8-31

8.5.2.7

Example

8-32

8.5.2.8

Properties

8-32

8.5.2.9

Related QosPolicies

8-32

8.5.2.10

Applicable Entities

8-33

8.5.2.11

System Resource Considerations

8-33

8.5.3 DISCOVERY_CONFIG QosPolicy (DDS Extension)

8-33

8.5.3.1

Resource Limits for Builtin-Topic DataReaders

8-36

8.5.3.2

Controlling Purging of Remote Participants

8-38

8.5.3.3Controlling the Reliable Protocol Used by Builtin-Topic DataWriters/ DataReaders8-39

8.5.3.4

Example

8-39

8.5.3.5

Properties

8-39

8.5.3.6

Related QosPolicies

8-39

8.5.3.7

Applicable Entities

8-39

8.5.3.8

System Resource Considerations

8-39

8.5.4 DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension)

8-40

8.5.4.1 Configuring Resource Limits for Asynchronous DataWriters

8-43

8.5.4.2

Configuring Memory Allocation

8-43

8.5.4.3

Example

8-44

8.5.4.4

Properties

8-44

8.5.4.5

Related QosPolicies

8-45

8.5.4.6

Applicable Entities

8-45

8.5.4.7

System Resource Considerations

8-45

8.5.5 EVENT QosPolicy (DDS Extension)

8-45

8.5.5.1

Example

8-46

8.5.5.2

Properties

8-46

8.5.5.3

Related QosPolicies

8-46

8.5.5.4

Applicable Entities

8-46

8.5.5.5

System Resource Considerations

8-46

8.5.6 RECEIVER_POOL QosPolicy (DDS Extension)

8-46

8.5.6.1

Example

8-47

8.5.6.2

Properties

8-47

8.5.6.3

Related QosPolicies

8-47

8.5.6.4

Applicable Entities

8-48

8.5.6.5

System Resource Considerations

8-48

8.5.7 TRANSPORT_BUILTIN QosPolicy (DDS Extension)

8-48

8.5.7.1

Example

8-48

8.5.7.2

Properties

8-48

8.5.7.3

Related QosPolicies

8-48

8.5.7.4

Applicable Entities

8-49

xvi

 

 

8.5.7.5

System Resource Considerations

8-49

 

8.5.8 TRANSPORT_MULTICAST_MAPPING QosPolicy (DDS Extension)

8-49

 

 

8.5.8.1 Formatting Rules for Addresses

8-50

 

 

8.5.8.2

Example

8-50

 

 

8.5.8.3

Properties

8-50

 

 

8.5.8.4

Related QosPolicies

8-50

 

 

8.5.8.5

Applicable Entities

8-50

 

 

8.5.8.6

System Resource Considerations

8-51

 

8.5.9 WIRE_PROTOCOL QosPolicy (DDS Extension)

8-51

 

 

8.5.9.1

Choosing Participant IDs

8-51

 

 

8.5.9.2 Host, App, and Instance IDs

8-52

 

 

8.5.9.3 Ports Used for Discovery

8-53

 

 

8.5.9.4 Controlling How the GUID is Set (rtps_auto_id_kind)

8-53

 

 

8.5.9.5

Example

8-55

 

 

8.5.9.6

Properties

8-56

 

 

8.5.9.7

Related QosPolicies

8-56

 

 

8.5.9.8

Applicable Entities

8-56

 

 

8.5.9.9

System Resource Considerations

8-56

8.6

Clock Selection

 

8-56

 

8.6.1

Available Clocks

8-56

 

8.6.2

Clock Selection Strategy

8-56

8.7

System Properties

8-57

9 Building Applications

9-1

9.1

Running on a Computer Not Connected to a Network

9-1

9.2

Connext Header Files — All Architectures

9-2

9.3

UNIX-Based Platforms

9-2

 

9.3.1

Required Libraries

9-3

 

9.3.2

Compiler Flags

9-3

9.4

Windows Platforms

9-3

 

9.4.1 Using Microsoft Visual C++ 6.0

9-4

 

9.4.2 Using Visual Studio .NET, Visual Studio .NET 2003, or Visual Studio 2005

9-5

9.5

Java Platforms

9-6

 

9.5.1

Java Libraries

9-6

 

9.5.2

Native Libraries

9-6

xvii

Chapter 3 Data Types and Data Samples

How data is stored or laid out in memory can vary from language to language, compiler to compiler, operating system to operating system, and processor to processor. This combination of language/compiler/operating system/processor is called a platform. Any modern middleware must be able to take data from one specific platform (say C/gcc.3.2.2/Solaris/Sparc) and transparently deliver it to another (for example, Java/JDK 1.6/Windows XP/Pentium). This process is commonly called serialization/deserialization, or marshalling/demarshalling.

Messaging products have typically taken one of two approaches to this problem:

1.Do nothing. Messages consist only of opaque streams of bytes. The JMS BytesMessage is an example of this approach.

2.Send everything, every time. Self-describing messages are at the opposite extreme, embedding full reflective information, including data types and field names, with each message. The JMS MapMessage and the messages in TIBCO Rendezvous are examples of this approach.

The “do nothing” approach is lightweight on its surface but forces you, the user of the middleware API, to consider all data encoding, alignment, and padding issues. The “send everything” alternative results in large amounts of redundant information being sent with every packet, impacting performance.

Connext takes an intermediate approach. Just as objects in your application program belong to some data type, data samples sent on the same Connext topic share a data type. This type defines the fields that exist in the data samples and what their constituent types are. The middleware stores and propagates this meta-information separately from the individual data samples, allowing it to propagate samples efficiently while handling byte ordering and alignment issues for you.

To publish and/or subscribe to data with Connext, you will carry out the following steps:

1.Select a type to describe your data.

You have a number of choices. You can choose one of these options, or you can mix and match them.

Use a built-in type provided by the middleware.

This option may be sufficient if your data typing needs are very simple. If your data is highly structured, or you need to be able to examine fields within that data for filtering or other purposes, this option may not be appropriate. The built-in types are described in Built-in Data Types (Section 3.2).

Use the RTI code generator, rtiddsgen, to define a type at compile-time using a language-independent description language.

3-1

Code generation offers two strong benefits not available with dynamic type definition: (1) it allows you to share type definitions across programming languages, and (2) because the structure of the type is known at compile time, it provides rigorous static type safety.

The code generator accepts input in a number of formats to make it easy to integrate Connext with your development processes and IT infrastructure:

OMG IDL. This format is a standard component of both the DDS and CORBA specifications. It describes data types with a C++-like syntax. This format is described in Creating User Data Types with IDL (Section 3.3).

XML schema (XSD), either independent or embedded in a WSDL file. XSD should be the format of choice for those using Connext alongside or connected to a web- services infrastructure. This format is described in Creating User Data Types with XML Schemas (XSD) (Section 3.5).

XML in a DDS-specific format. This XML format is terser, and therefore easier to read and write by hand, than an XSD file. It offers the general benefits of XML- extensibility and ease of integration, while fully supporting DDS-specific data types and concepts. This format is described in Creating User Data Types with Extensible Markup Language (XML) (Section 3.4).

Define a type programmatically at run time.

This method may be appropriate for applications with dynamic data description needs: applications for which types change frequently or cannot be known ahead of time. It is described in Defining New Types (Section 3.8.2).

2.Register your type with a logical name.

If you've chosen to use a built-in type instead of defining your own, you can omit this step; the middleware pre-registers the built-in types for you.

This step is described in the Defining New Types (Section 3.8.2).

3.Create a Topic using the type name you previously registered.

If you've chosen to use a built-in type instead of defining your own, you will use the API constant corresponding to that type's name.

Creating and working with Topics is discussed in Chapter 5: Topics.

4.Create one or more DataWriters to publish your data and one or more DataReaders to subscribe to it.

The concrete types of these objects depend on the concrete data type you've selected, in order to provide you with a measure of type safety.

Creating and working with DataWriters and DataReaders are described in Chapter 6: Sending Data and Chapter 7: Receiving Data, respectively.

Whether publishing or subscribing to data, you will need to know how to create and delete data samples and how to get and set their fields. These tasks are described in Working with Data Samples (Section 3.9).

This chapter describes:

Introduction to the Type System (Section 3.1 on Page 3-3)

Built-in Data Types (Section 3.2 on Page 3-5)

Creating User Data Types with IDL (Section 3.3 on Page 3-37)

Creating User Data Types with Extensible Markup Language (XML) (Section 3.4 on Page 3-61)

3-2

Creating User Data Types with XML Schemas (XSD) (Section 3.5 on Page 3-66)

Using rtiddsgen (Section 3.6 on Page 3-78)

Using Generated Types without Connext (Standalone) (Section 3.7 on Page 3-85)

Interacting Dynamically with User Data Types (Section 3.8 on Page 3-86)

Working with Data Samples (Section 3.9 on Page 3-92)

3.1Introduction to the Type System

A user data type is any custom type that your application defines for use with Connext. It may be a structure, a union, a value type, an enumeration, or a typedef (or language equivalents).

Your application can have any number of user data types. They can be composed of any of the primitive data types listed below or of other user data types.

Only structures, unions, and value types may be read and written directly by Connext; enums, typedefs, and primitive types must be contained within a structure, union, or value type. In order for a DataReader and DataWriter to communicate with each other, the data types associated with their respective Topic definitions must be identical.

octet, char, wchar

short, unsigned short

long, unsigned long

long long, unsigned long long

float

double, long double

boolean

enum (with or without explicit values)

bounded and unbounded string and wstring

The following type-building constructs are also supported:

module (also called a package or namespace)

pointer

array of primitive or user type elements

bounded/unbounded sequence of elements1—a sequence is a variable-length ordered collection, such as a vector or list

typedef

bitfield2

union

struct

value type, a complex type that supports inheritance and other object-oriented features

1.Sequences of sequences are not supported directly. To work around this constraint, typedef the inner sequence and form a sequence of that new type.

2.Data types containing bitfield members are not supported by DynamicData.

3-3

To use a data type with Connext, you must define that type in a way the middleware understands and then register the type with the middleware. These steps allow Connext to serialize, deserialize, and otherwise operate on specific types. They will be described in detail in the following sections.

3.1.1Sequences

A sequence contains an ordered collection of elements that are all of the same type. The operations supported in the sequence are documented in the API Reference HTML documentation, which is available for all supported programming languages (select Modules, DDS API Reference, Infrastructure Module, Sequence Support).

Java sequences implement the java.util.List interface from the standard Collections framework.

C++ users will find sequences conceptually similar to the deque class in the Standard Template Library (STL).

Elements in a sequence are accessed with their index, just like elements in an array. Indices start from zero. Unlike arrays, however, sequences can grow in size. A sequence has two sizes associated with it: a physical size (the "maximum") and a logical size (the "length"). The physical size indicates how many elements are currently allocated by the sequence to hold; the logical size indicates how many valid elements the sequence actually holds. The length can vary from zero up to the maximum. Elements cannot be accessed at indices beyond the current length.

A sequence may be declared as bounded or unbounded. A sequence's "bound" is the maximum number of elements tha tthe sequence can contain at any one time. The bound is very important because it allows Connext to preallocate buffers to hold serialized and deserialized samples of your types; these buffers are used when communicating with other nodes in your distributed system. If a sequence had no bound, Connext would not know how large to allocate its buffers and would therefore have to allocate them on the fly as individual samples were read and written—severely impacting the latency and determinism of your application. Therefore, Connext supports only bounded sequences; any unbounded sequences found in an IDL file will be given a default bound of 100 elements (see rtiddsgen Command-Line Arguments (Section 3.6.1)).

3.1.2Strings and Wide Strings

Connext supports both strings consisting of single-byte characters (the IDL string type) and strings consisting of wide characters (IDL wstring). The wide characters supported by Connext are four bytes long, large enough to store not only two-byte Unicode/UTF16 characters but also UTF32 characters.

Like sequences, strings may be bounded or unbounded. A string's "bound" is its maximum length (not counting the trailing NULL character in C and C++).

3.1.3Introduction to TypeCode

Type schemas—the names and definitions of a type and its fields—are represented by TypeCode objects. A type code value consists of a type code kind (see the TCKind enumeration below) and a list of members. For compound types like structs and arrays, this list will recursively include one or more type code values.

enum TCKind { TK_NULL, TK_SHORT, TK_LONG, TK_USHORT,

3-4

TK_ULONG,

TK_FLOAT,

TK_DOUBLE,

TK_BOOLEAN, TK_CHAR, TK_OCTET, TK_STRUCT, TK_UNION, TK_ENUM, TK_STRING, TK_SEQUENCE, TK_ARRAY, TK_ALIAS, TK_LONGLONG, TK_ULONGLONG, TK_LONGDOUBLE, TK_WCHAR, TK_WSTRING, TK_VALUE, TK_SPARSE

}

Type codes unambiguously match type representations and provide a more reliable test than comparing the string type names.

The TypeCode class, modeled after the corresponding CORBA API, provides access to type- code information. For details on the available operations for the TypeCode class, see the API Reference HTML documentation, which is available for all supported programming languages (select Modules, DDS API Reference, Topic Module, Type Code Support).

3.1.3.1Sending TypeCodes on the Network

In addition to being used locally, serialized type codes are typically published automatically during discovery as part of the built-in topics for publications and subscriptions. See Built-in DataReaders (Section 16.2). This allows applications to publish or subscribe to topics of arbitrary types. This functionality is useful for generic system monitoring tools like the rtiddsspy debug tool (see the API Reference HTML documentation).

Note: Type codes are not cached by Connext upon receipt and are therefore not available from the built-in data returned by the DataWriter's get_matched_subscription_data() operation or the

DataReader's get_matched_publication_data() operation.

If your data type has an especially complex type code, you may need to increase the value of the type_code_max_serialized_length field in the DomainParticipant's

DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4). Or, to prevent the propagation of type codes altogether, you can set this value to zero (0). Be aware that some features of monitoring tools, as well as some features of the middleware itself (such as ContentFilteredTopics) will not work correctly if you disable TypeCode propagation.

3.2Built-in Data Types

Connext provides a set of standard types that are built into the middleware. These types can be used immediately; they do not require writing IDL, invoking the rtiddsgen utility (see Section 3.6), or using the dynamic type API (see Section 3.2.8).

3-5

The supported built-in types are String, KeyedString, Octets, and KeyedOctets. (The latter two types are called Bytes and KeyedBytes, respectively, on Java and .NET platforms.)

The built-in type API is located under the DDS namespace in C++ and .NET. For Java, the API is contained inside the package com.rti.dds.type.builtin.

Built-in data types are discussed in the following sections:

Registering Built-in Types (Section 3.2.1)

Creating Topics for Built-in Types (Section 3.2.2)

Creating ContentFilteredTopics for Built-in Types (Section 3.2.3)

String Built-in Type (Section 3.2.4)

KeyedString Built-in Type (Section 3.2.5)

Octets Built-in Type (Section 3.2.6)

KeyedOctets Built-in Type (Section 3.2.7)

Type Codes for Built-in Types (Section 3.2.9)

3.2.1Registering Built-in Types

By default, the built-in types are automatically registered when a DomainParticipant is created. You can change this behavior by setting the DomainParticipant’s dds.builtin_type.auto_register property to 0 (false) using the PROPERTY QosPolicy (DDS Extension) (Section 6.5.17).

3.2.2Creating Topics for Built-in Types

To create a topic for a built-in type, just use the standard DomainParticipant operations, create_topic() or create_topic_with_profile() (see Creating Topics (Section 5.1.1)); for the type_name parameter, use the value returned by the get_type_name() operation, listed below for each API.

Note: In the following examples, you will see the sentinel "<BuiltinType>."

For C and C++: <BuiltinType> = String, KeyedString, Octets or KeyedOctets For Java and .NET1: <BuiltinType> = String, KeyedString, Bytes or KeyedBytes

C API:

const char* DDS_<BuiltinType>TypeSupport_get_type_name();

C++ API with namespace:

const char* DDS::<BuiltinType>TypeSupport::get_type_name();

C++ API without namespace:

const char* DDS<BuiltinType>TypeSupport::get_type_name();

C++/CLI API:

System::String^ DDS:<BuiltinType>TypeSupport::get_type_name();

C# API:

System.String DDS.<BuiltinType>TypeSupport.get_type_name();

1. RTI Connext .NET language binding is currently supported for C# and C++/CLI.

3-6

Java API:

String com.rti.dds.type.builtin.<BuiltinType>TypeSupport.get_type_name();

3.2.2.1Topic Creation Examples

For simplicity, error handling is not shown in the following examples.

C Example:

DDS_Topic * topic = NULL;

/* Create a builtin type Topic */

topic = DDS_DomainParticipant_create_topic( participant, "StringTopic",

DDS_StringTypeSupport_get_type_name(), &DDS_TOPIC_QOS_DEFAULT, NULL, DDS_STATUS_MASK_NONE);

C++ Example with Namespaces:

using namespace DDS;

...

/* Create a String builtin type Topic */ Topic * topic = participant->create_topic(

"StringTopic", StringTypeSupport::get_type_name(),

DDS_TOPIC_QOS_DEFAULT, NULL, DDS_STATUS_MASK_NONE);

C++/CLI Example:

using namespace DDS;

...

/* Create a builtin type Topic */

Topic^ topic = participant->create_topic(

"StringTopic", StringTypeSupport::get_type_name(), DomainParticipant::TOPIC_QOS_DEFAULT,

nullptr, StatusMask::STATUS_MASK_NONE);

C# Example:

using namespace DDS;

...

/* Create a builtin type Topic */

Topic topic = participant.create_topic(

"StringTopic", StringTypeSupport.get_type_name(), DomainParticipant.TOPIC_QOS_DEFAULT,

null, StatusMask.STATUS_MASK_NONE);

Java Example:

import com.rti.dds.type.builtin.*;

...

/* Create a builtin type Topic */

Topic topic = participant.create_topic(

"StringTopic", StringTypeSupport.get_type_name(), DomainParticipant.TOPIC_QOS_DEFAULT,

null, StatusKind.STATUS_MASK_NONE);

3-7

3.2.3Creating ContentFilteredTopics for Built-in Types

To create a ContentFilteredTopic for a built-in type, just use the standard DomainParticipant operations, create_contentfilteredtopic() or create_contentfilteredtopic_with_filter (see Section 5.4.3).

The field names used in the filter expressions for the built-in SQL (see Section 5.4.6) and StringMatch filters (see Section 5.4.7) must correspond to the names provided in the IDL description of the built-in types (see Section 3.2.4).

3.2.3.1ContentFilteredTopic Creation Examples

For simplicity, error handling is not shown in the following examples.

C Example:

DDS_Topic * topic = NULL;

DDS_ContentFilteredTopic * contentFilteredTopic = NULL; struct DDS_StringSeq parameters = DDS_SEQUENCE_INITIALIZER;

/* Create a string ContentFilteredTopic */ topic = DDS_DomainParticipant_create_topic(

participant, "StringTopic", DDS_StringTypeSupport_get_type_name(), &DDS_TOPIC_QOS_DEFAULT,NULL, DDS_STATUS_MASK_NONE);

contentFilteredTopic = DDS_DomainParticipant_create_contentfilteredtopic( participant, "StringContentFilteredTopic",

topic, "value = 'Hello World!'", & parameters);

C++ Example with Namespaces:

using namespace DDS;

...

/* Create a String ContentFilteredTopic */ Topic * topic = participant->create_topic(

"StringTopic", StringTypeSupport::get_type_name(), TOPIC_QOS_DEFAULT, NULL, STATUS_MASK_NONE);

StringSeq parameters;

ContentFilteredTopic * contentFilteredTopic = participant->create_contentfilteredtopic(

"StringContentFilteredTopic", topic, "value = 'Hello World!'", parameters);

C++/CLI Example:

using namespace DDS;

...

/* Create a String ContentFilteredTopic */ Topic^ topic = participant->create_topic(

"StringTopic", StringTypeSupport::get_type_name(), DomainParticipant::TOPIC_QOS_DEFAULT,

nullptr, StatusMask::STATUS_MASK_NONE);

StringSeq^ parameters = gcnew StringSeq();

3-8

ContentFilteredTopic^ contentFilteredTopic = participant->create_contentfilteredtopic(

"StringContentFilteredTopic", topic, "value = 'Hello World!'", parameters);

C# Example:

using namespace DDS;

...

/* Create a String ContentFilteredTopic */ Topic topic = participant.create_topic(

"StringTopic", StringTypeSupport.get_type_name(), DomainParticipant.TOPIC_QOS_DEFAULT,

null, StatusMask.STATUS_MASK_NONE);

StringSeq parameters = new StringSeq();

ContentFilteredTopic contentFilteredTopic = participant.create_contentfilteredtopic(

"StringContentFilteredTopic", topic, "value = 'Hello World!'", parameters);

Java Example:

import com.rti.dds.type.builtin.*;

...

/* Create a String ContentFilteredTopic */ Topic topic = participant.create_topic(

"StringTopic", StringTypeSupport.get_type_name(), DomainParticipant.TOPIC_QOS_DEFAULT,

null, StatusKind.STATUS_MASK_NONE);

StringSeq parameters = new StringSeq();

ContentFilteredTopic contentFilteredTopic = participant.create_contentfilteredtopic(

"StringContentFilteredTopic", topic, "value = 'Hello World!'", parameters);

3.2.4String Built-in Type

The String built-in type is represented by a NULL-terminated character array (char *) in C and C++ and an immutable String object in Java and .NET1. This type can be used to publish and subscribe to a single string.

3.2.4.1Creating and Deleting Strings

In C and C++, Connext provides a set of operations to create (DDS::String_alloc()), destroy (DDS::String_free()), and clone strings (DDS::String_dup()). Select Modules, DDS API Reference, Infrastructure Module, String support in the API Reference HTML documentation, which is available for all supported programming languages.

1. RTI Connext .NET language binding is currently supported for C# and C++/CLI.

3-9

Memory Considerations in Copy Operations:

When the read/take operations that take a sequence of strings as a parameter are used in copy mode, Connext allocates the memory for the string elements in the sequence if they are initialized to NULL.

If the elements are not initialized to NULL, the behavior depends on the language:

In Java and .NET, the memory associated with the elements is reallocated with every sample, because strings are immutable objects.

In C and C++, the memory associated with the elements must be large enough to hold the received data. Insufficient memory may result in crashes.

When take_next_sample() and read_next_sample() are called in C and C++, you must make sure that the input string has enough memory to hold the received data. Insufficient memory may result in crashes.

3.2.4.2String DataWriter

The string DataWriter API matches the standard DataWriter API (see Using a Type-Specific DataWriter (FooDataWriter) (Section 6.3.7)). There are no extensions.

The following examples show how to write simple strings with a string built-in type DataWriter. For simplicity, error handling is not shown.

C Example:

DDS_StringDataWriter * stringWriter = ... ; DDS_ReturnCode_t retCode;

char * str = NULL;

/* Write some data */

retCode = DDS_StringDataWriter_write(

stringWriter, "Hello World!", &DDS_HANDLE_NIL);

str = DDS_String_dup("Hello World!");

retCode = DDS_StringDataWriter_write(stringWriter, str, &DDS_HANDLE_NIL); DDS_String_free(str);

C++ Example with Namespaces:

#include "ndds/ndds_namespace_cpp.h" using namespace DDS;

...

StringDataWriter * stringWriter = ... ;

/* Write some data */

ReturnCode_t retCode = stringWriter->write("Hello World!", HANDLE_NIL); char * str = DDS::String_dup("Hello World!");

retCode = stringWriter->write(str, HANDLE_NIL);

DDS::String_free(str);

C++/CLI Example:

using namespace System; using namespace DDS;

...

StringDataWriter^ stringWriter = ... ;

/* Write some data */

3-10

stringWriter->write("Hello World!", InstanceHandle_t::HANDLE_NIL); String^ str = "Hello World!";

stringWriter->write(str, InstanceHandle_t::HANDLE_NIL);

C# Example:

using System; using DDS;

...

StringDataWriter stringWriter = ... ;

/* Write some data */

stringWriter.write("Hello World!", InstanceHandle_t.HANDLE_NIL); String str = "Hello World!";

stringWriter.write(str, InstanceHandle_t.HANDLE_NIL);

Java Example:

import com.rti.dds.publication.*; import com.rti.dds.type.builtin.*; import com.rti.dds.infrastructure.*;

...

StringDataWriter stringWriter = ... ;

/* Write some data */

stringWriter.write("Hello World!", InstanceHandle_t.HANDLE_NIL); String str = "Hello World!";

stringWriter.write(str, InstanceHandle_t.HANDLE_NIL);

3.2.4.3String DataReader

The string DataReader API matches the standard DataReader API (see Using a Type-Specific DataReader (FooDataReader) (Section 7.4.1)). There are no extensions.

The following examples show how to read simple strings with a string built-in type DataReader. For simplicity, error handling is not shown.

C Example:

struct DDS_StringSeq dataSeq = DDS_SEQUENCE_INITIALIZER; struct DDS_SampleInfoSeq infoSeq = DDS_SEQUENCE_INITIALIZER; DDS_StringDataReader * stringReader = ... ; DDS_ReturnCode_t retCode;

int i;

/* Take and print the data */

retCode = DDS_StringDataReader_take(stringReader, &dataSeq, &infoSeq, DDS_LENGTH_UNLIMITED, DDS_ANY_SAMPLE_STATE, DDS_ANY_VIEW_STATE, DDS_ANY_INSTANCE_STATE);

for (i = 0; i < DDS_StringSeq_get_length(&data_seq); ++i) {

if (DDS_SampleInfoSeq_get_reference(&info_seq, i)->valid_data) { DDS_StringTypeSupport_print_data(

DDS_StringSeq_get(&data_seq, i));

}

}

/* Return loan */

retCode = DDS_StringDataReader_return_loan(stringReader, &data_seq, &info_seq);

3-11

C++ Example with Namespaces:

#include "ndds/ndds_namespace_cpp.h" using namespace DDS;

...

StringSeq dataSeq;

SampleInfoSeq infoSeq;

StringDataReader * stringReader = ... ;

/* Take a print the data */

ReturnCode_t retCode = stringReader->take(dataSeq, infoSeq, LENGTH_UNLIMITED, ANY_SAMPLE_STATE, ANY_VIEW_STATE, ANY_INSTANCE_STATE);

for (int i = 0; i < data_seq.length(); ++i) { if (infoSeq[i].valid_data) {

StringTypeSupport::print_data(dataSeq[i]);

}

}

/* Return loan */

retCode = stringReader->return_loan(dataSeq, infoSeq);

C++/CLI Example:

using namespace System; using namespace DDS;

...

StringSeq^ dataSeq = gcnew StringSeq(); SampleInfoSeq^ infoSeq = gcnew SampleInfoSeq(); StringDataReader^ stringReader = ... ;

/* Take and print the data */ stringReader->take(dataSeq, infoSeq,

ResourceLimitsQosPolicy::LENGTH_UNLIMITED, SampleStateKind::ANY_SAMPLE_STATE, ViewStateKind::ANY_VIEW_STATE, InstanceStateKind::ANY_INSTANCE_STATE);

for (int i = 0; i < data_seq.length(); ++i) { if (infoSeq->get_at(i)->valid_data) {

StringTypeSupport::print_data(dataSeq->get_at(i));

}

}

/* Return loan */ stringReader->return_loan(dataSeq, infoSeq);

C# Example:

using System; using DDS;

...

StringSeq dataSeq = new StringSeq();

SampleInfoSeq infoSeq = new SampleInfoSeq();

StringDataReader stringReader = ... ;

3-12

/* Take and print the data */ stringReader.take(dataSeq, infoSeq,

ResourceLimitsQosPolicy.LENGTH_UNLIMITED, SampleStateKind.ANY_SAMPLE_STATE, ViewStateKind.ANY_VIEW_STATE, InstanceStateKind.ANY_INSTANCE_STATE);

for (int i = 0; i < data_seq.length(); ++i) { if (infoSeq.get_at(i)).valid_data) {

StringTypeSupport.print_data(dataSeq.get_at(i));

}

}

Java Example:

import com.rti.dds.infrastructure.*; import com.rti.dds.subscription.*; import com.rti.dds.type.builtin.*;

...

StringSeq dataSeq = new StringSeq();

SampleInfoSeq infoSeq = new SampleInfoSeq();

StringDataReader stringReader = ... ;

/* Take and print the data */ stringReader.take(dataSeq, infoSeq,

ResourceLimitsQosPolicy.LENGTH_UNLIMITED, SampleStateKind.ANY_SAMPLE_STATE, ViewStateKind.ANY_VIEW_STATE, InstanceStateKind.ANY_INSTANCE_STATE);

for (int i = 0; i < data_seq.length(); ++i) {

if (((SampleInfo)infoSeq.get(i)).valid_data) { System.out.println((String)dataSeq.get(i));

}

}

/* Return loan */ stringReader.return_loan(dataSeq, infoSeq);

3.2.5KeyedString Built-in Type

The Keyed String built-in type is represented by a (key, value) pair, where key and value are strings. This type can be used to publish and subscribe to keyed strings. The language specific representations of the type are as follows:

C/C++ Representation (without namespaces):

struct DDS_KeyedString { char * key;

char * value;

};

C++/CLI Representation:

namespace DDS {

public ref struct KeyedString: { public:

System::String^ key; System::String^ value;

...

};

3-13

};

C# Representation:

namespace DDS {

public class KeyedString { public System.String key; public System.String value;

};

};

Java Representation:

namespace DDS {

public class KeyedString { public System.String key; public System.String value;

};

};

3.2.5.1Creating and Deleting Keyed Strings

Connext provides a set of constructors/destructors to create/destroy Keyed Strings. For details, see the API Reference HTML documentation, which is available for all supported programming languages (select Modules, DDS API Reference, Topic Module, Built-in Types).

If you want to manipulate the memory of the fields 'value' and 'key' in the KeyedString struct in C/C++, use the operations DDS::String_alloc(), DDS::String_dup(), and DDS::String_free(), as described in the API Reference HTML documentation (select Modules, DDS API Reference, Infrastructure Module, String Support).

3.2.5.2Keyed String DataWriter

The keyed string DataWriter API is extended with the following methods (in addition to the standard methods described in Using a Type-Specific DataWriter (FooDataWriter) (Section 6.3.7)):

DDS::ReturnCode_t DDS::KeyedStringDataWriter::dispose( const char* key,

const DDS::InstanceHandle_t* instance_handle);

DDS::ReturnCode_t DDS::KeyedStringDataWriter::dispose_w_timestamp( const char* key,

const DDS::InstanceHandle_t* instance_handle, const struct DDS::Time_t* source_timestamp);

DDS::ReturnCode_t DDS::KeyedStringDataWriter::get_key_value( char * key,

const DDS::InstanceHandle_t* handle);

DDS::InstanceHandle_t DDS::KeyedStringDataWriter::lookup_instance(

const char * key);

DDS::InstanceHandle_t DDS::KeyedStringDataWriter::register_instance(

const char* key);

DDS::InstanceHandle_t

DDS_KeyedStringDataWriter::register_instance_w_timestamp(

const char * key,

const struct DDS_Time_t* source_timestamp);

3-14

DDS::ReturnCode_t DDS::KeyedStringDataWriter::unregister_instance( const char * key,

const DDS::InstanceHandle_t* handle);

DDS::ReturnCode_t DDS::KeyedStringDataWriter::unregister_instance_w_timestamp(

const char* key,

const DDS::InstanceHandle_t* handle,

const struct DDS::Time_t* source_timestamp);

DDS::ReturnCode_t DDS::KeyedStringDataWriter::write ( const char * key,

const char * str,

const DDS::InstanceHandle_t* handle);

DDS::ReturnCode_t DDS::KeyedStringDataWriter::write_w_timestamp( const char * key,

const char * str,

const DDS::InstanceHandle_t* handle,

const struct DDS::Time_t* source_timestamp);

These operations are introduced to provide maximum flexibility in the format of the input parameters for the write and instance management operations. For additional information and a complete description of the operations, see the API Reference HTML documentation, which is available for all supported programming languages.

The following examples show how to write keyed strings using a keyed string built-in type DataWriter and some of the extended APIs. For simplicity, error handling is not shown.

C Example:

DDS_KeyedStringDataWriter * stringWriter = ... ; DDS_ReturnCode_t retCode;

struct DDS_KeyedString * keyedStr = NULL; char * str = NULL;

/* Write some data using the KeyedString structure */ keyedStr = DDS_KeyedString_new(255, 255); strcpy(keyedStr->key, "Key 1"); strcpy(keyedStr->value, "Value 1");

retCode = DDS_KeyedStringDataWriter_write_string_w_key( stringWriter, keyedStr, &DDS_HANDLE_NIL);

DDS_KeyedString_delete(keyedStr);

/* Write some data using individual strings */

retCode = DDS_KeyedStringDataWriter_write_string_w_key( stringWriter, "Key 1", "Value 1", &DDS_HANDLE_NIL);

str = DDS_String_dup("Value 2");

retCode = DDS_KeyedStringDataWriter_write_string_w_key( stringWriter, "Key 1", str, &DDS_HANDLE_NIL);

DDS_String_free(str);

3-15

C++ Example with Namespaces:

#include "ndds/ndds_namespace_cpp.h" using namespace DDS;

...

KeyedStringDataWriter * stringWriter = ... ;

/* Write some data using the KeyedString */ KeyedString * keyedStr = new KeyedString(255, 255); strcpy(keyedStr->key, "Key 1"); strcpy(keyedStr->value, "Value 1");

ReturnCode_t retCode = stringWriter->write(keyedStr, HANDLE_NIL);

delete keyedStr;

#include "ndds/ndds_namespace_cpp.h" using namespace DDS;

...

KeyedStringDataWriter * stringWriter = ... ;

/* Write some data using the KeyedString */ KeyedString * keyedStr = new KeyedString(255, 255); strcpy(keyedStr->key, "Key 1"); strcpy(keyedStr->value, "Value 1");

ReturnCode_t retCode = stringWriter->write(keyedStr, HANDLE_NIL);

delete keyedStr;

C++/CLI Example:

using namespace System; using namespace DDS;

...

KeyedStringDataWriter^ stringWriter = ... ;

/* Write some data using the KeyedString */ KeyedString^ keyedStr = gcnew KeyedString(); keyedStr->key = "Key 1";

keyedStr->value = "Value 1";

stringWriter->write(keyedStr, InstanceHandle_t::HANDLE_NIL);

/* Write some data using individual strings */ stringWriter->write("Key 1","Value 1",InstanceHandle_t::HANDLE_NIL);

String^ str = "Value 2";

stringWriter->write("Key 1", str, InstanceHandle_t::HANDLE_NIL);

C# Example

using System; using DDS;

...

KeyedStringDataWriter stringWriter = ... ;

/* Write some data using the KeyedString */

3-16

KeyedString keyedStr = new KeyedString(); keyedStr.key = "Key 1";

keyedStr.value = "Value 1";

stringWriter.write(keyedStr, InstanceHandle_t.HANDLE_NIL);

/* Write some data using individual strings */ stringWriter.write("Key 1", "Value 1", InstanceHandle_t.HANDLE_NIL);

String str = "Value 2";

stringWriter.write("Key 1", str, InstanceHandle_t.HANDLE_NIL);

Java Example :

import com.rti.dds.publication.*; import com.rti.dds.type.builtin.*; import com.rti.dds.infrastructure.*;

...

KeyedStringDataWriter stringWriter = ... ;

/* Write some data using the KeyedString */ KeyedString keyedStr = new KeyedString(); keyedStr.key = "Key 1";

keyedStr.value = "Value 1";

stringWriter.write(keyedStr, InstanceHandle_t.HANDLE_NIL);

/* Write some data using individual strings */ stringWriter.write("Key 1", "Value 1", InstanceHandle_t.HANDLE_NIL);

String str = "Value 2";

stringWriter.write("Key 1", str, InstanceHandle_t.HANDLE_NIL);

3.2.5.3Keyed String DataReader

The KeyedString DataReader API is extended with the following operations (in addition to the standard methods described in Using a Type-Specific DataReader (FooDataReader) (Section 7.4.1)):

DDS::ReturnCode_t DDS::KeyedStringDataReader::get_key_value(

char * key, const DDS::InstanceHandle_t* handle);

DDS::InstanceHandle_t DDS::KeyedStringDataReader::lookup_instance(

const char * key);

For additional information and a complete description of these operations in all supported languages, see the API Reference HTML documentation, which is available for all supported programming languages.

Memory considerations in copy operations:

For read/take operations with copy semantics, such as read_next_sample() and take_next_sample(), Connext allocates memory for the fields 'value' and 'key' if they are initialized to NULL.

If the fields are not initialized to NULL, the behavior depends on the language:

In Java and .NET, the memory associated to the fields 'value' and 'key' will be reallocated with every sample.

3-17

In C and C++, the memory associated with the fields 'value' and 'key' must be large enough to hold the received data. Insufficient memory may result in crashes.

The following examples show how to read keyed strings with a keyed string built-in type DataReader. For simplicity, error handling is not shown.

C Example:

struct DDS_KeyedStringSeq dataSeq = DDS_SEQUENCE_INITIALIZER; struct DDS_SampleInfoSeq infoSeq = DDS_SEQUENCE_INITIALIZER; DDS_KeyedKeyedStringDataReader * stringReader = ... ; DDS_ReturnCode_t retCode;

int i;

/* Take and print the data */

retCode = DDS_KeyedStringDataReader_take(stringReader, &dataSeq, &infoSeq, DDS_LENGTH_UNLIMITED, DDS_ANY_SAMPLE_STATE, DDS_ANY_VIEW_STATE, DDS_ANY_INSTANCE_STATE);

for (i = 0; i < DDS_KeyedStringSeq_get_length(&data_seq); ++i) {

if (DDS_SampleInfoSeq_get_reference(&info_seq, i)->valid_data) { DDS_KeyedStringTypeSupport_print_data(

DDS_KeyedStringSeq_get_reference(&data_seq, i));

}

}

/* Return loan */

retCode = DDS_KeyedStringDataReader_return_loan( stringReader, &data_seq, &info_seq);

C++ Example with Namespaces:

#include "ndds/ndds_namespace_cpp.h" using namespace DDS;

...

KeyedStringSeq dataSeq;

SampleInfoSeq infoSeq;

KeyedStringDataReader * stringReader = ... ;

/* Take a print the data */

ReturnCode_t retCode = stringReader->take(dataSeq, infoSeq, LENGTH_UNLIMITED, ANY_SAMPLE_STATE, ANY_VIEW_STATE, ANY_INSTANCE_STATE);

for (int i = 0; i < data_seq.length(); ++i) { if (infoSeq[i].valid_data) {

KeyedStringTypeSupport::print_data(&dataSeq[i]);

}

}

/* Return loan */

retCode = stringReader->return_loan(dataSeq, infoSeq);

3-18

C++/CLI Example:

using namespace System; using namespace DDS;

...

KeyedStringSeq^ dataSeq = gcnew KeyedStringSeq();

SampleInfoSeq^ infoSeq = gcnew SampleInfoSeq();

KeyedStringDataReader^ stringReader = ... ;

/* Take and print the data */ stringReader->take(dataSeq, infoSeq,

ResourceLimitsQosPolicy::LENGTH_UNLIMITED, SampleStateKind::ANY_SAMPLE_STATE, ViewStateKind::ANY_VIEW_STATE, InstanceStateKind::ANY_INSTANCE_STATE);

for (int i = 0; i < data_seq.length(); ++i) { if (infoSeq->get_at(i)->valid_data) {

KeyedStringTypeSupport::print_data(dataSeq->get_at(i));

}

}

/* Return loan */ stringReader->return_loan(dataSeq, infoSeq);

C# Example:

using System; using DDS;

...

KeyedStringSeq dataSeq = new KeyedStringSeq();

SampleInfoSeq infoSeq = new SampleInfoSeq();

KeyedStringDataReader stringReader = ... ;

/* Take and print the data */ stringReader.take(dataSeq, infoSeq,

ResourceLimitsQosPolicy.LENGTH_UNLIMITED, SampleStateKind.ANY_SAMPLE_STATE, ViewStateKind.ANY_VIEW_STATE, InstanceStateKind.ANY_INSTANCE_STATE);

for (int i = 0; i < data_seq.length(); ++i) { if (infoSeq.get_at(i)).valid_data) {

KeyedStringTypeSupport.print_data(dataSeq.get_at(i));

}

}

/* Return loan */ stringReader.return_loan(dataSeq, infoSeq);

Java Example:

import com.rti.dds.infrastructure.*; import com.rti.dds.subscription.*; import com.rti.dds.type.builtin.*;

...

KeyedStringSeq dataSeq = new KeyedStringSeq();

SampleInfoSeq infoSeq = new SampleInfoSeq();

KeyedStringDataReader stringReader = ... ;

3-19

/* Take and print the data */ stringReader.take(dataSeq, infoSeq,

ResourceLimitsQosPolicy.LENGTH_UNLIMITED, SampleStateKind.ANY_SAMPLE_STATE, ViewStateKind.ANY_VIEW_STATE, InstanceStateKind.ANY_INSTANCE_STATE);

for (int i = 0; i < data_seq.length(); ++i) {

if (((SampleInfo)infoSeq.get(i)).valid_data) { System.out.println((

(KeyedString)dataSeq.get(i)).toString());

}

}

/* Return loan */ stringReader.return_loan(dataSeq, infoSeq);

3.2.6Octets Built-in Type

The octets built-in type is used to send sequences of octets. The language-specific representations are as follows:

C/C++ Representation (without Namespaces):

struct DDS_Octets { int length;

unsigned char * value;

};

C++/CLI Representation:

namespace DDS {

public ref struct Bytes: { public:

System::Int32 length; System::Int32 offset; array<System::Byte>^ value;

...

};

};

C# Representation:

namespace DDS {

public class Bytes {

public System.Int32 length; public System.Int32 offset; public System.Byte[] value;

...

};

};

Java Representation:

package com.rti.dds.type.builtin;

public class Bytes implements Copyable { public int length;

public int offset; public byte[] value;

...

};

3-20

3.2.6.1Creating and Deleting Octets

Connext provides a set of constructors/destructors to create and destroy Octet objects. For details, see the API Reference HTML documentation, which is available for all supported programming languages (select Modules, DDS API Reference, Topic Module, Built-in Types).

If you want to manipulate the memory of the value field inside the Octets struct in C/C++, use the operations DDS::OctetBuffer_alloc(), DDS::OctetBuffer_dup(), and

DDS::OctetBuffer_free(), described in the API Reference HTML documentation (select

Modules, DDS API Reference, Infrastructure Module, Octet Buffer Support).

3.2.6.2Octets DataWriter

In addition to the standard methods (see Using a Type-Specific DataWriter (FooDataWriter) (Section 6.3.7)), the octets DataWriter API is extended with the following methods:

DDS::ReturnCode_t DDS::OctetsDataWriter::write(

const DDS::OctetSeq & octets,

const DDS::InstanceHandle_t & handle);

DDS::ReturnCode_t DDS::OctetsDataWriter::write(

const unsigned char * octets, int length,

const DDS::InstanceHandle_t& handle);

DDS::ReturnCode_t DDS::OctetsDataWriter::write_w_timestamp( const DDS::OctetSeq & octets,

const DDS::InstanceHandle_t & handle, const DDS::Time_t & source_timestamp);

DDS::ReturnCode_t DDS::OctetsDataWriter::write_w_timestamp( const unsigned char * octets, int length,

const DDS::InstanceHandle_t& handle, const DDS::Time_t& source_timestamp);

These methods are introduced to provide maximum flexibility in the format of the input parameters for the write operations. For additional information and a complete description of these operations in all supported languages, see the API Reference HTML documentation.

The following examples show how to write an array of octets using an octets built-in type DataWriter and some of the extended APIs. For simplicity, error handling is not shown.

C Example:

DDS_OctetsDataWriter * octetsWriter = ... ; DDS_ReturnCode_t retCode;

struct DDS_Octets * octets = NULL; char * octetArray = NULL;

/* Write some data using the Octets structure */ octets = DDS_Octets_new_w_size(1024); octets->length = 2;

octets->value[0] = 46; octets->value[1] = 47;

retCode = DDS_OctetsDataWriter_write(octetsWriter, octets, &DDS_HANDLE_NIL);

DDS_Octets_delete(octets);

/* Write some data using an octets array */

3-21

octetArray = (unsigned char *)malloc(1024); octetArray[0] = 46;

octetArray[1] = 47;

retCode = DDS_OctetsDataWriter_write_octets (octetsWriter, octetArray, 2, &DDS_HANDLE_NIL);

free(octetArray);

C++ Example with Namespaces:

#include "ndds/ndds_namespace_cpp.h" using namespace DDS;

...

OctetsDataWriter * octetsWriter = ... ;

/* Write some data using the Octets structure */ Octets * octets = new Octets(1024); octets->length = 2;

octets->value[0] = 46; octets->value[1] = 47;

ReturnCode_t retCode = octetsWriter->write(octets, HANDLE_NIL);

delete octets;

/* Write some data using an octet array */

unsigned char * octetArray = new unsigned char[1024]; octetArray[0] = 46;

octetArray[1] = 47;

retCode = octetsWriter->write(octetArray, 2, HANDLE_NIL);

delete []octetArray;

C++/CLI Example:

using namespace System; using namespace DDS;

...

BytesDataWriter^ octetsWriter = ...;

/* Write some data using Bytes */ Bytes^ octets = gcnew Bytes(1024); octets->value[0] =46; octets->value[1] =47; octets.length = 2;

octets.offset = 0;

octetWriter->write(octets, InstanceHandle_t::HANDLE_NIL);

/* Write some data using individual strings */ array<Byte>^ octetAray = gcnew array<Byte>(1024); octetArray[0] = 46;

octetArray[1] = 47;

octetsWriter->write(octetArray, 0, 2, InstanceHandle_t::HANDLE_NIL);

C# Example:

using System; using DDS;

...

3-22

BytesDataWriter stringWriter = ...;

/* Write some data using the Bytes */ Bytes octets = new Bytes(1024); octets.value[0] = 46; octets.value[1] = 47;

octets.length = 2; octets.offset = 0;

octetWriter.write(octets, InstanceHandle_t.HANDLE_NIL);

/* Write some data using individual strings */ byte[] octetArray = new byte[1024]; octetArray[0] = 46;

octetArray[1] = 47;

octetsWriter.write(octetArray, 0, 2, InstanceHandle_t.HANDLE_NIL);

Java Example:

import com.rti.dds.publication.*; import com.rti.dds.type.builtin.*; import com.rti.dds.infrastructure.*;

...

BytesDataWriter octetsWriter = ... ;

/* Write some data using the Bytes class*/ Bytes octets = new Bytes(1024); octets.length = 2;

octets.offset = 0; octets.value[0] = 46; octets.value[1] = 47;

octetsWriter.write(octets, InstanceHandle_t.HANDLE_NIL);

/* Write some data using a byte array */ byte[] octetArray = new byte[1024]; octetArray[0] = 46;

octetArray[1] = 47;

octetsWriter.write(octetArray, 0, 2, InstanceHandle_t.HANDLE_NIL);

3.2.6.3Octets DataReader

The octets DataReader API matches the standard DataReader API (see Using a Type-Specific DataReader (FooDataReader) (Section 7.4.1)). There are no extensions.

Memory considerations in copy operations:

For read/take operations with copy semantics, such as read_next_sample() and take_next_sample(), Connext allocates memory for the field 'value' if it is initialized to NULL.

If the field 'value' is not initialized to NULL, the behavior depends on the language:

In Java and .NET, the memory for the field 'value' will be reallocated if the current size is not large enough to hold the received data.

In C and C++, the memory associated with the field 'value' must be big enough to hold the received data. Insufficient memory may result in crashes.

3-23

The following examples show how to read octets with an octets built-in type DataReader. For simplicity, error handling is not shown.

C Example:

struct DDS_OctetsSeq dataSeq = DDS_SEQUENCE_INITIALIZER; struct DDS_SampleInfoSeq infoSeq = DDS_SEQUENCE_INITIALIZER; DDS_OctetsDataReader * octetsReader = ... ; DDS_ReturnCode_t retCode;

int i;

/* Take and print the data */

retCode = DDS_OctetsDataReader_take(octetsReader, &dataSeq, &infoSeq, DDS_LENGTH_UNLIMITED, DDS_ANY_SAMPLE_STATE, DDS_ANY_VIEW_STATE, DDS_ANY_INSTANCE_STATE);

for (i = 0; i < DDS_OctetsSeq_get_length(&dataSeq); ++i) {

if (DDS_SampleInfoSeq_get_reference(&infoSeq, i)->valid_data) { DDS_OctetsTypeSupport_print_data(

DDS_OctetsSeq_get_reference(&dataSeq, i));

}

}

/* Return loan */ retCode =

DDS_OctetsDataReader_return_loan(octetsReader, &dataSeq, &infoSeq);

C++ Example with Namespaces:

#include "ndds/ndds_namespace_cpp.h" using namespace DDS;

...

OctetsSeq dataSeq; SampleInfoSeq infoSeq;

OctetsDataReader * octetsReader = ... ;

/* Take a print the data */

ReturnCode_t retCode = octetsReader->take(dataSeq, infoSeq, LENGTH_UNLIMITED, ANY_SAMPLE_STATE, ANY_VIEW_STATE,ANY_INSTANCE_STATE);

for (int i = 0; i < data_seq.length(); ++i) { if (infoSeq[i].valid_data) {

OctetsTypeSupport::print_data(&dataSeq[i]);

}

}

/* Return loan */

retCode = octetsReader->return_loan(dataSeq, infoSeq);

C++/CLI Example:

using namespace System; using namespace DDS;

...

BytesSeq^ dataSeq = gcnew BytesSeq();

SampleInfoSeq^ infoSeq = gcnew SampleInfoSeq();

BytesDataReader^ octetsReader = ... ;

/* Take and print the data */

3-24

octetsReader->take(dataSeq, infoSeq, ResourceLimitsQosPolicy::LENGTH_UNLIMITED, SampleStateKind::ANY_SAMPLE_STATE, ViewStateKind::ANY_VIEW_STATE, InstanceStateKind::ANY_INSTANCE_STATE);

for (int i = 0; i < data_seq.length(); ++i) { if (infoSeq->get_at(i)->valid_data) {

BytesTypeSupport::print_data(dataSeq->get_at(i));

}

}

/* Return loan */ octetsReader->return_loan(dataSeq, infoSeq);

C# Example:

using System; using DDS;

...

BytesSeq dataSeq = new BytesSeq(); SampleInfoSeq infoSeq = new SampleInfoSeq(); BytesDataReader octetsReader = ... ;

/* Take and print the data */ octetsReader.take(dataSeq, infoSeq,

ResourceLimitsQosPolicy.LENGTH_UNLIMITED, SampleStateKind.ANY_SAMPLE_STATE, ViewStateKind.ANY_VIEW_STATE, InstanceStateKind.ANY_INSTANCE_STATE);

for (int i = 0; i < data_seq.length(); ++i) { if (infoSeq.get_at(i)).valid_data) {

BytesTypeSupport.print_data(dataSeq.get_at(i));

}

}

/* Return loan */ octetsReader.return_loan(dataSeq, infoSeq);

Java Example:

import com.rti.dds.infrastructure.*; import com.rti.dds.subscription.*; import com.rti.dds.type.builtin.*;

...

BytesSeq dataSeq = new BytesSeq(); SampleInfoSeq infoSeq = new SampleInfoSeq(); BytesDataReader octetsReader = ... ;

/* Take and print the data */ octetsReader.take(dataSeq, infoSeq,

ResourceLimitsQosPolicy.LENGTH_UNLIMITED, SampleStateKind.ANY_SAMPLE_STATE, ViewStateKind.ANY_VIEW_STATE, InstanceStateKind.ANY_INSTANCE_STATE);

for (int i = 0; i < data_seq.length(); ++i) {

if (((SampleInfo)infoSeq.get(i)).valid_data) { System.out.println(((Bytes)dataSeq.get(i)).toString());

}

}

3-25

/* Return loan */ octetsReader.return_loan(dataSeq, infoSeq);

3.2.7KeyedOctets Built-in Type

The keyed octets built-in type is used to send sequences of octets with a key. The language- specific representations of the type are as follows:

C/C++ Representation (without Namespaces):

struct DDS_KeyedOctets { char * key;

int length;

unsigned char * value;

};

C++/CLI Representation:

namespace DDS {

public ref struct KeyedBytes { public:

System::String^ key; System::Int32 length; System::Int32 offset; array<System::Byte>^ value;

...

};

};

C# Representation:

namespace DDS {

public class KeyedBytes { public System.String key; public System.Int32 length; public System.Int32 offset; public System.Byte[] value;

};

};

Java Representation:

package com.rti.dds.type.builtin; public class KeyedBytes {

public String key; public int length; public int offset; public byte[] value;

...

};

3.2.7.1Creating and Deleting KeyedOctets

Connext provides a set of constructors/destructors to create/destroy KeyedOctets objects. For details, see the API Reference HTML documentation, which is available for all supported programming languages (select Modules, DDS API Reference, Topic Module, Built-in Types).

To manipulate the memory of the value field in the KeyedOctets struct in C/C++: use

DDS::OctetBuffer_alloc(), DDS::OctetBuffer_dup(), and DDS::OctetBuffer_free(). See the API Reference HTML documentation (select Modules, DDS API Reference, Infrastructure Module, Octet Buffer Support).

3-26

To manipulate the memory of the key field in the KeyedOctets struct in C/C++: use

DDS::String_alloc(), DDS::String_dup(), and DDS::String_free(). See the API Reference HTML documentation (select Modules, DDS API Reference, Infrastructure Module, String Support).

3.2.7.2Keyed Octets DataWriter

In addition to the standard methods (see Using a Type-Specific DataWriter (FooDataWriter) (Section 6.3.7)), the keyed octets DataWriter API is extended with the following methods:

DDS::ReturnCode_t DDS::KeyedOctetsDataWriter::dispose( const char* key,

const DDS::InstanceHandle_t & instance_handle);

DDS::ReturnCode_t DDS::KeyedOctetsDataWriter::dispose_w_timestamp( const char* key,

const DDS::InstanceHandle_t & instance_handle, const DDS::Time_t & source_timestamp);

DDS::ReturnCode_t DDS::KeyedOctetsDataWriter::get_key_value( char * key,

const DDS::InstanceHandle_t& handle);

DDS::InstanceHandle_t DDS::KeyedOctetsDataWriter::lookup_instance(

const char * key);

DDS::InstanceHandle_t DDS::KeyedOctetsDataWriter::register_instance(

const char* key);

DDS::InstanceHandle_t

DDS::KeyedOctetsDataWriter::register_instance_w_timestamp(

const char * key,

const DDS::Time_t & source_timestamp);

DDS::ReturnCode_t DDS::KeyedOctetsDataWriter::unregister_instance( const char * key,

const DDS::InstanceHandle_t & handle);

DDS::ReturnCode_t DDS::KeyedOctetsDataWriter::unregister_instance_w_timestamp(

const char* key,

const DDS::InstanceHandle_t & handle, const DDS::Time_t & source_timestamp);

DDS::ReturnCode_t DDS::KeyedOctetsDataWriter::write( const char * key,

const unsigned char * octets, int length,

const DDS::InstanceHandle_t& handle);

DDS::ReturnCode_t DDS::KeyedOctetsDataWriter::write( const char * key,

const DDS::OctetSeq & octets,

const DDS::InstanceHandle_t & handle);

DDS::ReturnCode_t DDS::KeyedOctetsDataWriter::write_w_timestamp( const char * key,

const unsigned char * octets, int length,

3-27

const DDS::InstanceHandle_t& handle, const DDS::Time_t& source_timestamp);

DDS::ReturnCode_t DDS::KeyedOctetsDataWriter::write_w_timestamp( const char * key,

const DDS::OctetSeq & octets,

const DDS::InstanceHandle_t & handle, const DDS::Time_t & source_timestamp);

These methods are introduced to provide maximum flexibility in the format of the input parameters for the write and instance management operations. For more information and a complete description of these operations in all supported languages, see the API Reference HTML documentation.

The following examples show how to write keyed octets using a keyed octets built-in type DataWriter and some of the extended APIs. For simplicity, error handling is not shown.

C Example:

DDS_KeyedOctetsDataWriter * octetsWriter = ... ; DDS_ReturnCode_t retCode;

struct DDS_KeyedOctets * octets = NULL; char * octetArray = NULL;

/* Write some data using the KeyedOctets structure */ octets = DDS_KeyedOctets_new_w_size(128,1024); strcpy(octets->key, "Key 1");

octets->length = 2; octets->value[0] = 46; octets->value[1] = 47;

retCode = DDS_KeyedOctetsDataWriter_write(

octetsWriter, octets, &DDS_HANDLE_NIL);

DDS_KeyedOctets_delete(octets);

/* Write some data using an octets array */ octetArray = (unsigned char *)malloc(1024); octetArray[0] = 46;

octetArray[1] = 47;

retCode = DDS_KeyedOctetsDataWriter_write_octets_w_key ( octetsWriter, "Key 1", octetArray, 2, &DDS_HANDLE_NIL);

free(octetArray);

C++ Example with Namespaces:

#include "ndds/ndds_namespace_cpp.h" using namespace DDS;

...

KeyedOctetsDataWriter * octetsWriter = ... ;

/* Write some data using the KeyedOctets structure */ KeyedOctets * octets = new KeyedOctets(128,1024); strcpy(octets->key, "Key 1");

octets->length = 2; octets->value[0] = 46; octets->value[1] = 47;

3-28

ReturnCode_t

retCode = octetsWriter->write(octets, HANDLE_NIL);

delete octets;

 

/* Write some

data using an octet array */

unsigned char

* octetArray = new unsigned char[1024];

octetArray[0]

= 46;

octetArray[1]

= 47;

retCode = octetsWriter->write("Key 1", octetArray, 2, HANDLE_NIL);

delete []octetArray;

C++/CLI Example:

using namespace System; using namespace DDS;

...

KeyedOctetsDataWriter^ octetsWriter = ... ;

/* Write some data using KeyedBytes */ KeyedBytes^ octets = gcnew KeyedBytes(1024); octets->key = "Key 1";

octets->value[0] =46; octets->value[1] =47; octets.length = 2; octets.offset = 0;

octetWriter->write(octets, InstanceHandle_t::HANDLE_NIL);

/* Write some data using individual strings */ array<Byte>^ octetAray = gcnew array<Byte>(1024); octetArray[0] = 46;

octetArray[1] = 47;

octetsWriter->write(

"Key 1", octetArray, 0, 2, InstanceHandle_t::HANDLE_NIL);

C# Example:

using System; using DDS;

...

KeyedBytesDataWriter stringWriter = ... ;

/* Write some data using the KeyedBytes */ KeyedBytes octets = new KeyedBytes(1024); octets.key = "Key 1";

octets.value[0] = 46; octets.value[1] = 47; octets.length = 2; octets.offset = 0;

octetWriter.write(octets, InstanceHandle_t.HANDLE_NIL);

/* Write some data using individual strings */ byte[] octetArray = new byte[1024]; octetArray[0] = 46;

octetArray[1] = 47;

3-29

octetsWriter.write(

"Key 1", octetArray, 0, 2, InstanceHandle_t.HANDLE_NIL);

Java Example:

import com.rti.dds.publication.*; import com.rti.dds.type.builtin.*; import com.rti.dds.infrastructure.*;

...

KeyedBytesDataWriter octetsWriter = ... ;

/* Write some data using the KeyedBytes class*/ KeyedBytes octets = new KeyedBytes(1024); octets.key = "Key 1";

octets.length = 2; octets.offset = 0; octets.value[0] = 46; octets.value[1] = 47;

octetsWriter.write(octets, InstanceHandle_t.HANDLE_NIL);

/* Write some data using a byte array */ byte[] octetArray = new byte[1024]; octetArray[0] = 46;

octetArray[1] = 47; octetsWriter.write(

"Key 1", octetArray, 0, 2, InstanceHandle_t.HANDLE_NIL);

3.2.7.3Keyed Octets DataReader

The KeyedOctets DataReader API is extended with the following methods (in addition to the standard methods described in Using a Type-Specific DataReader (FooDataReader) (Section 7.4.1)):

DDS::ReturnCode_t DDS::KeyedOctetsDataReader::get_key_value( char * key,

const DDS::InstanceHandle_t* handle);

DDS::InstanceHandle_t DDS::KeyedOctetsDataReader::lookup_instance(

const char * key);

For more information and a complete description of these operations in all supported languages, see the API Reference HTML documentation.

Memory considerations in copy operations:

For read/take operations with copy semantics, such as read_next_sample() and take_next_sample(), Connext allocates memory for the fields 'value' and 'key' if they are initialized to NULL.

If the fields are not initialized to NULL, the behavior depends on the language:

In Java and .NET, the memory of the field 'value' will be reallocated if the current size is not large enough to hold the received data. The memory associated with the field 'key' will be reallocated with every sample (the key is an immutable object).

In C and C++, the memory associated with the fields 'value' and 'key' must be large enough to hold the received data. Insufficient memory may result in crashes.

The following examples show how to read keyed octets with a keyed octets built-in type DataReader. For simplicity, error handling is not shown.

3-30

C Example:

struct DDS_KeyedOctetsSeq dataSeq = DDS_SEQUENCE_INITIALIZER; struct DDS_SampleInfoSeq infoSeq = DDS_SEQUENCE_INITIALIZER; DDS_KeyedOctetsDataReader * octetsReader = ... ; DDS_ReturnCode_t retCode;

int i;

/* Take and print the data */

retCode = DDS_KeyedOctetsDataReader_take( octetsReader,

&dataSeq, &infoSeq, DDS_LENGTH_UNLIMITED, DDS_ANY_SAMPLE_STATE, DDS_ANY_VIEW_STATE, DDS_ANY_INSTANCE_STATE);

for (i = 0; i < DDS_KeyedOctetsSeq_get_length(&data_seq); ++i) {

if (DDS_SampleInfoSeq_get_reference(&info_seq, i)->valid_data) { DDS_KeyedOctetsTypeSupport_print_data(

DDS_KeyedOctetsSeq_get_reference(&data_seq, i));

}

}

/* Return loan */

retCode = DDS_KeyedOctetsDataReader_return_loan( octetsReader, &data_seq, &info_seq);

C++ Example with Namespaces:

#include "ndds/ndds_namespace_cpp.h" using namespace DDS;

...

KeyedOctetsSeq dataSeq; SampleInfoSeq infoSeq;

KeyedOctetsDataReader * octetsReader = ... ;

/* Take a print the data */

ReturnCode_t retCode = octetsReader->take( dataSeq, infoSeq, LENGTH_UNLIMITED,

ANY_SAMPLE_STATE, ANY_VIEW_STATE, ANY_INSTANCE_STATE); for (int i = 0; i < data_seq.length(); ++i) {

if (infoSeq[i].valid_data) { KeyedOctetsTypeSupport::print_data(&dataSeq[i]);

}

}

/* Return loan */

retCode = octetsReader->return_loan(dataSeq, infoSeq);

C++/CLI Example:

using namespace System; using namespace DDS;

...

KeyedBytesSeq^ dataSeq = gcnew KeyedBytesSeq(); SampleInfoSeq^ infoSeq = gcnew SampleInfoSeq(); KeyedBytesDataReader^ octetsReader = ... ;

/* Take and print the data */ octetsReader->take(dataSeq, infoSeq,

ResourceLimitsQosPolicy::LENGTH_UNLIMITED, SampleStateKind::ANY_SAMPLE_STATE,

3-31

ViewStateKind::ANY_VIEW_STATE,

InstanceStateKind::ANY_INSTANCE_STATE);

for (int i = 0; i < data_seq.length(); ++i) { if (infoSeq->get_at(i)->valid_data) {

KeyedBytesTypeSupport::print_data(dataSeq->get_at(i));

}

}

/* Return loan */ octetsReader->return_loan(dataSeq, infoSeq);

C# Example:

using System; using DDS;

...

KeyedBytesSeq dataSeq = new KeyedButesSeq(); SampleInfoSeq infoSeq = new SampleInfoSeq(); KeyedBytesDataReader octetsReader = ... ;

/* Take and print the data */ octetsReader.take(dataSeq, infoSeq,

ResourceLimitsQosPolicy.LENGTH_UNLIMITED, SampleStateKind.ANY_SAMPLE_STATE, ViewStateKind.ANY_VIEW_STATE, InstanceStateKind.ANY_INSTANCE_STATE);

for (int i = 0; i < data_seq.length(); ++i) { if (infoSeq.get_at(i)).valid_data) {

KeyedBytesTypeSupport.print_data(dataSeq.get_at(i));

}

}

/* Return loan */ octetsReader.return_loan(dataSeq, infoSeq);

Java Example:

import com.rti.dds.infrastructure.*; import com.rti.dds.subscription.*; import com.rti.dds.type.builtin.*;

...

KeyedBytesSeq dataSeq = new KeyedBytesSeq(); SampleInfoSeq infoSeq = new SampleInfoSeq(); KeyedBytesDataReader octetsReader = ... ;

/* Take and print the data */ octetsReader.take(dataSeq, infoSeq,

ResourceLimitsQosPolicy.LENGTH_UNLIMITED, SampleStateKind.ANY_SAMPLE_STATE, ViewStateKind.ANY_VIEW_STATE, InstanceStateKind.ANY_INSTANCE_STATE);

for (int i = 0; i < data_seq.length(); ++i) {

if (((SampleInfo)infoSeq.get(i)).valid_data) { System.out.println(((KeyedBytes)dataSeq.get(i)).toString());

}

}

/* Return loan */ octetsReader.return_loan(dataSeq, infoSeq);

3-32

3.2.8Managing Memory for Built-in Types

When a sample is written, the DataWriter serializes it and stores the result in a buffer obtained from a pool of preallocated buffers. In the same way, when a sample is received, the DataReader deserializes it and stores the result in a sample coming from a pool of preallocated samples.

For data types generated by rtiddsgen, the size of the buffers and samples in both pools is known based on the IDL or XML description of the type.

For example:

struct MyString { string<128> value;

};

This IDL-defined type has a maximum serialized size of 133 bytes (4 bytes for length + 128 characters + 1 NULL terminating character). So the serialization buffers will have a size of 133 bytes. It can hold samples with 128 characters strings. Consequently, the preallocated samples will be sized to keep this length.

However, for built-in types, the maximum size of the buffers/samples is unknown and depends on the nature of the application using the built-in type.

For example, a video surveillance application that is using the keyed octets built-in type to publish a stream of images will require bigger buffers than a market-data application that uses the same built-in type to publish market-data values.

To accommodate both kinds of applications and optimize memory usage, you can configure the maximum size of the built-in types on a per-DataWriter or per-Datareader basis using the PROPERTY QosPolicy (DDS Extension) (Section 6.5.17). Table 3.1 on page 3-34 lists the supported built-in type properties. When the properties are defined in the DomainParticipant, they are applicable to all DataWriters and DataReaders belonging to the DomainParticipant, unless they are overwritten in the DataWriters and DataReaders.

Note: These properties must be set consistently with respect to the corresponding *.max_size properties in the DomainParticipant (see Table 3.14 on page 3-91). The value of the alloc_size property must be less than or equal to the max_size property with the same name prefix in the

DomainParticipant.

Section 3.2.8.1 includes examples of how to set the maximum size of a string built-in type for a DataWriter programmatically, for each API. You can also set the maximum size of the built-in types using XML QoS Profiles. For example, the following XML shows how to set the maximum size of a string built-in type for a DataWriter.

<dds>

<qos_library name="BuiltinExampleLibrary"> <qos_profile name="BuiltinExampleProfile">

<datawriter_qos> <property>

<value>

<element> <name>dds.builtin_type.string.alloc_size</name> <value>2048</value>

</element>

</value>

</property> </datawriter_qos> <datareader_qos>

<property>

<value>

<element>

3-33

<name>dds.builtin_type.string.alloc_size</name> <value>2048</value>

</element>

</value>

</property> </datareader_qos>

</qos_profile> </qos_library>

</dds>

Table 3.1 Properties for Allocating Size of Built-in Types, per DataWriter and DataReader

Built-in

Property

 

 

Description

 

 

 

Type

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Maximum size of the strings published by the DataWriter

 

 

or received by the DataReader (includes the NULL-

string

dds.builtin_type.string.alloc_size

terminated character).

 

 

 

 

 

 

Default: dds.builtin_type.string.max_size if defined (see

 

 

Table 3.14 on page 3-91). Otherwise, 1024.

 

 

 

 

 

 

 

 

Maximum size of the keys used by the DataWriter or

 

dds.builtin_type.keyed_string.

DataReader (includes the NULL-terminated character).

 

 

alloc_key_size

Default: dds.builtin_type.keyed_string.max_key_size if

 

 

defined (see Table 3.14 on page 3-91). Otherwise, 1024.

 

keyedstring

 

 

 

Maximum size of the strings published by the DataWriter

 

dds.builtin_type.keyed_string.

or received

by the DataReader

(includes

the

NULL-

 

terminated character).

 

 

 

 

 

alloc_size

 

 

 

 

 

Default:

dds.builtin_type.keyed_string.max_size

if

 

 

 

 

defined (see Table 3.14 on page 3-91). Otherwise, 1024.

 

 

 

 

 

 

Maximum size of the octet sequences published by the

octets

dds.builtin_type.octets.alloc_size

DataWriter or DataReader.

 

 

 

 

Default: dds.builtin_type.octets.max_size if defined (see

 

 

Table 3.14 on page 3-91). Otherwise, 2048.

 

 

 

 

 

 

 

 

Maximum size of the key published by the DataWriter or

 

dds.builtin_type.keyed_octets.

received

by

the DataReader

(includes

the

NULL-

 

terminated character).

 

 

 

 

 

alloc_key_size

 

 

 

 

 

Default:

dds.builtin_type.keyed_octets.max_key_size if

 

 

keyed-octets

 

defined (see Table 3.14 on page 3-91). Otherwise, 1024.

 

 

 

Maximum size of the octet sequences published by the

 

dds.builtin_type.keyed_octets.

DataWriter or DataReader.

 

 

 

 

 

alloc_size

Default:

dds.builtin_type.keyed_octets.max_size

if

 

 

defined (see Table 3.14 on page 3-91). Otherwise, 2048.

 

 

 

 

 

 

 

 

 

 

3.2.8.1Examples—Setting the Maximum Size for a String Programmatically

For simplicity, error handling is not shown in the following examples.

C Example:

DDS_DataWriter * writer = NULL; DDS_StringDataWriter * stringWriter = NULL; DDS_Publisher * publisher = ... ;

DDS_Topic * stringTopic = ... ;

struct DDS_DataWriterQos writerQos = DDS_DataWriterQos_INITIALIZER; DDS_ReturnCode_t retCode;

retCode = DDS_DomainParticipant_get_default_datawriter_qos ( participant, &writerQos);

3-34

retCode = DDS_PropertyQosPolicyHelper_add_property ( &writerQos.property, "dds.builtin_type.string.alloc_size", "1000", DDS_BOOLEAN_FALSE);

writer = DDS_Publisher_create_datawriter(

publisher, stringTopic, &writerQos, NULL, DDS_STATUS_MASK_NONE);

stringWriter = DDS_StringDataWriter_narrow(writer); DDS_DataWriterQos_finalize(&writerQos);

C++ Example with Namespaces:

#include "ndds/ndds_namespace_cpp.h" using namespace DDS;

...

Publisher * publisher = ... ;

Topic * stringTopic = ... ;

DataWriterQos writerQos;

ReturnCode_t retCode = participant->get_default_datawriter_qos(writerQos);

retCode = PropertyQosPolicyHelper::add_property ( &writerQos.property, dds.builtin_type.string.alloc_size",

"1000",

BOOLEAN_FALSE);

DataWriter * writer = publisher->create_datawriter( stringTopic, writerQos, NULL, STATUS_MASK_NONE);

StringDataWriter * stringWriter = StringDataWriter::narrow(writer);

C++/CLI Example:

using namespace DDS;

...

Topic^ stringTopic = ... ;

Publisher^ publisher = ... ;

DataWriterQos^ writerQos = gcnew DataWriterQos();

participant->get_default_datawriter_qos(writerQos);

PropertyQosPolicyHelper::add_property(writerQos->property_qos,

"dds.builtin_type.string.alloc_size","1000", false);

DataWriter^ writer = publisher->create_datawriter(stringTopic, writerQos, nullptr, StatusMask::STATUS_MASK_NONE);

StringDataWriter^ stringWriter = safe_cast<StringDataWriter^>(writer);

C# Example:

using DDS;

...

Topic stringTopic = ... ;

Publisher publisher = ... ;

3-35

DataWriterQos writerQos = new DataWriterQos();

participant.get_default_datawriter_qos(writerQos);

PropertyQosPolicyHelper.add_property (writerQos.property_qos,

"dds.builtin_type.string.alloc_size", "1000", false);

StringDataWriter stringWriter =

(StringDataWriter) publisher.create_datawriter(stringTopic, writerQos, null, StatusMask.STATUS_MASK_NONE);

Java Example:

import com.rti.dds.publication.*; import com.rti.dds.type.builtin.*; import com.rti.dds.infrastructure.*;

...

Topic stringTopic = ... ;

Publisher publisher = ... ;

DataWriterQos writerQos = new DataWriterQos();

participant.get_default_datawriter_qos(writerQos);

PropertyQosPolicyHelper.add_property (writerQos.property,

"dds.builtin_type.string.alloc_size", "1000", false);

StringDataWriter stringWriter =

(StringDataWriter) publisher.create_datawriter(stringTopic, writerQos, null, StatusKind.STATUS_MASK_NONE);

3.2.9Type Codes for Built-in Types

The type codes associated with the built-in types are generated from the following IDL type definitions:

module DDS {

/* String */ struct String {

string<max_size> value;

};

/* KeyedString */ struct KeyedString {

string<max_size> key; //@key string<max_size> value;

};

/* Octets */ struct Octets {

sequence<octet, max_size> value;

};

/* KeyedOctets */ struct KeyedOctets {

string<max_size> key; //@key sequence<octet, max_size> value;

};

};

The maximum size (max_size) of the strings and sequences that will be included in the type code definitions can be configured on a per-DomainParticipant-basis by using the properties in

3-36

Table 3.2.

Table 3.2 Properties for Allocating Size of Built-in Types, per DomainParticipant

Built-in

Property

 

 

Description

 

 

 

 

Type

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Maximum size of the strings published by the DataWriters

 

 

and received by the DataReaders belonging to a

String

dds.builtin_type.string.max_size

DomainParticipant (includes the NULL-terminated

 

 

character).

 

 

 

 

 

 

 

 

 

 

Default: 1024

 

 

 

 

 

 

 

 

 

 

 

 

 

Maximum size of the keys used by the DataWriters and

 

dds.builtin_type.keyed_string.

DataReaders belonging to a DomainParticipant (includes the

 

max_key_size

NULL-terminated character).

 

 

 

 

 

 

 

Default: 1024

 

 

 

 

 

 

 

 

KeyedString

 

 

 

Maximum size of the strings published by the DataWriters

 

dds.builtin_type.keyed_string.

and received

by

the

DataReaders

belonging to

a

 

DomainParticipant using

the

built-in

type (includes

the

 

max_size

 

NULL-terminated character).

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Default: 1024

 

 

 

 

 

 

 

 

 

 

 

 

 

Maximum size of the octet sequences published by the

Octets

dds.builtin_type.octets.max_size

DataWriters

and

DataReaders

belonging

to

a

DomainParticipant.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Default: 2048

 

 

 

 

 

 

 

 

 

 

 

 

 

Maximum size of the key published by the DataWriter and

 

dds.builtin_type.keyed_octets.

received by

the

DataReaders

belonging

to

the

 

DomainParticipant (includes

the

 

NULL-terminated

 

max_key_size

 

 

character).

 

 

 

 

 

 

 

 

Keyed-

 

 

 

 

 

 

 

 

 

 

Default:1024.

 

 

 

 

 

 

 

 

Octets

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Maximum size of the octet sequences published by the

 

 

 

dds.builtin_type.keyed_octets.

DataWriters and DataReaders belonging to a

 

max_size

DomainParticipant.

 

 

 

 

 

 

 

 

 

Default: 2048

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

3.3Creating User Data Types with IDL

You can create user data types in a text file using IDL (Interface Description Language). IDL is programming-language independent, so the same file can be used to generate code in C, C++, C++/CLI, and Java (the languages supported by rtiddsgen). The rtiddsgen utility parses the IDL file and automatically generates all the necessary routines and wrapper functions to bind the types for use by Connext at run time. You will end up with a set of required routines and structures that your application and Connext will use to manipulate the data.

Connext only uses a subset of the IDL syntax. IDL was originally defined by the OMG for the use of CORBA client/server applications in an enterprise setting. Not all of the constructs that can be described by the language are as useful in the context of high-performance data-centric embedded applications. These include the constructs that define method and function prototypes like “interface.”

The rtiddsgen utility will parse any file that follows version 3.0.3 of the IDL specification. It will quietly ignore all syntax that is not recognized by Connext. In addition, even though “anonymous sequences” (sequences of sequences with no intervening typedef) are currently

3-37

legal in IDL, they have been deprecated by the specification, and thus rtiddsgen does not support them.

Certain keywords are considered reserved by the IDL specification; see Table 3.3.

Table 3.3 Reserved IDL Keywords

abstract

emits

local

pseudo

typeid

 

 

 

 

 

alias

enum

long

public

typename

 

 

 

 

 

any

eventtype

mirrorport

publishes

typeprefix

 

 

 

 

 

attribute

exception

module

raises

union

 

 

 

 

 

boolean

factory

multiple

readonly

unsigned

 

 

 

 

 

case

FALSE

native

sequence

uses

 

 

 

 

 

char

finder

object

setraises

valuebase

 

 

 

 

 

component

fixed

octet

short

valuetype

 

 

 

 

 

connector

float

oneway

string

void

 

 

 

 

 

const

getraises

out

struct

wchar

 

 

 

 

 

consumes

home

port

supports

wstring

 

 

 

 

 

context

import

porttype

switch

 

 

 

 

 

 

custom

in

primarykey

TRUE

 

 

 

 

 

 

default

inout

private

truncatable

 

 

 

 

 

 

double

interface

provides

typedef

 

 

 

 

 

 

The IDL constructs supported by rtiddsgen are described in Table 3.5, “Specifying Data Types in IDL for C and C++,” on page 3-41 and Table 3.7, “Specifying Data Types in IDL for Java,” on page 3-48. Use these tables to map primitive types to their equivalent IDL syntax, and vice versa.

For C and C++, rtiddsgen uses typedefs instead of the language keywords for primitive types. For example, DDS_Long instead of long or DDS_Double instead of double. This ensures that the types are of the same size regardless of the platform.1

The remainder of this section includes:

Variable-Length Types (Section 3.3.1)

Value Types (Section 3.3.2)

TypeCode and rtiddsgen (Section 3.3.3)

rtiddsgen Translations for IDL Types (Section 3.3.4)

Escaped Identifiers (Section 3.3.5)

Referring to Other IDL Files (Section 3.3.6)

Preprocessor Directives (Section 3.3.7)

Using Custom Directives (Section 3.3.8)

1. The number of bytes sent on the wire for each data type is determined by the Common Data Representation (CDR) standard. For details on CDR, please see the Common Object Request Broker Architecture (CORBA) Specification, Version 3.1, Part 2: CORBA Interoperability, Section 9.3, CDR Transfer Syntax (http://www.omg.org/ technology/documents/corba_spec_catalog.htm).

3-38

3.3.1Variable-Length Types

When rtiddsgen generates code for data structures with variable-length types—strings and sequences—it includes functions that create, initialize and finalize (destroy) those objects. These support functions will properly initialize pointers and allocate and deallocate the memory used for variable-length types. All Connext APIs assume that the data structures passed to them are properly initialized.

For variable-length types, the actual length (instead of the maximum length) of data is transmitted on the wire when the sample is written (regardless of whether the type has hard- coded bounds).

3.3.1.1Sequences

C, C++, C++/CLI, and C# users can allocate memory from a number of sources: from the heap, the stack, or from a custom allocator of some kind. In those languages, sequences provide the concept of memory "ownership." A sequence may own the memory allocated to it or be loaned memory from another source. If a sequence owns its memory, it will manage its underlying memory storage buffer itself. When a sequence's maximum size is changed, the sequence will free and reallocate its buffer as needed. However, if a sequence was created with loaned memory by user code, then its memory is not its own to free or reallocate. Therefore, you cannot set the maximum size of a sequence whose memory is loaned. See the API Reference HTML documentation, which is available for all supported programming languages (select Modules, DDS API Reference, Infrastructure Module, Sequence Support) for more information about how to loan and unloan memory for sequence.

In IDL, as described above, a sequence may be declared as bounded or unbounded. A sequence's "bound" is the greatest value its maximum may take. If you use the initializer functions rtiddsgen provides for your types, all sequences will have their maximums set to their declared bounds. However, the amount of data transmitted on the wire when the sample is written will vary.

3.3.1.2Strings and Wide Strings

The initialization functions that rtiddsgen provides for your types will allocate all of the memory for strings in a type to their declared bounds. Take care—if you assign a string pointer (char *) in a data structure allocated or initialized by a Connext-generated function, you should release (free) the memory originally allocated for the string, otherwise the memory will be leaked.

To Java and .NET users, an IDL string is a String object: it is immutable and knows its own length. C and C++ users must take care, however, as there is no way to determine how much memory is allocated to a character pointer "string"; all that can be determined is the string's current logical length. In some cases, Connext may need to copy a string into a structure that user code has provided. Connext does not free the memory of the string provided to it, as it cannot know from where that memory was allocated.

In the C and C++ APIs, Connext therefore uses the following conventions:

A string's memory is "owned" by the structure that contains that string. Calling the finalization function provided for a type will free all recursively contained strings. If you have allocated a contained string in a special way, you must be careful to clean up your own memory and assign the pointer to NULL before calling the type’s finalize() method, so that Connext will skip over that string.

You must provide a non-NULL string pointer for Connext to copy into. Otherwise, Connext will log an error.

3-39

When you provide a non-NULL string pointer in your data structure, Connext will copy into the provided memory without performing any additional memory allocations. Be careful—if you provide Connext with an uninitialized pointer or allocate a string that is too short, you may corrupt the memory or cause a program crash. Connext will never try to copy a string that is longer than the bound of the destination string. However, your application must insure that any string that it allocates is long enough.

Connext provides a small set of C functions for dealing with strings. These functions simplify common tasks, avoid some platform-specific issues (such as the lack of a strdup() function on some platforms), and provide facilities for dealing with wide strings, for which no standard C library exists. Connext always uses these functions internally for managing string memory; you are recommended—but not required—to use them as well. See the API Reference HTML documentation, which is available for all supported programming languages (select Modules, DDS API Reference, Infrastructure Module, String Support) for more information about strings.

3.3.2Value Types

A value type is like a structure, but with support for additional object-oriented features such as inheritance. It is similar to what is sometimes referred to in Java as a POJO—a Plain Old Java Object.

Readers familiar with value types in the context of CORBA should consult Table 3.4 to see which value type-related IDL keywords are supported and what their behavior is in the context of

Connext.

Table 3.4 Value Type Support

Aspect

Level of Support in rtiddsgen

 

 

Inheritance

Single inheritance from other value types

 

 

Public state members

Supported

 

 

Private state members

Become public when code is generated

 

 

Custom keyword

Ignored (the value type is parsed without the keyword and code is generated to

work with it)

 

 

 

Abstract value types

No code generated (the value type is parsed, but no code is generated)

 

 

Operations

No code generated (the value type is parsed, but no code is generated)

 

 

Truncatable keyword

Ignored (the value type is parsed without the keyword and code is generated to

work with it)

 

 

 

3.3.3TypeCode and rtiddsgen

Type codes are enabled by default when you run rtiddsgen. The -notypecode option disables generation of type code information. Type-code support does increase the amount of memory used, so if you need to save on memory, you may consider disabling type codes.

(The -notypecode option is described in rtiddsgen Command-Line Arguments (Section 3.6.1)

Locally, your application can access the type code for a generated type "Foo" by calling the Foo::get_typecode() operation in the code for the type generated by rtiddsgen (unless type-code support is disabled with the -notypecode option).

Note: Type-code support must be enabled if you are going to use ContentFilteredTopics (Section 5.4) with the default SQL filter. You may disable type codes and use a custom filter, as described in Creating ContentFilteredTopics (Section 5.4.3).

3-40

3.3.4rtiddsgen Translations for IDL Types

This section describes how to specify your data types in an IDL file. The rtiddsgen utility supports all the types listed in the following tables:

Table 3.5, “Specifying Data Types in IDL for C and C++,” on page 3-41

Table 3.6, “Specifying Data Types in IDL for C++/CLI,” on page 3-45

Table 3.7, “Specifying Data Types in IDL for Java,” on page 3-48

In each table, the middle column shows the syntax for an IDL data type in the IDL file. The rightmost column shows the corresponding language mapping created by rtiddsgen.

Table 3.5 Specifying Data Types in IDL for C and C++

IDL Type

Sample Entry in IDL File

Sample Output Generated by rtiddsgen

 

 

 

char

struct PrimitiveStruct {

typedef struct PrimitiveStruct

{

(see Note 1

char char_member;

DDS_Char char_member;

below)

};

} PrimitiveStruct;

 

 

 

 

 

 

struct PrimitiveStruct {

typedef struct PrimitiveStruct

wchar

{

wchar wchar_member;

DDS_Wchar wchar_member;

 

};

 

} PrimitiveStruct;

 

 

 

 

 

 

struct PrimitiveStruct {

typedef struct PrimitiveStruct

 

{

octet

octet octet_member;

DDS_Octet octect_member;

 

};

 

} PrimitiveStruct;

 

 

 

 

 

 

struct PrimitiveStruct {

typedef struct PrimitiveStruct

short

{

short short_member;

DDS_Short short_member;

 

};

 

} PrimitiveStruct;

 

 

 

 

 

 

struct PrimitiveStruct {

typedef struct PrimitiveStruct

unsigned

{

unsigned short

DDS_UnsignedShort

short

unsigned_short_member;

unsigned_short_member;

 

};

 

} PrimitiveStruct;

 

 

 

 

 

 

struct PrimitiveStruct {

typedef struct PrimitiveStruct

long

{

long long_member;

DDS_Long long_member;

 

};

 

} PrimitiveStruct;

 

 

 

 

 

 

struct PrimitiveStruct {

typedef struct PrimitiveStruct

unsigned

{

unsigned long

DDS_UnsignedLong

long

unsigned_long_member;

unsigned_long_member;

 

};

 

} PrimitiveStruct;

 

 

 

 

 

 

struct PrimitiveStruct {

typedef struct PrimitiveStruct

 

{

long long

long long long_long_member;

DDS_LongLong long_long_member;

 

};

 

} PrimitiveStruct;

 

 

 

 

 

 

struct PrimitiveStruct {

typedef struct PrimitiveStruct

unsigned

{

unsigned long long

DDS_UnsignedLongLong

long long

unsigned_long_long_member;

unsigned_long_long_member;

 

};

 

} PrimitiveStruct;

 

 

 

 

 

 

struct PrimitiveStruct {

typedef struct PrimitiveStruct

float

{

float float_member;

DDS_Float float_member;

 

};

 

} PrimitiveStruct;

 

 

 

 

 

3-41

Table 3.5 Specifying Data Types in IDL for C and C++

IDL Type

Sample Entry in IDL File

Sample Output Generated by rtiddsgen

 

 

 

 

 

 

 

 

 

 

struct PrimitiveStruct {

typedef struct PrimitiveStruct

double

{

double double_member;

DDS_Double double_member;

 

 

};

 

 

} PrimitiveStruct;

 

 

 

 

 

 

 

long

 

struct PrimitiveStruct {

typedef struct PrimitiveStruct

double

{

long double long_double_member;

(see Note 2

DDS_LongDouble long_double_member;

};

} PrimitiveStruct;

below)

 

 

 

 

pointer

struct MyStruct {

typedef struct MyStruct {

(see Note 9

long * member;

DDS_Long * member;

below)

};

} MyStruct;

 

 

 

 

 

 

struct PrimitiveStruct {

typedef struct PrimitiveStruct

boolean

{

boolean boolean_member;

DDS_Boolean boolean_member;

 

 

};

 

 

} PrimitiveStruct;

 

 

 

 

 

 

 

 

 

enum PrimitiveEnum {

typedef enum PrimitiveEnum

 

 

{

 

 

ENUM1,

 

 

ENUM1,

 

 

ENUM2,

 

 

ENUM2,

 

 

ENUM3

 

 

ENUM3

 

 

};

 

 

} PrimitiveEnum;

 

 

 

enum

 

 

 

 

 

enum PrimitiveEnum {

typedef enum PrimitiveEnum

 

 

{

 

 

ENUM1 = 10,

 

 

ENUM1 = 10,

 

 

ENUM2 = 20,

 

 

ENUM2 = 20,

 

 

ENUM3 = 30

 

 

ENUM3 = 30

 

 

};

 

 

} PrimitiveEnum;

 

 

 

 

 

 

 

 

 

 

C: #define SIZE 5

constant

const short SIZE = 5;

C++: static const DDS_Short size = 5;

 

 

 

 

 

 

 

typedef struct BitfieldType

 

 

struct BitfieldType {

{

 

 

short myShort_1 : 1;

DDS_Short myShort_1 : 1;

 

 

unsigned short myUnsignedShort_1:

DDS_UnsignedShort myUnsignedShort_1

 

 

1;

: 1;

 

 

long myLong_1: 1;

DDS_Long myLong_1 : 1;

 

 

unsigned long myUnsignedLong_1 :1;

DDS_UnsignedLong myUnsignedLong_1 :

bitfield

char myChar_1 : 1;

1;

wchar myWChar_1 : 1;

DDS_Char myChar_1 : 1;

 

 

 

 

octet myOctet_1 : 1;

DDS_Wchar myWChar_1 : 1;

(see

Note

short : 0;

DDS_Octet myOctet_1 : 1;

12 below)

long myLong_5 : 5;

DDS_Short : 0;

long myLong_30 : 30;

DDS_Long myLong_5 : 5;

 

 

 

 

short myShort_6 : 6;

DDS_Long myLong_30 : 30;

 

 

short myShort_3and4 : 3+4;

DDS_Short myShort_6 : 6;

 

 

short myShort;

DDS_Short myShort_3and4 : 3+4;

 

 

short myShort_8 : 8;

DDS_Short myShort;

 

 

long myLong_32: 32;

DDS_Short myShort_8 : 8;

 

 

};

DDS_Long myLong_32 : 32;

 

 

 

} BitfieldType;

 

 

 

 

struct

 

struct PrimitiveStruct {

typedef struct PrimitiveStruct

 

 

 

 

{

 

 

char char_member;

(see

Note

char char_member;

};

} PrimitiveStruct;

10 below)

 

 

 

 

 

 

 

3-42

Table 3.5 Specifying Data Types in IDL for C and C++

IDL Type

Sample Entry in IDL File

Sample Output Generated by rtiddsgen

 

 

 

 

 

 

 

 

 

 

 

 

 

typedef struct PrimitiveUnion

 

union

 

union PrimitiveUnion switch (long){

{

 

 

 

 

case 1:

DDS_Long _d;

 

 

(see Note 3

short short_member;

struct {

 

 

default:

DDS_Short short_member;

 

and

Note

 

long long_member;

DDS_Long long_member;

 

10 below)

};

} _u;

 

 

 

 

 

} PrimitiveUnion;

 

 

 

 

 

 

typedef

typedef short TypedefShort;

typedef DDS_Short TypedefShort;

 

 

 

 

 

 

 

 

struct OneDArrayStruct {

typedef struct OneDArrayStruct

 

 

 

{

 

 

 

 

short short_array[2];

 

 

 

 

DDS_Short short_array[2];

 

array

of

};

 

} OneDArrayStruct;

 

 

above

 

struct TwoDArrayStruct {

 

 

 

types

 

typedef struct TwoDArrayStruct

 

 

short short_array[1][2];

 

 

 

{

 

 

 

 

};

 

 

 

 

DDS_Short short_array[1][2];

 

 

 

 

 

 

 

 

} TwoDArrayStruct;

 

 

 

 

 

 

 

bounded

 

typedef struct SequenceStruct

 

sequence of

 

 

 

{

 

 

above

 

 

 

 

 

struct SequenceStruct {

DDSShortSeq short_sequence;

 

types

 

sequence<short,4> short_sequence;

} SequenceStruct;

 

 

 

 

};

Note: Sequences of primitive types have been

(see

Note

 

 

predefined by Connext.

 

 

11 below)

 

 

 

 

 

 

 

 

 

 

 

 

unbounded

 

typedef struct SequenceStruct

 

 

{

 

 

sequence of

 

 

 

 

DDSShortSeq short_sequence;

 

above

 

struct SequenceStruct {

} SequenceStruct;

 

 

types

 

sequence<short> short_sequence;

Note: rtiddsgen will supply a default bound.

 

 

};

(see

Note

 

You can specify that bound

with the

“-

 

sequenceSize” command-line

option;

see

11 below)

 

 

Section 3.6.1.

 

 

 

 

 

 

 

 

 

 

 

 

array

of

struct ArraysOfSequences{

typedef struct ArraysOfSequences

 

sequence<short,4>

{

 

 

sequences

sequences_array[2];

DDS_ShortSeq sequences_array[2];

 

 

 

};

} ArraysOfSequences;

 

 

 

 

 

 

 

 

 

 

typedef DDS_Short ShortArray[2];

 

 

 

 

DDS_SEQUENCE_NO_GET(ShortArraySeq,

 

 

 

 

ShortArray);

 

sequence of

typedef short ShortArray[2];

typedef struct SequenceOfArrays

 

arrays

 

 

 

 

struct SequenceofArrays {

{

 

 

 

 

 

 

(see

Note

sequence<ShortArray,2>

ShortArraySeq arrays_sequence;

 

arrays_sequence;

} SequenceOfArrays;

 

 

11 below)

};

DDS_SEQUENCE_NO_GET is a Connext

 

 

 

 

 

 

macro that defines a new sequence type for a

 

 

 

user data type. In this case, the user data type is

 

 

 

ShortArray.

 

 

 

 

 

 

 

 

3-43

Table 3.5 Specifying Data Types in IDL for C and C++

IDL Type

Sample Entry in IDL File

Sample Output Generated by rtiddsgen

 

 

 

 

 

 

 

 

 

typedef sequence<short,4>

typedef DDS_ShortSeq ShortSequence;

 

sequence of

 

 

 

 

sequences

ShortSequence;

DDS_SEQUENCE(ShortSequenceSeq,

 

 

 

 

struct SequencesOfSequences{

 

ShortSequence);

 

 

 

 

 

 

(see Note 4

sequence<ShortSequence,2>

typedef struct SequencesOfSequences{

 

sequences_sequence;

 

and Note

ShortSequenceSeq

 

 

};

 

 

11 below)

sequences_sequence;

 

 

 

 

 

 

 

} SequencesOfSequences;

 

 

 

 

 

 

bounded

struct PrimitiveStruct {

typedef struct PrimitiveStruct {

 

char* string_member;

 

 

string<20> string_member;

 

 

string

 

/* maximum length = (20) */

};

 

 

} PrimitiveStruct;

 

 

 

 

 

 

 

 

 

 

 

 

typedef struct PrimitiveStruct {

 

 

 

char* string_member;

 

 

 

struct PrimitiveStruct {

 

/* maximum length = (255) */

unbounded

} PrimitiveStruct;

 

 

string string_member;

 

 

 

 

 

 

string

};

Note: rtiddsgen will supply a default bound.

 

 

 

 

You can specify that bound with the -

 

 

stringSize

command-line

option,

see

 

 

Section 3.6.1.

 

 

 

 

 

 

 

 

typedef struct PrimitiveStruct {

 

bounded

struct PrimitiveStruct {

DDS_Wchar * wstring_member;

 

wstring<20> wstring_member;

 

/* maximum length = (20)

wstring

 

};

*/

 

 

 

 

 

 

 

 

 

} PrimitiveStruct;

 

 

 

 

 

 

 

 

typedef struct PrimitiveStruct {

 

unbounded

struct PrimitiveStruct {

DDS_Wchar * wstring_member;

 

 

/* maximum length = (255) */

wstring

wstring wstring_member;

} PrimitiveStruct;

 

 

};

 

 

 

 

 

 

 

 

 

Note: rtiddsgen will supply a default bound.

 

 

 

 

 

 

 

With the -namespace option

(only available

 

 

for C++):

 

 

 

 

 

namespace PackageName{

 

 

module PackageName {

 

typedef struct Foo {

 

module

struct Foo {

 

DDS_Long field;

 

long field;

 

} Foo;

 

 

 

};

};

 

 

 

 

};

Without the -namespace option:

 

 

 

typedef struct PackageName_Foo {

 

 

 

DDS_Long field;

 

 

 

 

} PackageName_Foo;

 

 

 

 

 

 

 

 

3-44

Table 3.5 Specifying Data Types in IDL for C and C++

 

IDL Type

Sample Entry in IDL File

Sample Output Generated by rtiddsgen

 

 

 

 

 

 

 

 

 

 

 

 

 

C++:

class MyValueType {

 

 

 

 

public:

 

 

 

 

 

MyValueType2 * member;

 

 

 

 

};

 

 

 

 

 

class MyValueType {

 

 

 

 

public:

 

 

 

valuetype MyValueType {

 

MyValueType2

member;

 

 

 

};

 

 

 

public MyValueType2 * member;

 

 

 

 

 

 

 

 

 

};

 

class MyValueType : public MyBa-

 

 

 

 

 

valuetype

 

 

seValueType

 

 

valuetype MyValueType {

 

{

 

 

 

 

public:

 

 

 

public MyValueType2 member;

 

 

 

(see Note 9

 

MyValueType2 * member;

 

};

 

 

 

};

 

 

and Note

 

 

 

 

 

 

 

 

 

 

C:

 

 

 

10 below)

 

typedef struct MyValueType {

 

 

valuetype MyValueType: MyBaseValueType

 

MyValueType2 * member;

 

 

{

 

} MyValueType;

 

 

 

public MyValueType2 * member;

 

 

 

 

 

};

 

typedef struct MyValueType {

 

 

 

 

MyValueType2

member;

 

 

 

 

} MyValueType;

 

 

 

 

 

typedef struct MyValueType

 

 

 

 

{

 

 

 

 

 

MyBaseValueType parent;

 

 

 

 

MyValueType2 * member;

 

 

 

 

} MyValueType;

 

 

 

 

 

 

 

Table 3.6 Specifying Data Types in IDL for C++/CLI

 

 

 

 

 

 

 

 

IDL Type

Sample Entry in IDL File

Sample Output Generated by rtiddsgen

 

 

 

 

 

 

 

 

 

char

struct PrimitiveStruct {

public ref class PrimitiveStruct {

 

(see Note 1

char char_member;

System::Char char_member;

 

below)

};

};

 

 

 

 

 

 

 

wchar

struct PrimitiveStruct {

public ref class PrimitiveStruct {

 

wchar wchar_member;

System::Char wchar_member;

 

 

};

};

 

 

 

 

 

 

 

 

struct PrimitiveStruct {

public ref class PrimitiveStruct {

 

octet

octet octet_member;

System::Byte octet_member;

 

 

};

};

 

 

 

 

 

 

 

short

struct PrimitiveStruct {

public ref class PrimitiveStruct {

 

short short_member;

System::Int16 short_member;

 

 

};

};

 

 

 

 

 

 

 

 

 

unsigned

struct PrimitiveStruct {

public ref class PrimitiveStruct {

 

unsigned short

 

System::UInt16 unsigned_short_member;

 

short

unsigned_short_member;

 

};

 

 

 

 

};

 

 

 

 

 

 

 

 

 

 

 

 

long

struct PrimitiveStruct {

public ref class PrimitiveStruct {

 

long long_member;

System::Int32 long_member;

 

 

};

};

 

 

 

 

 

 

 

unsigned

struct PrimitiveStruct {

public ref class PrimitiveStruct {

 

unsigned long unsigned_long_member;

System::UInt32 unsigned_long_member;

 

long

 

};

};

 

 

 

 

 

 

 

 

 

 

 

 

3-45

Table 3.6 Specifying Data Types in IDL for C++/CLI

IDL Type

Sample Entry in IDL File

Sample Output Generated by rtiddsgen

 

 

 

 

 

 

 

 

long long

struct PrimitiveStruct {

public ref class PrimitiveStruct {

long long long_long_member;

System::Int64 long_long_member;

 

 

};

};

 

 

 

 

unsigned

struct PrimitiveStruct {

public ref class PrimitiveStruct {

unsigned long long

System::UInt64

long long

unsigned_long_long_member;

unsigned_long_long_member;

 

 

};

};

 

 

 

 

float

 

struct PrimitiveStruct {

public ref class PrimitiveStruct {

 

float float_member;

System::Single float_member;

 

 

};

};

 

 

 

 

 

 

struct PrimitiveStruct {

public ref class PrimitiveStruct {

double

double double_member;

System::Double double_member;

 

 

};

} PrimitiveStruct;

 

 

 

 

long

 

struct PrimitiveStruct {

public ref class PrimitiveStruct {

double

long double long_double_member;

DDS::LongDouble long_double_member;

(see Note 2

};

} PrimitiveStruct;

below)

 

 

 

 

 

struct PrimitiveStruct {

public ref class PrimitiveStruct {

boolean

boolean boolean_member;

System::Boolean boolean_member;

 

 

};

};

 

 

 

 

 

 

 

public enum class

 

 

enum PrimitiveEnum {

PrimitiveEnum : System::Int32 {

 

 

ENUM1,

ENUM1,

 

 

ENUM2,

ENUM2,

 

 

ENUM3

ENUM3

enum

 

};

};

 

 

 

 

 

enum PrimitiveEnum {

public enum class

 

 

ENUM1 = 10,

PrimitiveEnum : System::Int32 {

 

 

ENUM2 = 20,

ENUM1 = 10,

 

 

ENUM3 = 30

ENUM2 = 20,

 

 

};

ENUM3 = 30

 

 

 

};

 

 

 

 

 

 

 

public ref class SIZE {

constant

const short SIZE = 5;

public:

static System::Int16 VALUE = 5;

 

 

 

 

 

 

};

 

 

 

 

struct

 

struct PrimitiveStruct {

public ref class PrimitiveStruct {

 

 

 

 

 

(see

Note

char char_member;

System::Char char_member;

};

};

10 below)

 

 

 

 

 

 

 

 

 

 

public ref class PrimitiveUnion

union

 

union PrimitiveUnion switch (long){

{

 

 

case 1:

System::Int32 _d;

(see Note 3

short short_member;

struct PrimitiveUnion_u {

default:

System::Int16 short_member;

and

Note

long long_member;

System::Int32 long_member;

10 below)

};

} _u;

 

 

 

};

 

 

 

 

array

of

struct OneDArrayStruct {

public ref class OneDArrayStruct {

array<System::Int16>^ short_array;

above

 

short short_array[2];

 

/*length == 2*/

types

 

};

 

};

 

 

 

 

 

 

 

3-46

Table 3.6 Specifying Data Types in IDL for C++/CLI

IDL Type

Sample Entry in IDL File

Sample Output Generated by rtiddsgen

 

 

 

 

 

 

 

 

 

 

 

 

bounded

 

public ref class SequenceStruct {

 

sequence of

 

 

 

ShortSeq^ short_sequence;

 

above

 

 

 

 

struct SequenceStruct {

/*max = 4*/

 

 

types

 

sequence<short,4> short_sequence;

};

 

 

 

 

 

};

Note: Sequences of primitive types have been

(see

Note

 

 

predefined by Connext.

 

 

11 below)

 

 

 

 

 

 

 

 

 

 

 

 

unbounded

 

public ref class SequenceStruct {

 

sequence of

 

ShortSeq^ short_sequence;

 

above

 

struct SequenceStruct {

/*max = <default bound>*/

 

 

};

 

 

 

types

 

 

 

 

 

sequence<short> short_sequence;

 

 

 

 

Note: rtiddsgen will supply a default bound.

 

 

};

 

 

You can specify that bound with the

 

(see

Note

 

 

 

-sequenceSize command-line option; see

11 below)

 

Section 3.6.1.

 

 

 

 

 

 

 

 

 

 

 

public ref class ArraysOfSequences

 

array

of

struct ArraysOfSequences{

{

 

 

 

sequence<short,4>

array<DDS::ShortSeq^>^

 

 

sequences

sequences_array[2];

sequences_array;

 

 

 

 

};

// maximum length = (2)

 

 

 

 

 

};

 

 

 

 

 

 

 

 

bounded

struct PrimitiveStruct {

public ref class PrimitiveStruct {

 

System::String^ string_member;

 

string<20> string_member;

 

string

 

// maximum length = (20)

 

 

};

 

 

 

};

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

public ref class PrimitiveStruct {

 

 

 

 

System::String^ string_member;

 

unbounded

struct PrimitiveStruct {

// maximum length = (255)

 

string string_member;

};

 

 

 

string

 

};

Note: rtiddsgen will supply a default bound.

 

 

 

You can specify that bound with the -

 

 

 

stringSize

command-line

option,

see

 

 

 

Section 3.6.1.

 

 

 

 

 

 

 

 

bounded

struct PrimitiveStruct {

public ref class PrimitiveStruct {

 

System::String^ string_member;

 

wstring<20> wstring_member;

 

wstring

// maximum length = (20)

 

};

 

 

 

};

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

public ref class PrimitiveStruct {

 

 

 

 

System::String^ string_member; //

 

 

struct PrimitiveStruct {

maximum length = (255)

 

 

unbounded

};

 

 

 

wstring

wstring wstring_member;

Note: rtiddsgen will supply a default bound.

};

 

 

You can specify that bound with the -

 

 

 

 

 

 

stringSize

command-line

option,

see

 

 

 

Section 3.6.1.

 

 

 

 

 

 

 

 

 

 

 

module PackageName {

namespace PackageName {

 

 

module

struct Foo {

public ref class Foo {

 

 

long field;

System::Int32 field;

 

 

 

};

};

 

 

 

 

 

};

};

 

 

 

 

 

 

 

 

 

 

3-47

Table 3.7 Specifying Data Types in IDL for Java

IDL Type

Sample Entry in IDL file

Sample Java Output Generated by

rtiddsgen

 

 

 

 

 

 

 

char

 

 

public class PrimitiveStruct

 

 

struct PrimitiveStruct {

{

(see Note

5

char char_member;

public char char_member;

};

...

below)

 

 

}

 

 

 

 

wchar

 

 

public class PrimitiveStruct

 

 

struct PrimitiveStruct {

{

(see Note

5

wchar wchar_member;

public char wchar_member;

};

...

below)

 

 

}

 

 

 

 

 

 

 

public class PrimitiveStruct

octet

 

struct PrimitiveStruct {

{

 

octet octet_member;

public byte byte_member;

 

 

};

...

 

 

 

}

 

 

 

 

 

 

 

public class PrimitiveStruct

short

 

struct PrimitiveStruct {

{

 

short short_member;

public short short_member;

 

 

};

...

 

 

 

}

 

 

 

 

unsigned

 

struct PrimitiveStruct {

public class PrimitiveStruct

short

 

 

{

 

 

unsigned short

 

 

public short unsigned_short_member;

 

 

unsigned_short_member;

(see Note

6

...

};

}

below)

 

 

 

 

 

 

 

 

 

 

 

 

public class PrimitiveStruct

long

 

struct PrimitiveStruct {

{

 

long long_member;

public int long_member;

 

 

};

...

 

 

 

}

 

 

 

 

unsigned

 

struct PrimitiveStruct {

public class PrimitiveStruct

long

 

 

{

 

 

unsigned long

 

 

public int unsigned_long_member;

 

 

unsigned_long_member;

(see Note

6

...

};

}

below)

 

 

 

 

 

 

 

 

 

 

 

 

public class PrimitiveStruct

long long

 

struct PrimitiveStruct {

{

 

long long long_long_member;

public long long_long_member;

 

 

};

...

 

 

 

}

 

 

 

 

unsigned

 

 

public class PrimitiveStruct

long long

 

struct PrimitiveStruct {

{

 

 

unsigned long long

public long

(see Note

7

unsigned_long_long_member;

unsigned_long_long_member;

};

...

below)

 

 

}

 

 

 

 

 

 

 

public class PrimitiveStruct

float

 

struct PrimitiveStruct {

{

 

float float_member;

public float float_member;

 

 

};

...

 

 

 

}

 

 

 

 

3-48

Table 3.7 Specifying Data Types in IDL for Java

IDL Type

Sample Entry in IDL file

Sample Java Output Generated by

rtiddsgen

 

 

 

 

 

 

 

 

 

 

public class PrimitiveStruct

double

 

struct PrimitiveStruct {

{

 

double double_member;

public double double_member;

 

 

};

...

 

 

 

}

 

 

 

long double

 

public class PrimitiveStruct

 

 

struct PrimitiveStruct {

{

(see Note

7

long double long_double_member;

public double long_double_member;

};

...

below)

 

 

}

 

 

 

 

pointer

 

struct MyStruct {

public class MyStruct {

 

public int member;

(see Note

9

long * member;

...

below)

 

};

 

};

 

 

 

 

 

 

 

 

 

 

public class PrimitiveStruct

 

 

struct PrimitiveStruct {

{

boolean

 

boolean boolean_member;

public boolean boolean_member;

 

 

};

...

 

 

 

}

 

 

 

 

 

 

 

public class PrimitiveEnum extends Enum

 

 

 

{

 

 

 

public static PrimitiveEnum ENUM1 =

 

 

 

new PrimitiveEnum ("ENUM1", 0);

 

 

enum PrimitiveEnum {

public static PrimitiveEnum ENUM2 =

 

 

ENUM1,

new PrimitiveEnum ("ENUM2", 1);

 

 

ENUM2,

 

 

 

ENUM3

public static PrimitiveEnum ENUM3 =

 

 

};

new PrimitiveEnum ("ENUM3", 2);

 

 

 

public static PrimitiveEnum

 

 

 

valueOf(int ordinal);

 

 

 

...

enum

 

 

}

 

 

 

 

 

public class PrimitiveEnum extends Enum

 

 

 

 

 

 

{

 

 

 

public static PrimitiveEnum ENUM1 =

 

 

 

new PrimitiveEnum ("ENUM1", 10);

 

 

enum PrimitiveEnum {

public static PrimitiveEnum ENUM2 =

 

 

ENUM1 = 10,

new PrimitiveEnum ("ENUM2", 10);

 

 

ENUM2 = 20,

 

 

 

ENUM3 = 30

public static PrimitiveEnum ENUM3 =

 

 

};

new PrimitiveEnum ("ENUM3", 20);

 

 

 

public static PrimitiveEnum

 

 

 

valueOf(int ordinal);

 

 

 

...

 

 

 

}

 

 

 

 

constant

 

 

public class SIZE {

 

const short SIZE = 5;

public static final short VALUE = 5;

 

 

 

}

 

 

 

 

3-49

Table 3.7 Specifying Data Types in IDL for Java

IDL Type

Sample Entry in IDL file

Sample Java Output Generated by

rtiddsgen

 

 

 

 

 

 

 

 

 

struct BitfieldType {

public class BitfieldType

 

 

{

 

 

short myShort_1 : 1;

 

 

public short myShort_1;

 

 

long myLong_1: 1;

 

 

public int myLong_1;

 

 

char myChar_1 : 1;

 

 

public byte myChar_1;

 

 

wchar myWChar_1 : 1;

 

 

public char myWChar_1;

bitfield

 

octet myOctet_1 : 1;

 

public byte myOctet_1;

 

 

short : 0;

 

 

public int myLong_5;

 

 

long myLong_5 : 5;

(see Note 12

public int myLong_30;

long myLong_30 : 30;

public short myShort_6;

below)

 

short myShort_6 : 6;

 

public short myShort_3and4;

 

 

short myShort_3and4 : 3+4;

 

 

public short myShort;

 

 

short myShort;

 

 

public short myShort_8;

 

 

short myShort_8 : 8;

 

 

public int myLong_32;

 

 

long myLong_32: 32;

 

 

...

 

 

};

 

 

}

 

 

 

 

 

 

 

struct

 

 

public class PrimitiveStruct

 

struct PrimitiveStruct {

{

 

 

(see Note 10

char char_member;

public char char_member;

};

below)

 

 

}

 

 

 

 

 

 

 

union

 

union PrimitiveUnion switch (long){

public class PrimitiveUnion {

 

case 1:

public int _d;

 

 

 

 

short short_member;

public short short_member;

(see Note 10

default:

public int long_member;

below)

 

long long_member;

...

 

};

}

 

 

 

 

 

 

typedef

of

 

/* typedefs are unwounded to the original

primitives,

 

typedef short ShortType;

type when used */

enums,

 

 

 

public class PrimitiveStruct

strings

 

 

 

struct PrimitiveStruct {

{

 

 

ShortType short_member;

public short short_member;

(see Note

8

};

...

below)

 

 

}

 

 

 

 

 

 

 

typedef

of

 

/* Wrapper class */

sequences

 

 

public class ShortArray

or arrays

 

typedef short ShortArray[2];

{

 

public short[] userData = new

 

 

 

(see Note

8

 

short[2];

 

...

below)

 

 

}

 

 

 

 

 

 

 

public class OneDArrayStruct

 

 

struct OneDArrayStruct {

{

 

 

public short[] short_array = new

 

 

short short_array[2];

 

 

short[2];

 

 

};

 

 

...

 

 

 

array

 

 

}

 

 

 

 

 

public class TwoDArrayStruct

 

 

 

 

 

struct TwoDArrayStruct {

{

 

 

public short[][] short_array = new

 

 

short short_array[1][2];

 

 

short[1][2];

 

 

};

 

 

...

 

 

 

 

 

 

}

 

 

 

 

3-50

Table 3.7 Specifying Data Types in IDL for Java

IDL Type

Sample Entry in IDL file

Sample Java Output Generated by

rtiddsgen

 

 

 

 

 

 

 

 

 

 

public class SequenceStruct

bounded

 

 

{

sequence

 

struct SequenceStruct {

public ShortSeq short_sequence = new

 

 

sequence<short,4>

ShortSeq((4));

(see Note 11

short_sequence;

...

};

}

below)

 

 

Note: Sequences of primitive types have been

 

 

 

predefined by Connext.

 

 

 

 

 

 

 

public class SequenceStruct

unbounded

 

{

 

public ShortSeq short_sequence = new

sequence

 

struct SequenceStruct {

ShortSeq((100));

 

 

sequence<short> short_sequence;

...

(see Note 11

};

}

Note: rtiddsgen will supply a default bound. You

below)

 

 

 

 

can specify that bound with the “-sequenceSize”

 

 

 

 

 

 

command-line option; see Section 3.6.1.

 

 

 

 

 

 

 

public class ArraysOfSequences

array

of

struct ArraysOfSequences{

{

sequence<short,4>

public ShortSeq[] sequences_array =

sequences

 

sequences_array[2];

new ShortSeq[2];

 

 

};

...

 

 

 

}

 

 

 

 

 

 

 

/* Wrapper class */

 

 

 

public class ShortArray

 

 

 

{

 

 

 

public short[] userData = new

 

 

 

short[2];

 

 

 

...

 

 

 

}

sequence

of

typedef short ShortArray[2];

/* Sequence of wrapper class objects */

arrays

 

 

 

struct SequenceOfArrays{

public final class ShortArraySeq

 

 

 

 

extends ArraySequence

 

 

sequence<ShortArray,2>

(see Note 11

{

arrays_sequence;

...

below)

 

};

 

}

 

 

 

 

 

 

public class SequenceOfArrays

 

 

 

{

 

 

 

public ShortArraySeq arrays_sequence

 

 

 

= new ShortArraySeq((2));

 

 

 

...

 

 

 

}

 

 

 

 

3-51

Table 3.7 Specifying Data Types in IDL for Java

IDL Type

Sample Entry in IDL file

Sample Java Output Generated by

rtiddsgen

 

 

 

 

 

 

 

 

 

 

/* Wrapper class */

 

 

 

public class ShortSequence

 

 

 

{

 

 

 

public ShortSeq userData = new

 

 

 

ShortSeq((4));

 

 

 

...

 

 

 

}

sequence

of

typedef sequence<short,4>

/* Sequence of wrapper class objects */

sequences

 

ShortSequence;

 

public final class ShortSequenceSeq

 

 

 

 

 

struct SequencesOfSequences{

extends ArraySequence

(see Note

4

{

sequence<ShortSequence,2>

...

and Note 11

sequences_sequence;

}

below)

 

};

 

 

 

 

 

public class SequencesOfSequences

 

 

 

{

 

 

 

public ShortSequenceSeq

 

 

 

sequences_sequence = new

 

 

 

ShortSequenceSeq((2));

 

 

 

...

 

 

 

}

 

 

 

 

 

 

 

public class PrimitiveStruct

 

 

 

{

bounded

 

struct PrimitiveStruct {

public String string_member = new

 

string<20> string_member;

String();

string

 

 

};

/* maximum length = (20) */

 

 

 

 

 

...

 

 

 

}

 

 

 

 

 

 

 

public class PrimitiveStruct

 

 

 

{

 

 

 

public String string_member = new

 

 

struct PrimitiveStruct {

String();

unbounded

/* maximum length = (255) */

string

 

string string_member;

...

 

};

 

 

}

 

 

 

 

 

 

Note: rtiddsgen will supply a default bound. You

 

 

 

can specify that bound with the -stringSize

 

 

 

command-line option, see Section 3.6.1.

 

 

 

 

 

 

 

public class PrimitiveStruct

 

 

 

{

bounded

 

struct PrimitiveStruct {

public String wstring_member = new

 

wstring<20> wstring_member;

String();

wstring

 

 

};

/* maximum length = (20) */

 

 

 

 

 

...

 

 

 

}

 

 

 

 

 

 

 

public class PrimitiveStruct

 

 

 

{

unbounded

struct PrimitiveStruct {

public String wstring_member = new

String();

wstring

 

wstring wstring_member;

/* maximum length = (255) */

 

};

 

 

...

 

 

 

 

 

 

}

 

 

 

Note: rtiddsgen will supply a default bound.

 

 

 

 

3-52

Table 3.7 Specifying Data Types in IDL for Java

IDL Type

Sample Entry in IDL file

Sample Java Output Generated by

rtiddsgen

 

 

 

 

 

 

 

 

 

 

package PackageName;

 

 

module PackageName {

 

 

 

struct Foo {

public class Foo

 

module

long field;

{

 

 

};

public int field;

 

 

};

 

 

 

}

 

 

 

 

 

 

 

public class MyValueType

{

 

 

public MyValueType2 member;

 

valuetype MyValueType {

….

 

 

public MyValueType2 * member;

};

 

 

};

 

 

valuetype

 

public class MyValueType

{

 

valuetype MyValueType {

public MyValueType2 member;

(see Note 9

public MyValueType2 member;

….

 

};

};

 

and Note 10

 

 

 

below)

valuetype MyValueType:

public class MyValueType extends

 

MyBaseValueType {

MyBaseValueType

 

 

public MyValueType2 * member;

{

 

 

};

public MyValueType2 member;

 

 

….

 

 

 

}

 

 

 

 

 

Notes for Table 3.5 through Table 3.7:

1.Note that in C and C++, primitive types are not represented as native language types (e.g. long, char, etc.) but as custom types in the DDS namespace (DDS_Long, DDS_Char, etc.). These typedefs are used to ensure that a field’s size is the same across platforms.

2.Some platforms do not support long double or have different sizes for that type than defined by IDL (16 bytes). On such platforms, DDS_LongDouble (as well as the unsigned version) is mapped to a character array that matches the expected size of that type by default. If you are using a platform whose native mapping has exactly the expected size, you can instruct Connext to use the native type instead. That is, if sizeof(long double) == 16, you can tell Connext to map DDS_LongDouble to long double by defining the following macro either in code or on the compile line:

-DRTI_CDR_SIZEOF_LONG_DOUBLE=16

Not

Supported—>

Supported—>

3.Unions in IDL are mapped to structs in C and C++, so that Connext will not have to dynamically allocate memory for unions containing variable-length fields such as strings or sequences. To be efficient, the entire struct (or class in C++/CLI) is not sent when the union is published. Instead, Connext uses the discriminator field of the struct to decide what field in the struct is actually sent on the wire.

4.So-called "anonymous sequences" —sequences of sequences in which the sequence element has no type name of its own—are not supported. Such sequences are deprecated in CORBA and may be removed from future versions of IDL. For example, this is not supported:

sequence<sequence<short,4>,4> MySequence;

Sequences of typedef’ed types, where the typedef is really a sequence, are supported. For example, this is supported:

typedef sequence<short,4> MyShortSequence;

3-53

Not

Supported—>

sequence<MyShortSequence,4> MySequence;

5.IDL wchar and char are mapped to Java char, 16-bit unsigned quantities representing Unicode characters as specified in the standard OMG IDL to Java mapping. In C++/CLI, char and wchar are mapped to System::Char.

6.There are no unsigned types in Java. The unsigned version for integer types is mapped to its signed version as specified in the standard OMG IDL to Java mapping.

7.There is no current support in Java for the IDL long double type. This type is mapped to double as specified in the standard OMG IDL to Java mapping.

8.Java does not have a typedef construct, nor does C++/CLI. Typedefs for types that are neither arrays nor sequences (struct, unions, strings, wstrings, primitive types and enums) are "unwound" to their original type until a simple IDL type or user-defined IDL type (of the non-typedef variety) is encountered. For typedefs of sequences or arrays, rtiddsgen will generate wrapper classes.

9.In C and C++, all the members in a value type, structure or union that are declared with the pointer symbol (‘*’) will be mapped to references (pointers). In C++/CLI and Java, the pointer symbol is ignored because the members are always mapped as references.

10.In-line nested types are not supported inside structures, unions or valuetypes. For example, this is not supported:

struct Outer {

short outer_short; struct Inner {

char inner_char; short inner_short;

} outer_nested_inner;

};

 

11. The sequence <Type>Seq is implicitly declared in the IDL file and therefore it cannot be

 

declared explicitly by the user. For example, this is not supported:

Not

 

Supported—>

typedef sequence<Foo> FooSeq; //error

12.Data types containing bitfield members are not supported by DynamicData (Section 3.8).

3.3.5Escaped Identifiers

To use an IDL keyword as an identifier, the keyword must be “escaped” by prepending an underscore, ‘_’. In addition, you must run rtiddsgen with the -enableEscapeChar option. For example:

struct MyStruct {

octet _octet; // octet is a keyword. To use the type // as a member name we add ‘_’

};

The use of ‘_’ is a purely lexical convention that turns off keyword checking. The generated code will not contain ‘_’. For example, the mapping to C would be as follows:

struct MyStruct { unsigned char octet;

};

Note: If you generate code from an IDL file to a language ‘X’ (for example, C++), the keywords of this language cannot be used as IDL identifiers, even if they are escaped. For example:

struct MyStruct { long int; // error

3-54

long _int; // error

};

3.3.6Referring to Other IDL Files

IDL files may refer to other IDL files using a syntax borrowed from C, C++, and C++/CLI preprocessors:

#include “Bar.idl”

If such a statement is encountered by rtiddsgen and you are generating code for C, C++, and C++/CLI, rtiddsgen will assume that code has been generated for Bar.idl with corresponding header files, Bar.h and BarPlugin.h.

The generated code will automatically have:

#include “Bar.h” #include “BarPlugin.h”

added where needed to compile correctly.

Because Java types do not refer to one another in the same way, it is not possible for rtiddsgen to automatically generate Java import statements based on an IDL #include statement. Any #include statements will be ignored when Java code is generated. To add imports to your generated Java code, you should use the //@copy directive (see Section 3.3.8.2).

3.3.7Preprocessor Directives

rtiddsgen supports the standard preprocessor directives defined by the IDL specification, such as

#if, #endif, #include, and #define.

To support these directives, rtiddsgen calls an external C preprocessor before parsing the IDL file. On Windows systems, the preprocessor is ‘cl.exe.’ On other architectures, the preprocessor is ‘cpp.’ You can change the default preprocessor with the –ppPath option. If you do not want to run the preprocessor, use the –ppDisable option. See rtiddsgen Command-Line Arguments (Section 3.6.1).

3.3.8Using Custom Directives

The following rtiddsgen-specific directives can be used in your IDL file:

//@key (see Section 3.3.8.1)

//@copy (see Section 3.3.8.2) //@copy-c

//@copy-cppcli //@copy-java //@copy-java-begin

//@copy-declaration //@copy-c-declaration //@copy-cppcli-declaration //@copy-java-declaration

//@copy-java-declaration-begin //@resolve-name [true | false] (see Section 3.3.8.3) //@top-level [true | false] (see Section 3.3.8.4)

3-55

Custom directives start with “//@”. Note: Do not put a space between the slashes and the @, or the directive will not be recognized by rtiddsgen.

The directives are also case-sensitive. For instance, you must use //@key (not //@Key).

3.3.8.1The @key Directive

To declare a key for your data type, insert the @key directive in the IDL file after one or more fields of the data type.

With each key, Connext associates an internal 16-byte representation, called a key-hash.

If the maximum size of the serialized key is greater than 16 bytes, to generate the key-hash, Connext computes the MD5 key-hash of the serialized key in network-byte order. Otherwise (if the maximum size of the serialized key is <= 16 bytes), the key-hash is the serialized key in network-byte order.

Only struct definitions in IDL may have key fields. When rtiddsgen encounters //@key, it considers the previously declared field in the enclosing structure to be part of the key. Table 3.8 on page 3-56 shows some examples of keys.

Table 3.8 Example Keys

Type

Key Fields

 

 

 

 

struct NoKey {

 

long member1;

 

long member2;

 

}

 

 

 

struct SimpleKey {

 

long member1; //@key

member1

long member2;

 

}

 

 

 

struct NestedNoKey {

 

SimpleKey member1;

 

long member2;

 

}

 

 

 

struct NestedKey {

 

SimpleKey member1; //@key

member1.member1

long member2;

 

}

 

 

 

struct NestedKey2 {

 

NoKey member1; //@key

member1.member1

long member2;

member1.member2

}

 

 

 

valuetype BaseValueKey {

 

public long member1; //@key

member1

}

 

 

 

valuetype DerivedValueKey :BaseValueKey {

member1

public long member2; //@key

member2

}

 

 

 

valuetype DerivedValue : BaseValueKey {

 

public long member2;

member1

}

 

 

 

struct ArrayKey {

member1[0]

long member1[3]; //@key

member1[1]

}

member1[2]

 

 

3-56

3.3.8.2The @copy and Related Directives

To copy a line of text verbatim into the generated code files, use the @copy directive in the IDL file. This feature is particularly useful when you want your generated code to contain text that is valid in the target programming language but is not valid IDL. It is often used to add user comments or headers or preprocessor commands into the generated code.

//@copy // Modification History

//@copy // --------------------

//@copy // 17Jul05aaa, Created.

//@copy

//@copy // #include “MyTypes.h”

These variations allow you to use the same IDL file for multiple languages:

@copy-c

Copies code if the language is C or C++

 

 

@copy-cppcli

Copies code if the language is C++/CLI

 

 

@copy-java

Copies code if the language is Java.

 

 

@copy-ada

Copies code if the language is Ada.

 

 

For example, to add import statements to generated Java code:

//@copy-java import java.util.*;

The above line would be ignored if the same IDL file was used to generate non-Java code.

In C, C++, and C++/CLI, the lines are copied into all of the “foo*.[h, c, cxx, cpp]” files generated from “foo.idl”. For Java, the lines are copied into all of the “*.java” files that were generated from the original “.idl” file. The lines will not be copied into any additional files that are generated using the -example command line option.

@copy-java-begin copies a line of text at the beginning of all the Java files generated for a type. The directive only applies to the first type that is immediately below in the IDL file. A similar directive for Ada files is also available, @copy-ada-begin.

If you want rtiddsgen to copy lines only into the files that declare the data types—”foo.h for C, C++, and C++/CLI, “foo.java” for Java—use the “//@copy*declaration” forms of this directive.

Note that the first whitespace character to follow “//@copy” is considered a delimiter and will not be copied into generated files. All subsequent text found on the line, including any leading whitespaces will be copied.

//@copy-declaration

Copies the text into the file where the type is declared (<type>.h for C

and C++, or <type>.java for Java)

 

 

 

//@copy-c-declaration

Same as //@copy-declaration, but for C and C++ code

 

 

//@copy-cppcli-declaration

Same as //@copy-declaration, but for C++/CLI code

 

 

//@copy-java-declaration

Same as //@copy-declaration, but for Java-only code

 

 

//@copy-ada-declaration

Same as //@copy-declaration, but for Ada-only code

 

 

//@copy-java-declaration-begin

Same as //@copy-java-declaration, but only copies the text into the

file where the type is declared

 

 

 

//@copy-ada-declaration-begin

Same as //@copy-java-declaration-begin, but only for Ada-only code

 

 

3-57

3.3.8.3The @resolve-name Directive

In IDL, the “module” keyword is used to create namespaces for the declaration of types and classes defined within the file. Here is an example IDL definition:

module PackageName { struct Foo {

long field;

};

};

For C++ and C++/CLI, you may use the -namespace command-line option, which causes rtiddsgen to generate a namespace, such as the following:

namespace PackageName{ typedef struct Foo {

DDS_Long field;

}Foo;

}PackageName;

When generating C++/CLI, the -namespace option is considered to always be passed. Module names are never prepended to class names.

For C, or if you do not use the -namespace command-line option for C++ or C++/CLI, the name of the module is concatenated with the name of the structure to create the namespace. The resulting code looks like this:

typedef struct PackageName_Foo { DDS_Long field;

} PackageName_Foo;

In Java, a Foo.java file will be created in a directory called PackageName to use the equivalent concept as defined by Java. The file PackageName/Foo.java will contain a declaration of Foo class:

public class Foo { public int field;

...

};

In a more complicated example, consider the following IDL definition:

module PackageName { struct Bar {

long field;

};

struct Foo {

Bar barField;

};

};

When rtiddsgen generates code for the above definition, it will resolve the “Bar” type to be within the scope of the PackageName module and automatically generate fully-qualified type names.

In C or C++, if you do not use -namespace, the resulting code will be:

typedef struct PackageName_Bar { DDS_Long field;

} PackageName_Foo;

typedef struct PackageName_Foo { PackageName_Bar barField;

} PackageName_Foo;

3-58

In C++, if you use -namespace, the resulting code will be:

namespace PackageName { typedef struct Bar {

DDS_Long field; } Bar;

typedef struct Foo

{

PackageName::Bar barField; } Foo;

}

And in Java, PackageName/Bar.java and PackageName/Foo.java would be created with the following code respectively:

public class Bar { public int field;

...

};

and

public class Foo {

public PackageName.Bar barField = PackageName.Bar.create();

...

};

However, sometimes you may not want rtiddsgen to resolve the types of variables when modules are used. In the example above, instead of referring to the Bar as defined by the same package, you may want the barField in Foo to use Bar directly without prepending a module name. To specify that rtiddsgen should not resolve the scope of a type, use the //@resolve-name false’ directive.

For example:

module PackageName { struct Bar {

long field;

};

struct Foo {

Bar barField; //@resolve-name false

};

};

When this directive is used, then for the field preceding the directive, rtiddsgen respects the resolution of its type name indicated in the IDL file. It will use the type unmodified in the generated code. In C and C++:

typedef struct PackageName_Bar { DDS_Long field;

} PackageName_Foo;

typedef struct PackageName_Foo { Bar barField;

} PackageName_Foo;

And in Java, in PackageName/Bar.java and PackageName/Foo.java respectively:

public class Bar { public int field;

...

3-59

};

and

public class Foo {

public Bar barField = Bar.create();

...

};

It is up to you to include the correct header files (or if using Java, to import the correct packages) so that the compiler resolves the ‘Bar’ type correctly.

When used at the end of the declaration of a structure in IDL, then the directive applies to all types within the structure.

struct MyStructure { Foo member1;

Bar member2;

}; //@resolve-name false

By default, without using the directive, rtiddsgen will try to resolve the type of a field and to use the fully qualified name in the generated code. If the type is not found to be defined within the same scope as the structure in which it is used or in a parent scope, then rtiddsgen will generate code with just the type name itself, assuming that the name will be resolved by the compiler through other means available to the user (header files or import statements). A type is in the same scope as the structure if both the type and the structure in which it is used are defined within the same module.

3.3.8.4The @top-level Directive

By default, rtiddsgen generates user-level type-specific methods for all structures/unions found in an IDL file. These methods include the methods used by DataWriters and DataReaders to send and receive data of a given type. General methods for writing and reading that take a void pointer are not offered by Connext because they are not type safe. Instead, type-specific methods must be created to support a particular data type.

We use the term ‘top-level type’ to refer to the data type for which you intend to create a DCPS Topic that can be published or subscribed to. For top-level types, rtiddsgen must create all of the type-specific methods previously described in addition to the code to serialize/deserialize those types. However, some of structures/unions defined in the IDL file are only embedded within higher-level structures and are not meant to be published or subscribed to individually. For non- top-level types, the DataWriters and DataReaders methods to send or receive data of those types are superfluous and do not need to be created. Although the existence of these methods is not a problem in and of itself, code space can be saved if these methods are not generated in the first place.

You can mark non-top-level types in an IDL file with the directive //@top-level false’ to tell rtiddsgen not to generate type-specific methods. Code will still be generated to serialize and deserialize those types, since they may be embedded in top-level types.

In this example, rtiddsgen will generate DataWriter/DataReader code for TopLevelStruct only:

struct EmbeddedStruct{ short member;

}; //@top-level false

struct TopLevelStruct{ EmbeddedStruct member;

};

3-60

3.4Creating User Data Types with Extensible Markup Language (XML)

You can describe user data types with Extensible Markup Language (XML) notation. Connext provides DTD and XSD files that describe the XML format; see <NDDSHOME>/resource/ qos_profiles_5.0.x/rtiddsgen/schema/rti_dds_topic_types.dtd and <NDDSHOME>/resource/ qos_profiles_5.0.x/rtiddsgen/schema/rti_dds_topic_types.xsd, respectively (in 5.0.x, the x stands for the revision number of the current release).

The XML validation performed by rtiddsgen always uses the DTD definition. If the <!DOCTYPE> tag is not in the XML file, rtiddsgen will look for the default DTD document in <NDDSHOME>/resource/rtiddsgen/schema. Otherwise, it will use the location specified in <!DOCTYPE>.

We recommend including a reference to the XSD/DTD files in the XML documents. This provides helpful features in code editors such as Visual Studio® and Eclipse™, including validation and auto-completion while you are editing the XML. We recommend including the reference to the XSD document in the XML files because it provides stricter validation and better auto-completion than the DTD document.

To include a reference to the XSD document in your XML file, use the attribute xsi:noNamespaceSchemaLocation in the <types> tag. For example1:

<?xml version="1.0" encoding="UTF-8"?>

<types xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation=

"<same as NDDSHOME>/resource/rtiddsgen/schema/rti_dds_topic_types.xsd">

...

</types>

To include a reference to the DTD document in your XML file, use the <!DOCTYPE> tag. For example1:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE types SYSTEM

"<same as NDDSHOME>/resource/rtiddsgen/schema/rti_dds_topic_types.dtd"> <types>

...

</types>

Table 3.9 shows how to map the type system constructs into XML.

Table 3.9 Mapping Type System Constructs to XML

 

Type/Construct

 

Example

 

 

 

 

 

IDL

 

XML

IDL

XML

 

 

 

 

 

 

 

 

struct PrimitiveStruct {

<struct name="PrimitiveStruct">

char

 

char

<member name="char_member"

 

char char_member;

 

type="char"/>

 

 

 

};

 

 

 

</struct>

 

 

 

 

 

 

 

 

 

 

 

 

struct PrimitiveStruct {

<struct name="PrimitiveStruct">

wchar

 

wchar

<member name="wchar_member"

 

wchar wchar_member;

 

type="wchar"/>

 

 

 

};

 

 

 

</struct>

 

 

 

 

 

 

 

 

 

1. Replace <same as NDDSHOME> with the full path to the Connext installation directory.

3-61

Table 3.9 Mapping Type System Constructs to XML

Type/Construct

 

Example

 

 

 

 

IDL

XML

IDL

XML

 

 

 

 

 

 

struct PrimitiveStruct {

<struct name="PrimitiveStruct">

octet

octet

<member name="octet_member"

octet octet_member;

type="octet"/>

 

 

};

 

 

</struct>

 

 

 

 

 

 

 

 

 

struct PrimitiveStruct {

<struct name="PrimitiveStruct">

short

short

<member name="short_member"

short short_member;

type="short"/>

 

 

};

 

 

</struct>

 

 

 

 

 

 

 

 

 

struct PrimitiveStruct {

<struct name="PrimitiveStruct">

unsigned short

unsignedShort

unsigned short

<member name="unsigned_short_member"

unsigned_short_member;

type="unsignedShort"/>

 

 

 

 

};

</struct>

 

 

 

 

long

long

struct PrimitiveStruct {

<struct name="PrimitiveStruct">

long long_member;

<member name="long_member"type="long"/>

 

 

};

</struct>

 

 

 

 

 

 

struct PrimitiveStruct {

<struct name="PrimitiveStruct">

unsigned long

unsignedLong

unsigned long

<member name= "unsigned_long_member"

unsigned_long_member;

type="unsignedLong"/>

 

 

 

 

};

</struct>

 

 

 

 

 

 

struct PrimitiveStruct {

<struct name="PrimitiveStruct">

long long

longLong

long long

<member name="long_long_member"

long_long_member;

type="longLong"/>

 

 

 

 

};

</struct>

 

 

 

 

unsigned long

 

struct PrimitiveStruct {

<struct name="PrimitiveStruct">

unsignedLongLong

unsigned long long

<member name="unsigned_long_long_member"

long

unsigned_long_long_member;

type="unsignedLongLong"/>

 

 

 

};

</struct>

 

 

 

 

 

 

struct PrimitiveStruct {

<struct name="PrimitiveStruct">

float

float

<member name="float_member"

float float_member;

type="float"/>

 

 

};

 

 

</struct>

 

 

 

 

 

 

 

 

 

struct PrimitiveStruct {

<struct name="PrimitiveStruct">

double

double

<member name="double_member"

double double_member;

type="double"/>

 

 

};

 

 

</struct>

 

 

 

 

 

 

 

 

 

struct PrimitiveStruct {

<struct name="PrimitiveStruct">

long double

longDouble

long double

<member name= "long_double_member"

long_double_member;

type="longDouble"/>

 

 

 

 

};

</struct>

 

 

 

 

 

 

struct PrimitiveStruct {

<struct name="PrimitiveStruct">

boolean

boolean

<member name="boolean_member"

boolean boolean_member;

type="boolean"/>

 

 

};

 

 

</struct>

 

 

 

 

 

 

 

 

 

 

<struct name="PrimitiveStruct">

 

string without

 

<member name="string_member"

 

 

type="string"/>

unbounded

stringMaxLength

struct PrimitiveStruct {

</struct>

attribute or with

string string_member;

or

string

stringMaxLength set to

};

<struct name="PrimitiveStruct">

 

 

-1

 

<member name="string_member"

 

 

 

type="string" stringMaxLength="-1"/>

 

 

 

</struct>

 

 

 

 

 

string with

struct PrimitiveStruct {

<struct name="PrimitiveStruct">

 

<member name="string_member"

bounded string

stringMaxLength

string<20> string_member;

type="string" stringMaxLength="20"/>

 

attribute

};

 

</struct>

 

 

 

 

 

 

 

3-62

Table 3.9 Mapping Type System Constructs to XML

Type/Construct

 

Example

 

 

 

 

IDL

XML

IDL

XML

 

 

 

 

 

 

 

<struct name="PrimitiveStruct">

 

wstring without

 

<member name="wstring_member"

 

 

type="wstring"/>

unbounded

stringMaxLength

struct PrimitiveStruct {

</struct>

attribute or with

wstring wstring_member;

or

wstring

stringMaxLength set to

};

<struct name="PrimitiveStruct">

 

 

-1

 

<member name="wstring_member"

 

 

 

type="wstring" stringMaxLength="-1"/>

 

 

 

</struct>

 

 

 

 

bounded

wstring with

struct PrimitiveStruct {

<struct name="PrimitiveStruct">

wstring<20>

<member name="wstring_member"

stringMaxLength

wstring

wstring_member;

type="wstring" stringMaxLength="20"/>

attribute

 

};

</struct>

 

 

 

 

 

 

 

pointer attribute with

struct PrimitiveStruct {

<struct name="PointerStruct">

 

values true,false,0 or 1

pointer

<member name="long_member" type="long"

long * long_member;

Default (if not present):

pointer="true"/>

 

};

 

</struct>

 

0

 

 

 

 

 

 

 

 

 

 

 

<struct name="BitFieldStruct">

 

 

struct BitfieldStruct {

<member name="short_member"

 

 

short short_member: 1;

type="short" bitField="1"/>

bitfielda

bitfield attribute with

unsigned short

<member name="unsignedShort_member"

unsignedShort_member: 1;

type="unsignedShort" bitField="1"/>

the bitfield length

 

short short_nmember_2: 0;

<member type="short" bitField="0"/>

 

 

 

 

long long_member : 5;

<member name="long_member"

 

 

};

type="long" bitField="5"/>

 

 

 

</struct>

 

 

 

 

 

key attribute with

struct KeyedPrimitiveStruct

 

 

values true, false, 0 or 1

<struct name="KeyedPrimitiveStruct">

 

{

 

 

 

key directive b

 

short short_member; //

<member name="short_member"

 

type="short" key="true"/>

 

Default (if not present):

@key

 

</struct>

 

0

};

 

 

 

 

 

 

 

 

 

resolveName attribute

struct

<struct name=

 

with values true, false, 0

resolve-name

or 1

UnresolvedPrimitiveStruct {

"UnresolvedPrimitiveStruct">

PrimitiveStruct

<member name="primitive_member"

directive b

 

primitive_member;

type="PrimitiveStruct"

 

Default (if not present):

//@resolve-name false

resolveName="false"/>

 

};

</struct>

 

1

 

 

 

 

 

 

 

 

topLevel

 

 

 

attribute with values

struct

<struct name="TopLevelPrimitiveStruct"

top-level

true, false, 0 or 1

topLevel="false">

TopLevelPrimitiveStruct {

<member name="short_member"

directive b

 

short short_member;

 

type="short"/>

 

Default (if not present):

}; //@top-level false

 

</struct>

 

1

 

 

 

 

 

 

Other directives

 

//@copy This text will be

<directive kind="copy">

directive tag

This text will be copied in the

copied in the generated

b

generated files

 

 

files

 

 

</directive>

 

 

 

 

 

 

 

3-63

Table 3.9 Mapping Type System Constructs to XML

 

Type/Construct

 

Example

 

 

 

 

 

IDL

 

XML

IDL

XML

 

 

 

 

 

 

 

 

enum PrimitiveEnum {

<enum name="PrimitiveEnum">

 

 

 

ENUM1,

<enumerator name="ENUM1"/>

 

 

 

ENUM2,

<enumerator name="ENUM2"/>

 

 

 

ENUM3

<enumerator name="ENUM3"/>

enum

 

enum tag

};

</enum>

 

 

 

 

enum PrimitiveEnum {

<enum name="PrimitiveEnum">

 

 

 

 

 

 

ENUM1 = 10,

<enumerator name="ENUM1" value="10"/>

 

 

 

ENUM2 = 20,

<enumerator name="ENUM2" value="20"/>

 

 

 

ENUM3 = 30

<enumerator name="ENUM3" value="30"/>

 

 

 

};

</enum>

 

 

 

 

 

constant

 

const tag

const double PI = 3.1415;

<const name="PI" type="double"

 

value="3.1415"/>

 

 

 

 

 

 

 

 

 

 

 

 

struct PrimitiveStruct {

<struct name="PrimitiveStruct">

struct

 

struct tag

<member name="short_member"

 

short short_member;

 

type="short"/>

 

 

 

};

 

 

 

</struct>

 

 

 

 

 

 

 

 

 

 

 

 

 

<union name="PrimitiveUnion">

 

 

 

 

<discriminator type="long"/>

 

 

 

 

<case>

 

 

 

 

<caseDiscriminator value="1"/>

 

 

 

union PrimitiveUnion switch

<member name="short_member"

 

 

 

type="short"/>

 

 

 

(long) {

 

 

 

</case>

 

 

 

case 1:

 

 

 

<case>

 

 

 

short short_member;

 

 

 

<caseDiscriminator value="2"/>

union

 

union tag

case 2:

 

<caseDiscriminator value="3"/>

 

case 3:

 

 

 

<member name="float_member"

 

 

 

float float_member;

 

 

 

type="float"/>

 

 

 

default:

 

 

 

</case>

 

 

 

long long_member;

 

 

 

<case>

 

 

 

};

 

 

 

<caseDiscriminator value="default"/>

 

 

 

 

 

 

 

 

<member name="long_member"

 

 

 

 

type="long"/>

 

 

 

 

</case>

 

 

 

 

</union>

 

 

 

 

 

 

 

 

valuetype BaseValueType {

<valuetype name="BaseValueType">

 

 

 

<member name="long_member"

 

 

 

public long long_member;

 

 

 

type="long" visibility="public"/>

 

 

 

};

 

 

 

</valuetype>

 

 

 

 

valuetype

 

valuetype tag

valuetype DerivedValueType:

<valuetype name="DerivedValueType"

 

 

 

BaseValueType {

 

 

 

baseClass="BaseValueType">

 

 

 

public long

 

 

 

<member name="long_member_2"

 

 

 

long_member_2;

 

 

 

type="long" visibility="public"/>

 

 

 

};

 

 

 

</valuetype>

 

 

 

 

 

 

 

 

 

 

 

 

typedef short ShortType;

<typedef name="ShortType" type="short"/>

 

 

 

 

 

 

 

 

 

<struct name="PrimitiveStruct">

 

 

 

struct PrimitiveStruct {

<member name="short_member"

 

 

 

type="short"/>

typedef

 

typedef tag

short short_member;

 

</struct>

 

};

 

 

 

 

 

 

 

typedef PrimitiveStruct

<typedef name="PrimitiveStructType"

 

 

 

PrimitiveStructType;

 

 

 

type="nonBasic"

 

 

 

 

 

 

 

 

nonBasicTypeName="PrimitiveStruct"/>

 

 

 

 

 

3-64

Table 3.9 Mapping Type System Constructs to XML

 

Type/Construct

 

Example

 

 

 

 

 

IDL

 

XML

IDL

XML

 

 

 

 

 

 

 

 

struct OneArrayStruct {

<struct name="OneArrayStruct">

 

 

 

<member name="short_array"

 

 

 

short short_array[2];

 

 

 

type="short" arrayDimensions="2"/>

 

 

 

};

 

 

Attribute

</struct>

arrays

 

 

 

arrayDimensions

struct TwoArrayStruct {

<struct name="TwoArrayStruct">

 

 

 

 

 

<member name="short_array"

 

 

 

short short_array[1][2];

 

 

 

type="short" arrayDimensions="1,2"/>

 

 

 

};

 

 

 

</struct>

 

 

 

 

 

 

 

 

 

 

 

Attribute

struct SequenceStruct {

<struct name="SequenceStruct">

bounded

 

<member name="short_sequence"

 

sequence<short,4>

 

sequenceMaxLength >

type="short"

sequence

 

short_sequence;

 

0

sequenceMaxLength="4"/>

 

 

};

 

 

 

</struct>

 

 

 

 

 

 

 

 

 

unbounded

 

Attribute

struct SequenceStruct {

<struct name="SequenceStruct">

 

sequence<short>

<member name="short_sequence"

 

sequenceMaxLength set

sequence

 

short_sequence;

type="short" sequenceMaxLength="-1"/>

 

to -1

 

 

};

</struct>

 

 

 

 

 

 

 

 

 

 

Attributes

struct

<struct name= "ArrayOfSequenceStruct">

array of

 

ArrayOfSequencesStruct {

<member name= "short_sequence_array"

 

sequenceMaxLength

sequence<short,4>

type="short" arrayDimensions="2"

sequences

 

 

And arrayDimensions

short_sequence_array[2];

sequenceMaxLength="4"/>

 

 

 

 

 

};

</struct>

 

 

 

 

 

 

 

 

 

<typedef name="ShortArray"

 

 

 

typedef short

type="short" dimensions="2"/>

 

 

 

ShortArray[2];

 

sequence of

 

Must be implemented

 

<struct name=

 

struct

"SequenceOfArrayStruct">

arrays

 

with a typedef tag

SequenceOfArraysStruct {

<member name= "short_array_sequence"

 

 

 

sequence<ShortArray,2>

type="nonBasic"

 

 

 

short_array_sequence;

nonBasicTypeName="ShortSequence"

 

 

 

};

sequenceMaxLength="2"/>

 

 

 

 

</struct>

 

 

 

 

 

 

 

 

typedef sequence<short,4>

<typedef name="ShortSequence"

 

 

 

ShortSequence;

 

 

 

type="short"sequenceMaxLength="4"/>

 

 

 

 

sequence of

 

Must be implemented

struct

<struct name="SequenceofSequencesStruct">

 

<member name="short_sequence_sequence"

 

SequenceOfSequencesStruct

sequences

 

with a typedef tag

type="nonBasic"

 

{

 

 

 

nonBasicTypeName="ShortSequence"

 

 

 

sequence<ShortSequence,2>

 

 

 

sequenceMax-Length="2"/>

 

 

 

short_sequence_sequence;

 

 

 

</struct>

 

 

 

};

 

 

 

 

 

 

 

 

 

 

 

 

module PackageName {

<module name="PackageName">

module

 

module tag

struct PrimitiveStruct {

<struct name="PrimitiveStruct">

 

long long_member;

<member name="long_member" type="long"/>

 

 

 

};

</struct>

 

 

 

};

</module>

 

 

 

 

 

include

 

include tag

#include

<include file="PrimitiveTypes.xml"/>

 

"PrimitiveTypes.idl"

 

 

 

 

 

 

 

 

 

a.Data types containing bitfield members are not supported by DynamicData (Section 3.8).

b.Directives are RTI extensions to the standard IDL grammar. For additional information about directives see Using Custom Directives (Sec- tion 3.3.8).

3-65

3.5Creating User Data Types with XML Schemas (XSD)

You can describe data types with XML schemas (XSD), either independent or embedded in a Web Services Description Language (WSDL) file. The format is based on the standard IDL-to- WSDL mapping described in the OMG document "CORBA to WSDL/SOAP Interworking Specification." Defining a mapping between IDL and WSDL types enables integration between Connext and Web Services Technologies using WSDL.

Example Header for XSD:

<?xml version="1.0" encoding="UTF-8"?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:dds="http://www.omg.org/dds" xmlns:tns="http://www.omg.org/IDL-Mapped/" targetNamespace="http://www.omg.org/IDL-Mapped/"> <xsd:import namespace="http://www.omg.org/dds" schemaLocation="rti_dds_topic_types_common.xsd"/>

……

</xsd:schema>

Example Header for WSDL:

<?xml version="1.0" encoding="UTF-8"?>

<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:dds="http://www.omg.org/dds" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://www.omg.org/IDL-Mapped/" targetNamespace="http://www.omg.org/IDL-Mapped/"> <types>

<xsd:schema targetNamespace="http://www.omg.org/IDL-Mapped/"> <xsd:import namespace="http://www.omg.org/dds"

schemaLocation="rti_dds_topic_types_common.xsd"/>

……

</xsd:schema>

</types>

</definitions>

Table 3.10 describes how to map IDL types to XSD. The Connext code generator, rtiddsgen, will only accept XSD or WSDL files that follow this mapping.

Table 3.10 Mapping Type System Constructs to XSD

 

Type/Construct

 

Example

 

 

 

 

 

IDL

 

XSD

IDL

XSD

 

 

 

 

 

 

 

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

 

 

<xsd:sequence>

char

 

dds:chara

struct PrimitiveStruct {

<xsd:element name="char_member"

 

char char_member;

minOccurs="1" maxOccurs="1"

 

 

 

};

type="dds:char">

 

 

 

 

</xsd:sequence>

 

 

 

 

</xsd:complexType>

 

 

 

 

 

3-66

Table 3.10 Mapping Type System Constructs to XSD

Type/Construct

 

Example

 

 

 

 

IDL

XSD

IDL

XSD

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

 

<xsd:sequence>

 

dds:wchara

struct PrimitiveStruct {

<xsd:element name="wchar_member"

wchar

wchar wchar_member;

minOccurs="1" maxOccurs="1"

 

 

};

type="dds:wchar">

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

 

<xsd:sequence>

octet

xsd:unsignedByte

struct PrimitiveStruct {

<xsd:element name="octet_member"

octet octet_member;

minOccurs="1" maxOccurs="1"

 

 

};

type="xsd:unsignedByte">

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

 

<xsd:sequence>

 

 

struct PrimitiveStruct {

<xsd:element name="short_member"

short

xsd:short

short short_member;

minOccurs="1" maxOccurs="1"

 

 

};

type="xsd:short"/>

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

struct PrimitiveStruct {

<xsd:sequence>

unsigned

 

<xsd:element name="unsigned_short_member"

xsd:unsignedShort

unsigned short

minOccurs="1" maxOccurs="1"

short

unsigned_short_member;

 

 

};

type="xsd:unsignedShort"/>

 

 

</xsd:sequence>

 

 

 

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

 

<xsd:sequence>

long

xsd:int

struct PrimitiveStruct {

<xsd:element name="long_member"

long long_member;

minOccurs="1" maxOccurs="1"

 

 

};

type="xsd:int"/>

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

struct PrimitiveStruct {

<xsd:sequence>

unsigned

 

<xsd:element name= "unsigned_long_member"

 

unsigned long

xsd:unsignedInt

minOccurs="1" maxOccurs="1"

long

unsigned_long_member;

 

type="xsd:unsignedInt"/>

 

 

};

 

 

</xsd:sequence>

 

 

 

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

struct PrimitiveStruct {

<xsd:sequence>

 

 

<xsd:elementname= "long_long_member"

long long

xsd:long

long long

minOccurs="1" maxOccurs="1"

long_long_member;

 

 

type="xsd:long"/>

 

 

};

 

 

</xsd:sequence>

 

 

 

 

 

 

</xsd:complexType>

 

 

 

 

3-67

Table 3.10 Mapping Type System Constructs to XSD

Type/Construct

 

Example

 

 

 

 

IDL

XSD

IDL

XSD

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

 

<xsd:sequence>

unsigned

 

struct PrimitiveStruct {

<xsd:element name=

xsd:unsignedLong

unsigned long long

"unsigned_long_long_member"

long long

unsigned_long_long_member;

minOccurs="1" maxOccurs="1"

 

 

 

};

type="xsd:unsignedLong"/>

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

 

<xsd:sequence>

 

 

struct PrimitiveStruct {

<xsd:element name="float_member"

float

xsd:float

float float_member;

minOccurs="1" maxOccurs="1"

 

 

};

type="xsd:float"/>

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

 

<xsd:sequence>

double

xsd:double

struct PrimitiveStruct {

<xsd:element name="double_member"

double double_member;

minOccurs="1" maxOccurs="1"

 

 

};

type="xsd:double"/>

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

struct PrimitiveStruct {

<xsd:sequence>

long

 

<xsd:element name="long_double_member"

dds:longDoublea

long double

minOccurs="1" maxOccurs="1"

double

long_double_member;

 

type="dds:longDouble"/>

 

 

};

 

 

</xsd:sequence>

 

 

 

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

struct PrimitiveStruct {

<xsd:sequence>

 

 

<xsd:element name="boolean_member"

boolean

xsd:boolean

boolean

minOccurs="1" maxOccurs="1"

boolean_member;

 

 

type="xsd:boolean"/>

 

 

};

 

 

</xsd:sequence>

 

 

 

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

 

<xsd:sequence>

unbounded

xsd:string

struct PrimitiveStruct {

<xsd:element name="string_member"

string string_member;

minOccurs="1" maxOccurs="1"

string

 

};

type="xsd:string"/>

 

 

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

 

<xsd:sequence>

 

 

 

<xsd:element name="string_member"

 

 

 

minOccurs="1" maxOccurs="1">

 

xsd:string with

 

<xsd:simpleType>

 

struct PrimitiveStruct {

<xsd:restriction base="xsd:string">

bounded

restriction to

string<20> string_member;

<xsd:maxLength value="20"

string

specify the

};

fixed="true"/>

 

maximum length

 

 

</xsd:restriction>

 

 

 

 

 

 

</xsd:simpleType>

 

 

 

</xsd:element>

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

3-68

Table 3.10 Mapping Type System Constructs to XSD

Type/Construct

 

Example

 

 

 

 

IDL

XSD

IDL

XSD

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

 

<xsd:sequence>

unbounded

dds:wstringa

struct PrimitiveStruct {

<xsd:element name="wstring_member"

wstring wstring_member;

minOccurs="1" maxOccurs="1"

wstring

 

};

type="dds:wstring"/>

 

 

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

 

<xsd:sequence>

 

 

 

<xsd:element name="wstring_member"

 

 

 

minOccurs="1" maxOccurs="1">

 

xsd:wstring with

 

<xsd:simpleType>

 

struct PrimitiveStruct {

<xsd:restriction base=

bounded

restriction to

wstring<20>

"dds:wstring">

wstring

specify the

wstring_member;

<xsd:maxLength value="20"

 

maximum length

};

fixed="true"/>

 

 

 

</xsd:restriction>

 

 

 

</xsd:simpleType>

 

 

 

</xsd:element>

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

 

<!-- @pointer

 

<xsd:complexType name="PrimitiveStruct">

 

 

<xsd:sequence>

 

<true|false|1|0>

 

 

struct PrimitiveStruct {

<xsd:element name="long_member"

 

-->

 

minOccurs="1" maxOccurs="1"

pointer

long * long_member;

 

type="xsd:int"/>

 

 

};

 

Default (if not

<!-- @pointer true -->

 

 

 

 

</xsd:sequence>

 

specified): false

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

 

 

 

<xsd:complexType name="BitfieldStruct">

 

 

 

<xsd:sequence>

 

 

 

<xsd:element name="short_member"

 

 

 

minOccurs="1" maxOccurs="1"

 

 

 

type="xsd:short"/>

 

 

 

<!-- @bitField 1 -->

 

 

struct BitfieldStruct {

<xsd:element name=‘unsignedShort_member"

 

 

short short_member: 1;

minOccurs="1" maxOccurs="1"

 

<!-- @bitField

unsigned short

type="xsd:unsignedShort"/>

bitfieldb

unsignedShort_member: 1;

<!-- @bitField 1 -->

<bitfield length>

short: 0;

<xsd:element name="_ANONYMOUS_3"

 

-->

 

long long_member: 5;

minOccurs="1" maxOccurs="1"

 

 

 

 

};

type="xsd:short"/>

 

 

 

<!-- @bitField 0 -->

 

 

 

<xsd:element name="long_member"

 

 

 

minOccurs="1" maxOccurs="1"

 

 

 

type="xsd:int"/>

 

 

 

<!-- @bitField 5 -->

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

 

<!-- @key

 

<xsd:complexType name="KeyedPrimitiveStruct">

 

 

<xsd:sequence>

 

<true|false|1|0>

 

 

struct

<xsd:element name="long_member"

key

-->

KeyedPrimitiveStruct {

minOccurs="1" maxOccurs="1"

directivec

 

long long_member; //@key

type="xsd:int"/>

 

Default (if not

};

<!-- @key true -->

 

 

</xsd:sequence>

 

specified): false

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

3-69

Table 3.10 Mapping Type System Constructs to XSD

Type/Construct

 

Example

 

 

 

 

 

IDL

 

XSD

IDL

XSD

 

 

 

 

 

 

 

<!-- @resolveName

 

<xsd:complexType name=

 

 

struct

"UnresolvedPrimitiveStruct">

 

 

<true|false|1|0>

UnresolvedPrimitiveStruct

<xsd:sequence>

resolvenam

-->

{

<xsd:element name="primitive_member"

PrimitiveStruct

minOccurs="1" maxOccurs="1"

e directivec

 

 

primitive_member;

type="PrimitiveStruct"/>

 

 

 

 

 

Default (if not

//@resolve-name false

<!-- @resolveName false -->

 

 

specified): true

};

</xsd:sequence>

 

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

 

 

<xsd:complexType

 

 

<!-- @topLevel

 

name="TopLevelPrimitiveStruct">

 

 

<true|false|1|0> -

struct

<xsd:sequence>

 

 

<xsd:element name="short_member"

top-level

 

->

TopLevelPrimitiveStruct {

 

minOccurs="1" maxOccurs="1"

directivec

 

 

short short_member;

 

 

type="xsd:short"/>

 

 

Default (if not

}; //@top-level false

 

 

</xsd:sequence>

 

 

 

 

 

specified): true

 

</xsd:complexType>

 

 

 

 

<!-- @topLevel false -->

 

 

 

 

 

 

 

<!--

//@copy This text will be

 

other

c

@<directive kind>

<!--@copy This text will be copied in the

directives

<value>

copied in the generated

generated files -->

 

files

 

 

 

 

 

 

-->

 

 

 

 

 

 

 

 

 

 

 

<xsd:simpleType name="PrimitiveEnum">

 

 

 

 

<xsd:restriction base="xsd:string">

 

 

 

 

<xsd:enumeration value="ENUM1"/>

 

 

 

 

<xsd:enumeration value="ENUM2"/>

 

 

 

 

<xsd:enumeration value="ENUM3"/>

 

 

 

 

</xsd:restriction>

 

 

 

 

</xsd:simpleType>

 

 

 

 

<xsd:simpleType name="PrimitiveEnum">

 

 

 

 

<xsd:restriction base="xsd:string">

 

 

 

 

<xsd:enumeration value="ENUM1">

 

 

 

 

<xsd:annotation>

 

 

 

enum PrimitiveEnum {

<xsd:appinfo>

 

 

 

ENUM1,

<ordinal>10</ordinal>

 

 

 

ENUM2,

</xsd:appinfo>

 

 

 

ENUM3

</xsd:annotation>

enum

 

xsd:simpleType

};

</xsd:enumeration>

 

 

<xsd:enumeration value="ENUM2">

 

with enumeration

 

 

 

enum PrimitiveEnum {

<xsd:annotation>

 

 

 

 

 

 

ENUM1 = 10,

<xsd:appinfo>

 

 

 

ENUM2 = 20,

<ordinal>20</ordinal>

 

 

 

ENUM3 = 30

</xsd:appinfo>

 

 

 

};

</xsd:annotation>

 

 

 

 

</xsd:enumeration>

 

 

 

 

<xsd:enumeration value="ENUM3">

 

 

 

 

<xsd:annotation>

 

 

 

 

<xsd:appinfo>

 

 

 

 

<ordinal>30</ordinal>

 

 

 

 

</xsd:appinfo>

 

 

 

 

</xsd:annotation>

 

 

 

 

</xsd:enumeration>

 

 

 

 

</xsd:restriction>

 

 

 

 

</xsd:simpleType>

 

 

 

 

 

3-70

Table 3.10 Mapping Type System Constructs to XSD

Type/Construct

 

Example

 

 

 

 

IDL

XSD

IDL

XSD

 

 

constant

IDL constants are mapped by substituting their value directly in the generated file

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

 

<xsd:sequence>

 

xsd:complexType

struct PrimitiveStruct {

<xsd:element name="short_member"

struct

short short_member;

minOccurs="1" maxOccurs="1"

with xsd:sequence

 

};

type="xsd:short"/>

 

 

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

<xsd:complexType name="PrimitiveUnion">

 

 

 

<xsd:sequence>

 

 

 

<xsd:element name="discriminator"

 

 

 

type="xsd:int"/>

 

 

 

<xsd:choice>

 

 

 

<!-- case 1 -->d

 

 

 

<xsd:element name="short_member"

 

 

 

minOccurs="0" maxOccurs="1"

 

 

 

type="xsd:short">

 

 

 

<xsd:annotation>

 

 

union PrimitiveUnion

<xsd:appinfo>

 

 

<case>1</case>

 

 

switch (long) {

 

 

</xsd:appinfo>

 

xsd:complexType

case 1:

union

</xsd:annotation>

short short_member;

with xsd:choice

</xsd:element>

 

default:

 

 

<!-- case default -->

 

 

long long_member;

 

 

<xsd:element name="long_member"

 

 

};

 

 

minOccurs="0" maxOccurs="1"

 

 

 

 

 

 

type="xsd:int">

 

 

 

<xsd:annotation>

 

 

 

<xsd:appinfo>

 

 

 

<case>default</case>

 

 

 

</xsd:appinfo>

 

 

 

</xsd:annotation>

 

 

 

</xsd:element>

 

 

 

</xsd:choice>

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

3-71

Table 3.10 Mapping Type System Constructs to XSD

Type/Construct

 

Example

 

 

 

 

IDL

XSD

IDL

XSD

 

 

 

 

 

 

 

<xsd:complexType name="BaseValueType">

 

 

 

<xsd:sequence>

 

 

 

<xsd:element name=”long_member"

 

 

 

maxOccurs="1" minOccurs="1"

 

 

 

type="xs:int"/>

 

 

 

<!-- @visibility public -->

 

 

 

</xsd:sequence>

 

 

valuetype BaseValueType {

</xs:complexType>

 

 

public long

<!-- @valuetype true -->

 

 

long_member;

 

 

 

};

<xs:complexType name="DerivedValueType">

 

xsd:complexType

 

<xs:complexContent>

 

valuetype

<xs:extension base="BaseValueType">

valuetype

with @valuetype

DerivedValueType:

<xs:sequence>

 

directive

BaseValueType {

<xs:element name= "long_member2"

 

 

public long

maxOccurs="1" minOccurs="1"

 

 

long_member2;

type="xs:int"/>

 

 

public long

<!-- @visibility public -->

 

 

long_member3;

<xs:element name= "long_member3"

 

 

};

maxOccurs="1" minOccurs="1"

 

 

 

type="xs:int"/>

 

 

 

<!-- @visibility public -->

 

 

 

</xs:sequence>

 

 

 

</xs:extension>

 

 

 

</xs:complexContent>

 

 

 

</xs:complexType>

 

 

 

<!-- @valuetype true -->

 

 

 

 

 

 

 

<xsd:simpleType name="ShortType">

 

 

 

<xsd:restriction base="xsd:short"/>

 

 

 

</xsd:simpleType>

 

 

 

<!—- Struct definition -->

 

 

 

<xsd:complexType name="PrimitiveStruct">

 

 

 

<xsd:sequence>

 

 

typedef short ShortType;

<xsd:element name="short_member"

 

 

minOccurs="1" maxOccurs="1"

 

 

 

 

 

struct PrimitiveStruct {

type="xsd:short"/>

 

 

</xsd:sequence>

 

Type definitions

short short_member;

 

</xsd:complexType>

 

};

typedef

are mapped to

 

 

 

XML schema type

 

<!—- Typedef definition -->

 

typedef PrimitiveType

 

restrictions

<xsd:complexType

 

PrimitiveStructType;

 

 

name="PrimitiveTypeStructType">

 

 

 

 

 

 

<xsd:complexContent>

 

 

 

<xsd:restriction base=”PrimitiveStruct”>

 

 

 

<xsd:sequence>

 

 

 

<xsd:element name="short_member"

 

 

 

minOccurs="1" maxOccurs="1"

 

 

 

type="xsd:short"/>

 

 

 

</xsd:sequence>

 

 

 

</xsd:restriction>

 

 

 

</xsd:complexContent>

 

 

 

</xsd:complexType>

 

 

 

 

3-72

Table 3.10 Mapping Type System Constructs to XSD

 

Type/Construct

 

Example

 

 

 

 

 

IDL

 

XSD

IDL

XSD

 

 

 

 

 

 

 

 

 

<!-- Array type -->

 

 

 

 

<xsd:complexType name=

 

 

 

 

"OneArrayStruct_short_array_ArrayOfShort">

 

 

n xsd:complexType

 

<xsd:sequence>

 

 

 

<xsd:element name="item" minOccurs="2"

 

 

with sequence

 

 

 

 

maxOccurs="2" type="xsd:short">

 

 

containing one

 

 

 

 

</xsd:element>

 

 

element with min

 

 

 

struct OneArrayStruct {

</xsd:sequence>

 

 

& max occurs

 

 

</xsd:complexType>

arrays

 

short short_array[2];

 

 

<!-- Struct w unidimensional array member -->

 

 

 

};

 

 

There is one

<xsd:complexType name="OneArrayStruct">

 

 

 

 

 

 

<xsd:sequence>

 

 

xsd:complexType

 

 

 

 

<xsd:element name="short_array"

 

 

per array

 

 

 

 

minOccurs="1" maxOccurs="1"

 

 

dimension

 

 

 

 

type=

 

 

 

 

 

 

 

 

"OneArrayStruct_short_array_ArrayOfShort"/>

 

 

 

 

</xsd:sequence>

 

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

 

 

<!--Second dimension array type -->

 

 

 

 

<xsd:complexType name=

 

 

 

 

"TwoArrayStruct_short_array_ArrayOfShort">

 

 

 

 

<xsd:sequence>

 

 

 

 

<xsd:element name="item" minOccurs="2"

 

 

 

 

maxOccurs="2" type="xsd:short">

 

 

 

 

</xsd:element>

 

 

 

 

</xsd:sequence>

 

 

 

 

</xsd:complexType>

 

 

n xsd:complexType

 

<!-- First dimension array type -->

 

 

with sequence

 

<xsd:complexType name=

 

 

 

"TwoArrayStruct_short_array_ArrayOfArrayOfShort">

 

 

containing one

 

 

 

 

<xsd:sequence>

 

 

element with min

 

 

 

struct TwoArrayStruct {

<xsd:element name="item"

arrays

 

& max occurs

 

minOccurs="1" maxOccurs="1"

 

short short_array[2][1];

(cont’d)

 

 

type=

 

 

};

 

 

There is one

"TwoArrayStruct_short_array_ArrayOfShort">

 

 

 

 

 

 

</xsd:element>

 

 

xsd:complexType

 

 

 

 

</xsd:sequence>

 

 

per array

 

 

 

 

</xsd:complexType>

 

 

dimension

 

 

 

 

 

 

 

 

 

<!--Struct containing a bidimensional array

 

 

 

 

member -->

 

 

 

 

<xsd:complexType name="TwoArrayStruct">

 

 

 

 

<xsd:sequence>

 

 

 

 

<xsd:element name="short_array"

 

 

 

 

minOccurs="1" maxOccurs="1"

 

 

 

 

type=

 

 

 

 

"TwoArrayStruct_short_array_ArrayOfArrayOfShort"/>

 

 

 

 

</xsd:sequence>

 

 

 

 

</xsd:complexType>

 

 

 

 

 

3-73

Table 3.10 Mapping Type System Constructs to XSD

Type/Construct

 

Example

 

 

 

 

IDL

XSD

IDL

XSD

 

 

 

 

 

 

 

 

 

 

 

<!-- Sequence type -->

 

 

 

<xsd:complexType name=

 

 

 

"SequenceStruct_short_sequence_SequenceOfShort">

 

 

 

<xsd:sequence>

 

 

 

<xsd:element name="item" minOccurs="0"

 

 

 

maxOccurs="4" type="xsd:short">

 

 

 

</xsd:element>

 

xsd:complexType

 

</xsd:sequence>

bounded

with sequence

struct SequenceStruct {

</xsd:complexType>

sequence<short,4>

 

containing one

 

sequence

short_sequence;

<!-- Struct containing a bounded sequence

element with min

 

};

member -->

 

& max occurs

 

 

<xsd:complexType name="SequenceStruct">

 

 

 

 

 

 

<xsd:sequence>

 

 

 

<xsd:element name="short_sequence"

 

 

 

minOccurs="1" maxOccurs="1"

 

 

 

type=

 

 

 

"SequenceStruct_short_sequence_SequenceOfShort"/>

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

 

 

 

<!-- Sequence type -->

 

 

 

<xsd:complexType name=

 

 

 

"SequenceStruct_short_sequence_SequenceOfShort">

 

 

 

<xsd:sequence>

 

 

 

<xsd:element name="item"

 

 

 

minOccurs="0" maxOccurs="unbounded"

 

 

 

type="xsd:short"/>

 

xsd:complexType

 

</xsd:sequence>

unbound-

with sequence

struct SequenceStruct {

</xsd:complexType>

sequence<short>

 

ed

containing one

 

short_sequence;

<!-- Struct containing an unbounded sequence

sequence

element with min

};

member -->

 

& max occurs

 

 

<xsd:complexType name="SequenceStruct">

 

 

 

 

 

 

<xsd:sequence>

 

 

 

<xsd:element name="short_sequence"

 

 

 

minOccurs="1" maxOccurs="1"

 

 

 

type=

 

 

 

"SequenceStruct_short_sequence_SequenceOfShort"/>

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

3-74

Table 3.10 Mapping Type System Constructs to XSD

 

Type/Construct

 

Example

 

 

 

 

 

IDL

 

XSD

IDL

XSD

 

 

 

 

 

 

 

 

 

<!-- Sequence declaration -->

 

 

 

 

<xsd:complexType

 

 

 

 

name=

 

 

 

 

"ArrayOfSequencesStruct_sequence_array_SequenceOf

 

 

 

 

Short">

 

 

 

 

<xsd:sequence>

 

 

 

 

<xsd:element name="item"

 

 

 

 

minOccurs="0" maxOccurs="4"

 

 

 

 

type="xsd:short">

 

 

 

 

</xsd:element>

 

 

 

 

</xsd:sequence>

 

 

 

 

</xsd:complexType>

 

 

n + 1

 

 

 

 

xsd:complexType

 

<!-- Array declaration -->

 

 

with sequence

 

<xsd:complexType

 

 

containing one

 

name=

 

 

element with min

 

"ArrayOfSequencesStruct_sequence_array_ArrayOf

 

 

struct

SequenceOfShort">

 

 

& max occurs

array of

 

ArrayOfSequencesStruct {

<xsd:sequence>

 

 

 

 

sequence<short,4>

<xsd:element name="item"

sequences

 

There is one

sequence_sequence[2];

minOccurs="2" maxOccurs="2"

 

 

 

 

xsd:complexType

};

type=

 

 

 

"ArrayOfSequencesStruct_sequence_array_SequenceOf

 

 

per array

 

 

 

 

Short">

 

 

dimension and one

 

 

 

 

</xsd:element>

 

 

xsd:complexType

 

 

 

 

</xsd:sequence>

 

 

for the sequence

 

</xsd:complexType>

 

 

 

 

<!-- Structure containing a member that is an

 

 

 

 

array of sequences -->

 

 

 

 

<xsd:complexType name="ArrayOfSequencesStruct">

 

 

 

 

<xsd:sequence>

 

 

 

 

<xsd:element name="sequence_array"

 

 

 

 

minOccurs="1" maxOccurs="1"

 

 

 

 

type=

 

 

 

 

"ArrayOfSequencesStruct_sequence_array_ArrayOf

 

 

 

 

SequenceOfShort"/>

 

 

 

 

</xsd:sequence>

 

 

 

 

</xsd:complexType>

 

 

 

 

 

3-75

Table 3.10 Mapping Type System Constructs to XSD

Type/Construct

 

Example

 

 

 

 

IDL

XSD

IDL

XSD

 

 

 

 

 

 

 

<!-- Array declaration -->

 

 

 

<xsd:complexType name="ShortArray">

 

 

 

<xsd:sequence>

 

 

 

<xsd:element name="item"

 

 

 

minOccurs="2" maxOccurs="2"

 

 

 

type="xsd:short">

 

 

 

</xsd:element>

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

<!-- Sequence declaration -->

 

 

 

<xsd:complexType name=

 

Sequences of arrays

typedef short

"SequencesOfArraysStruct_array_sequence_SequenceO

 

ShortArray[2];

fShortArray">

 

must be

 

<xsd:sequence>

sequence of

implemented using

struct

<xsd:element name="item"

arrays

an explicit type

SequenceOfArraysStruct {

minOccurs="0" maxOccurs="2"

 

definition (typedef)

sequence<ShortArray,2>

type="ShortArray">

 

for the array

arrays_sequence;

</xsd:element>

 

 

};

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

<!-- Struct containing a sequence of arrays -->

 

 

 

<xsd:complexType name="SequenceOfArraysStruct">

 

 

 

<xsd:sequence>

 

 

 

<xsd:element name="arrays_sequence"

 

 

 

minOccurs="1" maxOccurs="1"

 

 

 

type=

 

 

 

"SequencesOfArraysStruct_arrays_sequence_Sequence

 

 

 

OfShortArray"/>

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

3-76

Table 3.10 Mapping Type System Constructs to XSD

Type/Construct

 

Example

 

 

 

 

IDL

XSD

IDL

XSD

 

 

 

 

 

 

 

<!-- Internal sequence declaration -->

 

 

 

<xsd:complexType name="ShortSequence">

 

 

 

<xsd:sequence>

 

 

 

<xsd:element name="item"

 

 

 

minOccurs="0" maxOccurs="4"

 

 

 

type="xsd:short">

 

 

 

</xsd:element>

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

<!-- External sequence declaration -->

 

 

 

<xsd:complexType name=

 

Sequences of

typedef sequence<short,4>

"SequencesOfSequences_sequences_sequence_Sequence

 

sequences must be

ShortSequence;

OfShortSequence">

sequence of

implemented using

 

<xsd:sequence>

struct

<xsd:element name="item"

an explicit type

sequences

definition (typedef)

SequenceOfSequences {

minOccurs="0" maxOccurs="2"

 

sequence<ShortSequence, 2>

type="ShortSequence">

 

for the second

sequences_sequence;

</xsd:element>

 

sequence

 

};

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

<!--Struct containing a sequence of sequences -->

 

 

 

<xsd:complexType name="SequenceOfSequences">

 

 

 

<xsd:sequence>

 

 

 

<xsd:element name="sequences_sequence"

 

 

 

minOccurs="1" maxOccurs="1"

 

 

 

type="SequencesOfSequences_

 

 

 

sequences_sequence_SequenceOfShortSequence"/>

 

 

 

</xsd:sequence>

 

 

 

</xsd:complexType>

 

 

 

 

 

Modules are

 

<xsd:complexType name=

 

module PackageName {

"PackageName.PrimitiveStruct">

 

mapped adding the

<xsd:sequence>

module

name of the

struct PrimitiveStruct {

<xsd:element name="long_member"

long long_member;

module before the

minOccurs="1" maxOccurs="1"

 

};

 

name of each type

type="xsd:int"/>

 

};

 

inside the module

</xsd:sequence>

 

 

 

 

 

</xsd:complexType>

 

 

 

 

include

xsd:include

#include

<xsd:include schemaLocation=

"PrimitiveType.idl"

"PrimitiveType.xsd"/>

 

 

 

 

 

 

a.All files that use the primitive types char, wchar, long double and wstring must reference rti_dds_topic_types_common.xsd. See Primitive Types (Section 3.5.1).

b.Data types containing bitfield members are not supported by DynamicData (Section 3.8).

c.Directives are RTI extensions to the standard IDL grammar. For additional information about directives see Using Custom Directives (Sec- tion 3.3.8).

d.The discriminant values can be described using comments (as specified by the standard) or xsd:annotation tags. We recommend using annotations because comments may be removed by XSD/XML parsers.

3-77

3.5.1Primitive Types

The primitive types char, wchar, long double, and wstring are not supported natively in XSD. Connext provides definitions for these types in the file <NDDSHOME>/resource/rtiddsgen/ schema/rti_dds_topic_types_common.xsd. All files that use the primitive types char, wchar, long double and wstring must reference rti_dds_topic_types_common.xsd. For example:

<?xml version="1.0" encoding="UTF-8"?>

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:dds="http://www.omg.org/dds">

<xsd:import namespace="http://www.omg.org/dds" schemaLocation="rti_dds_topic_types_common.xsd"/>

<xsd:complexType name="Foo"> <xsd:sequence>

<xsd:element name="myChar" minOccurs="1" maxOccurs="1" type="dds:char"/>

</xsd:sequence>

</xsd:complexType>

</xsd:schema>

3.6Using rtiddsgen

The rtiddsgen utility provided by Connext creates the code needed to define and register a user data type with Connext. Using this tool is optional if:

You are using dynamic types (see Managing Memory for Built-in Types (Section 3.2.8))

You are using one of the built-in types (see Built-in Data Types (Section 3.2))

To use rtiddsgen, you must supply a description of the type in an IDL, XML, XSD, or WSDL file. The supported syntax for each one of the notations is described in Section 3.8.5.1 (IDL), Section 3.4 (XML) and Section 3.5 (XSD and WSDL). You can define multiple data types in the same type-definition file.

Table 3.11 on page 3-78 (for C, C++, and C++/CLI and C#) and Table 3.12 on page 3-79 (for Java) show the files that rtiddsgen creates for an example IDL file called Hello.idl. (The file extension will depend on the chosen language: .c for C, .cxx for C++, .cpp for C++/CLI, .cs for C#.)

On Windows systems: Before running rtiddsgen, run VCVARS32.BAT in the same command prompt that you will use to run rtiddsgen.

Table 3.11 Files Created by rtiddsgen for C, C++, C++/CLI, C# for Example “Hello.idl”

Generated Files

Description

 

 

Required files for the user data type. The source files should be compiled and linked with the user application. The header files are required to use the data type in source.

You should not modify these files unless you intend to customize the generated code supporting your type.

Hello.[c,cxx, cpp]

Generated code for the data types. These files contain the

HelloSupport.[c, cxx, cpp]

implementation for your data types.

HelloPlugin.[c,cxx, cpp]

 

 

 

Hello.h

Header files that contain declarations used in the implementation of

HelloSupport.h

your data types.

HelloPlugin.h

 

 

 

3-78

Table 3.11 Files Created by rtiddsgen for C, C++, C++/CLI, C# for Example “Hello.idl”

 

Generated Files

 

 

Description

 

 

 

 

 

 

 

 

 

 

Optional files generated when you use the “-example <arch>” command-line option.

 

You may modify and use these files as a way to create simple applications that publish or subscribe to the

 

user data type.

 

 

 

 

 

 

 

 

 

 

 

 

 

Example code for an application that publishes the user data type. This

 

 

 

 

example shows the basic steps to create all of the Connext objects needed

 

Hello_publisher.[c, cxx, cpp, cs]

to send data.

 

 

 

 

You will need to modify the code to set and change the values being

 

 

 

 

sent in the data structure. Otherwise, just compile and run.

 

 

 

 

 

 

 

 

 

 

Example code for an application that subscribes to the user data type.

 

 

 

 

This example shows the basic steps to create all of the Connext objects

 

Hello_subscriber.[c, cxx, cpp,cs]

needed to receive data using a “listener” function.

 

 

 

 

No modification of this file is required. It is ready for you to compile

 

 

 

 

and run.

 

 

 

 

 

 

 

 

Hello.dsw or Hello.sln,

 

Microsoft Visual C++ or Visual Studio .NET Project workspace and

 

Hello_publisher.dsp

or

 

Hello_publisher.vcproj,

 

project files, generated only for “i86Win32” architectures. To compile

 

 

the generated source code, open the workspace file and build the two

 

Hello_subscriber.dsp

or

 

projects.

 

 

Hello_subscriber.vcproj

 

 

 

 

 

 

 

 

 

 

makefile_Hello_<architecture>

 

Makefile

for non-Windows-based architectures. An example

 

 

<architecture> would be linux2.4gcc3.2.2.

 

 

 

 

 

 

 

 

 

Table 3.12 Files Created by rtiddsgen for Java for Example “Hello.idl”

 

 

 

 

 

Data Type

Generated Files

Description

 

 

 

 

 

 

 

Since the Java language requires individual files to be created for each class, rtiddsgen will generate a

 

source file for every IDL construct that translates into a class in Java.

 

 

 

 

 

 

 

Constants

<Name>.java

 

 

Class associated with the constant

 

 

 

 

 

 

 

Enums

<Name>.java

 

 

Class associated with enum type

 

 

 

 

 

 

 

 

<Name>.java

 

 

Structure/Union class

 

 

<Name>Seq.java

 

 

Structures/

 

Sequence class

 

<Name>DataReader.java

 

Unions

Connext DataReader and DataWriter classes

 

<Name>DataWriter.java

 

 

Support (serialize, deserialize, etc.) class

 

 

<Name>TypeSupport.java

 

 

 

 

 

 

 

 

 

 

Typedef of

<Name>.java

 

 

Wrapper class

 

sequences or

<Name>Seq.java

 

Sequence class

 

arrays

<Name>TypeSupport.java

Support (serialize, deserialize, etc.) class

 

 

 

 

 

 

3-79

Table 3.12 Files Created by rtiddsgen for Java for Example “Hello.idl”

Data Type

Generated Files

Description

 

 

 

Optional files generated when you use the “-example <arch>” command-line option. You may modify and use these files as a way to create simple applications that publish or subscribe to the user data type.

 

 

Example code for applications that publish or subscribe to

 

<Name>Publisher.java

the user data type. You should modify the code in the

 

publisher application to set and change the value of the

Structures/

<Name>Subscriber.java

published data. Otherwise, both files should be ready to

Unions

 

 

compile and run.

 

 

 

 

 

 

makefile_Hello_<architecture>

Makefile for non-Windows-based architectures. An

 

 

example <architecture> is linux2.4gcc3.2.2.

Structures/

<Name>TypeCode.java

 

Unions/

Type code class associated with the IDL type given by

(Note: this is not generated if

Typedefs/

<Name>.

Enums

you use -notypecode)

 

 

 

 

 

 

NOTE: Before using an rtiddsgen-generated makefile to compile an application, make sure the ${NDDSHOME} environment variable is set as described in the Getting Started Guide. For INTEGRITY architectures, ${NDDSHOME} must be set when generating the project files.

3.6.1rtiddsgen Command-Line Arguments

There are several command-line options you can pass to rtiddsgen:

Note: CORBA support requires the RTI CORBA Compatibility Kit

rtiddsgen [-d <outdir>]

[-language <C|C++|Java|C++/CLI|C#|Ada>] [-namespace] (C++ only)

[-package <packagePrefix>] (Java only) [-example <arch>]

[-replace] [-debug]

[-corba [client header file]] [-orb \<CORBA ORB\>]] [-optimization <level of optimization>] [-stringSize <Unbounded strings size>] [-sequenceSize <Unbounded sequences size>] [-notypecode]

[-ppDisable]

[-ppPath <preprocessor executable>] [-ppOption <option>]

[-D <name>[=<value>]] [-U <name>]

[-I <directory>] [-noCopyable] [-use42eAlignment] [-enableEscapeChar] [-typeSequenceSuffix <Suffix>] [-dataReaderSuffix <Suffix>] [-dataWriterSuffix <Suffix>] [-convertToXml |

-convertToXsd | -convertToWsdl | -convertToIdl] [-convertToCcl] [-convertToCcs] [-expandOctetSeq] [-expandCharSeq]

3-80

[-version] [-help] [-verbosity [1-3]]

[[-inputIdl] <IDLInputFile.idl> | [-inputXml] <XMLInputFile.xml> | [-inputXsd] <XSDInputFile.xsd> | [-inputWsdl] <WSDLInputFile.wsdl>]

Table 3.13 describes the options (in alphabetical order).

Table 3.13 Options for rtiddsgen

Option

Description

 

 

 

 

-convertToCcl

Converts the input type description file into CCL format. This option creates

a new file with the same name as the input file and a .ccl extension.

 

 

 

-convertToCcs

Converts the input type description file into CCs format. This option creates

a new file with the same name as the input file and a .ccs extension.

 

 

 

-convertToIdl

Converts the input type description file into IDL format. This option creates

a new file with the same name as the input file and a .idl extension.

 

 

 

-convertToWsdl

Converts the input type description file into WSDL format. This option

creates a new file with the same name as the input file and a .wsdl extension.

 

 

 

-convertToXml

Converts the input type description file into XML format. This option creates

a new file with the same name as the input file and a .xml extension.

 

 

 

-convertToXsd

Converts the input type description file into XSD format. This option creates

a new file with the same name as the input file and a .xsd extension.

 

 

 

 

This option is only available when using the RTI CORBA Compatibility Kit for

-corba

Connext (available for purchase as a separate product). Please see Part 7: RTI

 

CORBA Compatibility Kit.

 

 

 

Defines preprocessor macros.

-D <name>[=<value>]

Note: On Windows systems, enclose the argument in quotation marks:

 

-D "<name>[=<value>]"

 

 

-d

Generates the output in the specified directory. By default, rtiddsgen will

generate files in the directory where the input type-definition file is found.

 

 

 

 

Assigns a suffix to the name of a DataReader interface. Only applies if -corba

-dataReaderSuffix <suffix>

is also specified. By default, the suffix is 'DataReader'. Therefore, given the

 

type 'Foo' the name of the DataReader interface will be 'FooDataReader'.

 

 

 

Assigns a suffix to the name of a DataWriter interface. Only applies if -corba

-dataWriterSuffix <suffix>

is also specified. By default, the suffix is 'DataWriter'. Therefore, given the

 

type 'Foo' the name of the DataWriter interface will be 'FooDataWriter'.

 

 

-debug

Creates XML files for debugging rtiddsgen only. Use this option only at the

direction of RTI support; it is unlikely to be useful to you otherwise.

 

 

 

-enableEscapeChar

Enables use of the escape character '_' in IDL identifiers. When -corba is

used, this option is always enabled.

 

 

 

 

Generates example application code and makefiles (for UNIX-based

-example <arch>

systems) or workspace and project files (for Windows systems) based on the

type-definition file. The parameter specifies the architecture for the example

 

 

makefiles. Valid options for <arch> are listed in the Platform Notes.

 

 

-expandOctetSeq

When converting to CCS or CCL files, expand octet sequences. The default

is to use a blob type.

 

 

 

3-81

Table 3.13 Options for rtiddsgen

Option

Description

 

 

 

 

-expandCharSeq

When converting to CCS or CCL files, expand char sequences. The default is

to use a string type.

 

 

 

 

Adds to the list of directories to be searched for type-definition files (IDL,

-I <directory>

XML, XSD or WSDL files). Note: A type-definition file in one format cannot

 

include a file in another format.

 

 

-inputIdl

Indicates that the input file is an IDL file, regardless of the file extension.

 

 

-inputWsdl

Indicates that the input file is a WSDL file, regardless of the file extension.

 

 

-inputXml

Indicates that the input file is a XML file, regardless of the file extension.

 

 

-inputXsd

Indicates that the input file is a XSD file, regardless of the file extension.

 

 

IDLInputFile.idl

File containing IDL descriptions of your data types. If -inputIdl is not used,

the file must have a ‘.idl’ extension.

 

 

 

-help

Prints out the command line options for rtiddsgen.

 

 

-language

Specifies the language to use for the generated files. The default language is

C++; you can also choose C, C++/CLI, C#, Java, or Ada.

 

 

 

 

Generates code for the Multi-Encapsulation Type Support (METP) library.

-metp

The METP library requires a special version of Connext; please contact

 

support@rti.com for more information.

 

 

-namespace

Specifies the use of C++ namespace. (For C++ only. For C++/CLI and C#, it

is implied-namespaces are always used.)

 

 

 

 

Forces rtiddsgen to put ‘copy’ logic into the corresponding TypeSupport class

 

rather than the type itself. This option is only used for Java code generation.

-noCopyable

This option is not compatible with the use of ndds_standalone_type.jar (see

 

Section 3.7). Note that when generating code for Java, the -corba option

 

implies the -noCopyable option (whether or not you specify -noCopyable).a

 

Disables type-code support. By using this option, you can generate code that

 

can be used in a standalone manner—see Using Generated Types without

 

Connext (Standalone) (Section 3.7).

-notypecode

Note: If you are using a large data type (more than 64 K) and type code

support, you will see a warning when type code information is sent. Connext

 

 

has a type code size limit of 64K. To avoid the warning when working with

 

data types with type codes larger than 64K, turn off type code support by

 

using -notypecode.

 

 

 

Allows rtiddsgen to overwrite any existing generated files. If it is not present

-replace

and existing files are found, rtiddsgen will print a warning but will not

 

overwrite them.

 

 

-optimization

See Optimizing Typedefs (-optimization) (Section 3.6.1.1 on Page 3-83)

 

 

 

Specifies the CORBA ORB. The majority of code generated is independent of

 

the ORB. However, for some IDL features the code generated depends on the

-orb

ORB. rtiddsgen generates code compatible with ACE-TAO or JacORB. To

select an ACE_TAO version use the -orb parameter. The default is

 

 

ACE_TAO1.6.

 

This option can only be used with the -corba option.

 

 

 

Specifies the root package into which generated classes will be placed. It

-package

applies to Java only. If the type-definition file contains module declarations,

 

those modules will be considered subpackages of the package specified here.

 

 

3-82

Table 3.13 Options for rtiddsgen

Option

Description

 

 

 

 

-ppDisable

Disables the preprocessor.

 

 

 

Specifies a preprocessor option. This parameter can be used multiple times

-ppOption <option>

to provide the command-line options for the specified preprocessor. See -

 

ppPath.

 

 

 

Specifies the preprocessor. If you only specify the name of an executable

 

(not a complete path to that executable), the executable must be found in

 

your Path. The default value is "cpp" for non-Windows architectures and

-ppPath

"cl.exe" for Windows architectures.If you use -ppPath to provide the full

path and filename for cl.exe or the cpp preprocessor, you must also use -

<preprocessor

ppOption (described below) to set the following preprocessor options:

executable>

If you use a non-default path for cl.exe, you also need to set:

 

 

-ppOption /nologo -ppOption /C -ppOption /E -ppOption /X

 

If you use a non-default path for cpp, you also need to set:

 

-ppOption -C

 

 

-sequenceSize

Sets the size assigned to unbounded sequences. The default value is 100

elements.

 

 

 

-stringSize

Sets the size assigned to unbounded strings, not counting a terminating

NULL character. The default value is 255 bytes.

 

 

 

 

Assigns a suffix to the names of the implicit sequences defined for IDL types.

-typeSequenceSuffix

Only applies if -corba is also specified. By default, the suffix is 'Seq'.

<suffix>

Therefore, given the type 'Foo' the name of the implicit sequence will be

 

'FooSeq'.

 

 

-U <name>

Cancels any previous definition of <name>.

 

 

 

Makes the generated code compatible with RTI Data Distribution Service 4.2e.

-use42eAlignment

This option should be used when compatibility with 4.2e is required and the

topic data types contain double, long long, unsigned long long, or long

 

 

double members.

 

 

 

rtiddsgen verbosity:

-verbosity [1-3]

1: exceptions

2: exceptions and warnings

 

 

3: exceptions, warnings and information (Default)

 

 

 

Displays the version of rtiddsgen being used, such as 5.0.x. (Note: To see

-version

‘patch’ revision information (such as 5.0.x rev. n), see What Version am I

 

Running? (Section 21.1).

 

 

WSDLInputFile.wsdl

WSDL file containing XSD descriptions of your data types. If -inputWsdl is

not used, the file must have an .wsdl extension.

 

 

 

XMLInputFile.idl

File containing XML descriptions of your data types. If -inputXml is not

used, the file must have an .xml extension.

 

 

 

XSDInputFile.xsd

File containing XSD descriptions of your data types. If -inputXsd is not used,

the file must have an .xsd extension.

 

 

 

a. CORBA support is only available when using the RTI CORBA Compatibility Kit (available for purchase as a separate product). See Part 7: RTI CORBA Compatibility Kit.

3.6.1.1Optimizing Typedefs (-optimization)

The -optimization option specifies how support for typedefs is generated in C and C++ code. This option is only useful when there are typedefs defined in the IDL file. This option only

3-83

applies to C and C++ because the Java language does not contain the typedef construct. In other words, rtiddsgen always resolves typedef’ed names to their most basic types when generating Java code (except for typedefs of arrays and sequences which are converted to wrapper classes—see Note 8 on Page 3-54). Effectively, Java code is always generated with an equivalent optimization level of 2. Choices are:

0 (default): No optimization. Typedef’ed types are treated as full types and type-plugin and support code is generated and invoked when the typedefs are used in other structures.

1: The compiler generates type-plugin and support code for typedefs but optimizes its use. If a type is a typedef that can be resolved either to a primitive type (char, short, long, etc.) or to another type that is defined in the same IDL file, then when the typedef is used in the definition of another structure, rtiddsgen will generate code that invokes the plugin and support code of the most basic type to which the typedef can be resolved.

This will save at least one function call for serialization, deserialization, and other manipulation of the parent structure. This optimization level is always safe to use unless the user intends to modify the generated type-plugin and support code. In that case, we recommend using the default of no optimization of typedefs.

2: Same as level 1 with the addition that the type-plugin and support code for typedefs are not generated (since they would not be used by the code for data types defined in the same IDL file that uses the typedefs).

This typedef optimization level is only recommend if you only have a single IDL file that contains the definitions of all of the user data types passed by Connext on the network. If you have multiple IDL files, and types defined in one file use typedefs that are defined in another, then rtiddsgen will generate code assuming that the type-plugin and support code were generated for the typedef’ed types. If level 2 optimization was used when generating the code for the IDL file that contained the typedefs, then the plugin and support code for the typedefs would not have been generated, and compilation and linking errors will result.

For example, consider this declaration:

typedef short MyShort

struct MyStructure { MyShort member;

};

With optimization 0: The type-plugin and support code for MyStructure will use the generated code for MyShort to serialize, deserialize, or otherwise manipulate the member field of

MyStructure.

With optimization 1: The type plug-in and support code for MyStructure will directly serialize, deserialize or otherwise manipulate the member field of MyStructure as a short—saving a function call. However, plugin and support code for MyShort is still generated because it would be used by the code generated from another IDL file that refers to MyShort.

With optimization 2: The type-plugin and support code for MyStructure will directly serialize, deserialize or otherwise manipulate the member field of MyStructure as a short–saving a function call. In addition, no plugin or support code for MyShort is generated.

3-84

3.7Using Generated Types without Connext (Standalone)

You can use the generated type-specific source and header files without linking the Connext libraries or even including the Connext header files. That is, the generated files for your data types can be used standalone.

The directory <NDDSHOME>/resource/rtiddsgen/standalone contains the required helper files:

include: header and templates files for C and C++.

src: source files for C and C++.

class: Java jar file.

Note: You must use rtiddsgen’s -notypecode option to generate code for standalone use.

3.7.1Using Standalone Types in C

The generated files that can be used standalone are:

<idl file name>.c: Types source file

<idl file name>.h: Types header file

The type plug-in code (<idl file>Plugin.[c,h]) and type-support code (<idl file>Support.[c,h]) cannot be used standalone.

To use the rtiddsgen-generated types in a standalone manner:

1.Make sure you use rtiddsgen’s -notypecode option to generate the code.

2.Include the directory <NDDSHOME>/resource/rtiddsgen/standalone/include in the list of directories to be searched for header files.

3.Add the source files, ndds_standalone_type.c and <idl file name>.c, to your project.

4.Include the file <idl file name>.h in the source files that will use the generated types in a standalone manner.

5.Compile the project using the following two preprocessor definitions:

a.NDDS_STANDALONE_TYPE

b.The definition for your platform (RTI_VXWORKS, RTI_QNX, RTI_WIN32, RTI_INTY, RTI_LYNX or RTI_UNIX)

3.7.2Using Standalone Types in C++

The generated files that can be used standalone are:

<idl file name>.cxx: Types source file

<idl file name>.h: Types header file

The type-plugin code (<idl file>Plugin.[cxx,h]) and type-support code (<idl file>Support.[cxx,h]) cannot be used standalone.

To use the generated types in a standalone manner:

1. Make sure you use rtiddsgen’s -notypecode option to generate the code.

3-85

2.Include the directory <NDDSHOME>/resource/rtiddsgen/standalone/include in the list of directories to be searched for header files.

3.Add the source files, ndds_standalone_type.cxx and <idl file name>.cxx, to your project.

4.Include the file <idl file name>.h in the source files that will use the rtiddsgen types in a standalone manner.

5.Compile the project using the following two preprocessor definitions:

a.NDDS_STANDALONE_TYPE

b.The definition for your platform (such as RTI_VXWORKS, RTI_QNX, RTI_WIN32, RTI_INTY, RTI_LYNX or RTI_UNIX)

3.7.3Standalone Types in Java

The generated files that can be used standalone are:

<idl type>.java

<idl type>Seq.java

The type code (<idl file>TypeCode.java), type-support code (<idl type>TypeSupport.java),

DataReader code (<idl file>DataReader.java) and DataWriter code (<idl file>DataWriter.java) cannot be used standalone.

To use the generated types in a standalone manner:

1.Make sure you use rtiddsgen’s -notypecode option to generate the code.

2.Include the file ndds_standalone_type.jar in the classpath of your project.

3.Compile the project using the standalone types files (<idl type>.java and <idl type>Seq.java).

3.8Interacting Dynamically with User Data Types

3.8.1Introduction to TypeCode

Type schemas—the names and definitions of a type and its fields—are represented by TypeCode objects. A type code value consists of a type code kind (see the TCKind enumeration below) and a list of members. For compound types like structs and arrays, this list will recursively include one or more type code values.

enum TCKind { TK_NULL, TK_SHORT, TK_LONG, TK_USHORT, TK_ULONG, TK_FLOAT, TK_DOUBLE, TK_BOOLEAN, TK_CHAR, TK_OCTET, TK_STRUCT,

3-86

TK_UNION,

TK_ENUM,

TK_STRING, TK_SEQUENCE, TK_ARRAY, TK_ALIAS, TK_LONGLONG, TK_ULONGLONG, TK_LONGDOUBLE, TK_WCHAR, TK_WSTRING, TK_VALUE, TK_SPARSE

}

Type codes unambiguously match type representations and provide a more reliable test than comparing the string type names.

The TypeCode class, modeled after the corresponding CORBA API, provides access to type- code information. For details on the available operations for the TypeCode class, see the API Reference HTML documentation, which is available for all supported programming languages (select Modules, DDS API Reference, Topic Module, Type Code Support).

Type codes are enabled by default when you run rtiddsgen. The -notypecode option disables generation of type code information. Type-code support does increase the amount of memory used, so if you need to save on memory, you may consider disabling type codes. See rtiddsgen Command-Line Arguments (Section 3.6.1).

Note: Type-code support must be enabled if you are going to use ContentFilteredTopics (Section 5.4) with the default SQL filter. You may disable type codes and use a custom filter, as described in Creating ContentFilteredTopics (Section 5.4.3).

3.8.2Defining New Types

Note: This section does not apply when using the separate add-on product, Ada 2005 Language Support, which does not support Dynamic Types.

Locally, your application can access the type code for a generated type "Foo" by calling the Foo_get_typecode() operation in the code for the type generated by rtiddsgen (unless type-code support is disabled with the -notypecode option). But you can also create TypeCodes at run time without any code generation.

Creating a TypeCode is parallel to the way you would define the type statically: you define the type itself with some name, then you add members to it, each with its own name and type.

For example, consider the following statically defined type. It might be in C, C++, or IDL; the syntax is largely the same.

struct MyType { long my_integer; float my_float; bool my_bool;

string<128> my_string; // @key

};

This is how you would define the same type at run time in C++:

DDS_ExceptionCode_t ex = DDS_NO_EXCEPTION_CODE; DDS_StructMemberSeq structMembers; // ignore for now DDS_TypeCodeFactory* factory = DDS_TypeCodeFactory::get_instance();

3-87

DDS_TypeCode* structTc = factory->create_struct_tc( "MyType", structMembers, ex);

// If structTc is NULL, check 'ex' for more information. structTc->add_member(my_integer", DDS_TYPECODE_MEMBER_ID_INVALID,

factory->get_primitive_tc(DDS_TK_LONG), DDS_TYPECODE_NONKEY_MEMBER, ex);

structTc->add_member("my_float", DDS_TYPECODE_MEMBER_ID_INVALID, factory->get_primitive_tc(DDS_TK_FLOAT), DDS_TYPECODE_NONKEY_MEMBER, ex);

structTc->add_member("my_bool", DDS_TYPECODE_MEMBER_ID_INVALID, factory->get_primitive_tc(DDS_TK_BOOLEAN), DDS_TYPECODE_NONKEY_MEMBER, ex);

structTc->add_member("my_string", DDS_TYPECODE_MEMBER_ID_INVALID, factory->create_string_tc(128), DDS_TYPECODE_KEY_MEMBER, ex);

More detailed documentation for the methods and constants you see above, including example code, can be found in the API Reference HTML documentation, which is available for all supported programming languages.

If, as in the example above, you know all of the fields that will exist in the type at the time of its construction, you can use the StructMemberSeq to simplify the code:

DDS_StructMemberSeq structMembers; structMembers.ensure_length(4, 4);

DDS_TypeCodeFactory* factory = DDS_TypeCodeFactory::get_instance();

structMembers[0].name = DDS_String_dup("my_integer"); structMembers[0].type = factory->get_primitive_tc(DDS_TK_LONG);

structMembers[1].name = DDS_String_dup("my_float"); structMembers[1].type = factory->get_primitive_tc(DDS_TK_FLOAT);

structMembers[2].name = DDS_String_dup("my_bool"); structMembers[2].type = factory->get_primitive_tc(DDS_TK_BOOLEAN);

structMembers[3].name = DDS_String_dup("my_string"); structMembers[3].type = factory->create_string_tc(128); structMembers[3].is_key = DDS_BOOLEAN_TRUE;

DDS_ExceptionCode_t ex = DDS_NO_EXCEPTION_CODE; DDS_TypeCode* structTc = factory->create_struct_tc("MyType",

structMembers, ex);

After you have defined the TypeCode, you will register it with a DomainParticipant using a logical name. You will use this logical name later when you create a Topic.

DDSDynamicDataTypeSupport* type_support =

new DDSDynamicDataTypeSupport(structTc, DDS_DYNAMIC_DATA_TYPE_PROPERTY_DEFAULT);

DDS_ReturnCode_t retcode = type_support->register_type(participant, "My Logical Type Name");

Now that you have created a type, you will need to know how to interact with objects of that type. Continue reading Section 3.8.3 below for more information.

3-88

3.8.3Sending Only a Few Fields

In some cases, your data model may contain a large number of potential fields, but it may not be desirable or appropriate to include a value for every one of them with every data sample.

It may use too much bandwidth. You may have a very large data structure, parts of which are updated very frequently. Rather than resending the entire data structure with every change, you may wish to send only those fields that have changed and rely on the recipients to reassemble the complete state themselves.

It may not make sense. Some fields may only have meaning in the presence of other fields. For example, you may have an event stream in which certain fields are only relevant for certain kinds of events.

To support these and similar cases, Connext supports sparse value types. A sample of such a type only contains the field values that were explicitly set by the sender. A recipient of that sample will receive an error when trying to look up the value of any other field.

An endpoint (DataWriter or DataReader) using a sparse value type will not communicate with another endpoint using a non-sparse value type or structure type, even if the two types contain similar member definitions, because these kinds of types have different semantics. A structure or non-sparse value type is a commitment to provide exactly the data described by the type's members and in a certain order. In contrast, a sparse value type is a commitment to provide some subset of those data values in no particular order.

Because direct programming language representations of data types typically have no way to express the concept of sparse fields (there is no way, for example, for a C structure to omit some of its fields), using sparse types requires use of the dynamic type API described in Defining New Types (Section 3.8.2). You will use the Dynamic Data API to work with sparse samples, just as you would with samples of any other dynamically defined type. For more information about working with sparse samples, see Objects of Dynamically Defined Types (Section 3.9.2) or the API Reference HTML documentation (select Modules, DDS API Reference, Topic Module, Dynamic Data).

A sparse version of the "MyType" type described above would be defined like this:

DDS_ExceptionCode_t ex = DDS_NO_EXCEPTION_CODE; DDS_TypeCodeFactory* factory = DDS_TypeCodeFactory::get_instance(); DDS_TypeCode* sparseTc = factory->create_sparse_tc(

"MySparseType", DDS_VM_NONE, NULL, ex);

// add members

sparseTc->add_member("my_integer", ID_MY_INTEGER, factory->get_primitive_tc(DDS_TK_LONG), DDS_TYPECODE_NONKEY_MEMBER, ex);

sparseTc->add_member("my_float", ID_MY_FLOAT, factory->get_primitive_tc(DDS_TK_FLOAT), DDS_TYPECODE_NONKEY_MEMBER, ex);

sparseTc->add_member("my_bool", ID_MY_BOOL, factory->get_primitive_tc(DDS_TK_BOOLEAN), DDS_TYPECODE_NONKEY_MEMBER, ex);

sparseTc->add_member("my_string", ID_MY_STRING, factory->create_string_tc(128), DDS_TYPECODE_KEY_MEMBER, ex);

Detailed descriptions of the methods and constants you see above can be found in the API Reference HTML documentation.

Integral to the definition of a sparse type are the member IDs of its fields. An ID is a two-byte integer that uniquely identifies a field within its parent type; these IDs are chosen by the type's

3-89

designer. (In the code example above, ID_MY_INTEGER, ID_MY_FLOAT, and ID_MY_BOOL are examples of user-defined symbolic constants representing member ID values.) When a sparse sample is serialized, the middleware will embed the IDs of the fields that are present, so that recipients will know how to deserialize it.

Although member IDs are a relatively efficient way to describe a sample's contents, they do use network bandwidth. This can be an important issue if you are considering using sparse types to decrease the size of your data samples on the network. Although the relative cost of adding member IDs to your packets will vary depending on the sizes and layout of your fields, the following is a good rule of thumb: if you expect a given data sample to contain less than half of the fields that are legal for its type, sparse types will probably save you on bandwidth. If, on the other hand, most samples contain most fields, you will probably be better off using a plain structure type and simply ignoring irrelevant fields on the receiving side.

3.8.4Type Extension and Versioning

As your system evolves, you may find that your data types need to change. And unless your system is relatively small, you may not be able to bring it all down at once in order to modify them. Instead, you may need to upgrade your types one component at a time—or even on the fly, without bringing any part of the system down.

You can use the sparse types described above to efficiently version types—and not just at the level of entire types, but at the level of individual fields.

You can add new fields to a type at any time. Because the type is sparse, existing publishers of the type that have not been updated will simply omit the new field in any data samples they send. If you anticipate changing your types in future versions of your system, make sure that you ignore fields that you do not recognize, so that your application will be robust to future type changes.

sparseTc->add_member("myNewInteger", ID_MY_NEW_INTEGER, DDS_TheTypeCodeFactory->get_primitive_tc(TK_LONG), DDS_TYPECODE_NONKEY_MEMBER, ex);

You cannot remove fields from an existing type. Doing so would break older applications and invalidate historical samples that might already be in the caches of upgraded applications. Instead, simply stop sending values for the fields you wish to deprecate.

3.8.5Sending Type Codes on the Network

In addition to being used locally, serialized type codes are typically published automatically during discovery as part of the built-in topics for publications and subscriptions. See Built-in DataReaders (Section 16.2). This allows applications to publish or subscribe to topics of arbitrary types. This functionality is useful for generic system monitoring tools like the rtiddsspy debug tool. For details on using rtiddsspy, see the API Reference HTML documentation (select

Modules, Programming Tools).

Note: Type codes are not cached by Connext upon receipt and are therefore not available from the built-in data returned by the DataWriter's get_matched_subscription_data() operation or the

DataReader's get_matched_publication_data() operation.

If your data type has an especially complex type code, you may need to increase the value of the type_code_max_serialized_length field in the DomainParticipant's

DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4). Or, to prevent the propagation of type codes altogether, you can set this value to zero (0). Be aware

3-90

that some features of monitoring tools, as well as some features of the middleware itself (such as ContentFilteredTopics) will not work correctly if you disable TypeCode propagation.

3.8.5.1Type Codes for Built-in Types

The type codes associated with the built-in types are generated from the following IDL type definitions:

module DDS {

/* String */ struct String {

string<max_size> value;

};

/* KeyedString */ struct KeyedString {

string<max_size> key; //@key string<max_size> value;

};

/* Octets */ struct Octets {

sequence<octet, max_size> value;

};

/* KeyedOctets */ struct KeyedOctets {

string<max_size> key; //@key sequence<octet, max_size> value;

};

};

The maximum size (max_size) of the strings and sequences that will be included in the type code definitions can be configured on a per-DomainParticipant-basis by using the properties in Table 3.14.

Table 3.14 Properties for Allocating Size of Built-in Types, per DomainParticipant

Built-

 

 

in

Property

Description

Type

 

 

 

 

 

 

 

Maximum size of the strings published by the DataWriters

 

 

and received by the DataReaders belonging to a

String

dds.builtin_type.string.max_size

DomainParticipant (includes the NULL-terminated

 

 

character).

 

 

Default: 1024

 

 

 

 

 

Maximum size of the keys used by the DataWriters and

 

dds.builtin_type.keyed_string.

DataReaders belonging to a DomainParticipant (includes the

 

max_key_size

NULL-terminated character).

KeyedSt

 

Default: 1024

 

 

 

Maximum size of the strings published by the DataWriters

ring

 

 

and received by the DataReaders belonging to a

 

dds.builtin_type.keyed_string.

 

DomainParticipant using the built-in type (includes the

 

max_size

 

NULL-terminated character).

 

 

 

 

Default: 1024

 

 

 

 

 

Maximum size of the octet sequences published by the

Octets

dds.builtin_type.octets.max_size

DataWriters and DataReaders belonging to a

DomainParticipant.

 

 

 

 

Default: 2048

 

 

 

3-91

Table 3.14 Properties for Allocating Size of Built-in Types, per DomainParticipant

Built-

 

 

in

Property

Description

Type

 

 

 

 

 

 

 

Maximum size of the key published by the DataWriter and

 

dds.builtin_type.keyed_octets.

received by the DataReaders belonging to the

 

DomainParticipant (includes the NULL-terminated

 

max_key_size

 

character).

Keyed-

 

 

Default:1024.

Octets

 

 

 

 

Maximum size of the octet sequences published by the

 

 

 

dds.builtin_type.keyed_octets.

DataWriters and DataReaders belonging to a

 

max_size

DomainParticipant.

 

 

Default: 2048

 

 

 

3.9Working with Data Samples

You should now understand how to define and work with data types, whether you're using the simple data types built into the middleware (see Built-in Data Types (Section 3.2)), dynamically defined types (see Managing Memory for Built-in Types (Section 3.2.8)), or code generated from IDL, XML, XSD, or WSDL files (see Sections 3.3 through 3.5).

Now that you have chosen one or more data types to work with, this section will help you understand how to create and manipulate objects of those types.

3.9.1Objects of Concrete Types

If you use one of the built-in types, or decide to generate custom types from an IDL or XML file, your Connext data type is like any other data type in your application: a class or structure with fields, methods, and other members that you interact with directly.

In C and C++, you create and delete your own objects from factories, just as you create Connext objects from factories. In the case of user data types, the factory is a singleton object called the type support. Objects allocated from these factories are deeply allocated and fully initialized.

/* In the generated header file: */ struct MyData {

char* myString;

};

/* In your code: */

MyData* sample = MyDataTypeSupport_create_data();

char* str = sample->myString; /*empty, non-NULL string*/

/* ... */

MyDataTypeSupport_delete_data(sample);

In C++, as in C, you create and delete objects using the TypeSupport factories.

MyData* sample = MyDataTypeSupport::create_data(); char* str = sample->myString; // empty, non-NULL string // ...

MyDataTypeSupport::delete_data(sample);

3-92

In C# and C++/CLI, you can use a no-argument constructor to allocate objects. Those objects will be deallocated by the garbage collector as appropriate.

//In the generated code (C++/CLI): public ref struct MyData {

public:

System::String^ myString;

};

//In your code, if you are using C#: MyData sample = new MyData();

System.String str = sample.myString; // empty, non-null string

//In your code, if you are using C++/CLI:

MyData^ sample = gcnew MyData();

System::String^ str = sample->myString; // empty, non-nullptr string

In Java, you can use a no-argument constructor to allocate objects. Those objects will be deallocated by the garbage collector as appropriate.

//In the generated code: public class MyData {

public String myString = "";

}

//In your code:

MyData sample = new MyData();

String str = sample->myString; // empty, non-null string

3.9.2Objects of Dynamically Defined Types

If you are working with a data type that was discovered or defined at run time, you will use the reflective API provided by the DynamicData class to get and set the fields of your object.

Consider the following type definition:

struct MyData { long myInteger;

};

As with a statically defined type, you will create objects from a TypeSupport factory. How to create or otherwise obtain a TypeCode, and how to subsequently create from it a DynamicDataTypeSupport, is described in Defining New Types (Section 3.8.2).

For more information about the DynamicData and DynamicDataTypeSupport classes, consult the API Reference HTML documentation, which is available for all supported programming languages (select Modules, DDS API Reference, Topic Module, Dynamic Data).

In C:

DDS_DynamicDataTypeSupport* support = ...;

DDS_DynamicData* sample = DDS_DynamicDataTypeSupport_create_data(support); DDS_Long theInteger = 0;

DDS_ReturnCode_t success = DDS_DynamicData_set_long(sample, "myInteger", DDS_DYNAMIC_DATA_MEMBER_ID_UNSPECIFIED, 5);

/* Error handling omitted. */

success = DDS_DynamicData_get_long(sample, &theInteger, "myInteger", DDS_DYNAMIC_DATA_MEMBER_ID_UNSPECIFIED);

/* Error handling omitted. "theInteger" now contains the value 5 if no error occurred.

*/

3-93

In C++:

DDSDynamicDataTypeSupport* support = ...; DDS_DynamicData* sample = support->create_data(); DDS_ReturnCode_t success = sample->set_long("myInteger",

DDS_DYNAMIC_DATA_MEMBER_ID_UNSPECIFIED, 5); // Error handling omitted.

DDS_Long theInteger = 0;

success = sample->get_long(&theInteger, "myInteger", DDS_DYNAMIC_DATA_MEMBER_ID_UNSPECIFIED);

//Error handling omitted.

//"theInteger" now contains the value 5 if no error occurred.

In C++/CLI:

using DDS;

DynamicDataTypeSupport^ support = ...; DynamicData^ sample = support->create_data(); sample->set_long("myInteger",

DynamicData::MEMBER_ID_UNSPECIFIED, 5);

int theInteger = sample->get_long("myInteger",

0 /*redundant w/ field name*/);

/* Exception handling omitted.

* "theInteger" now contains the value 5 if no error occurred. */

In C#:

using namespace DDS; DynamicDataTypeSupport support = ...; DynamicData sample = support.create_data();

sample.set_long("myInteger", DynamicData.MEMBER_ID_UNSPECIFIED, 5);

int theInteger = sample.get_long("myInteger", DynamicData.MEMBER_ID_UNSPECIFIED);

/* Exception handling omitted.

* "theInteger" now contains the value 5 if no error occurred. */

In Java:

import com.rti.dds.dynamicdata.*; DynamicDataTypeSupport support = ...;

DynamicData sample = (DynamicData) support.create_data(); sample.set_int("myInteger", DynamicData.MEMBER_ID_UNSPECIFIED, 5);

int theInteger = sample.get_int("myInteger", DynamicData.MEMBER_ID_UNSPECIFIED);

/* Exception handling omitted.

* "theInteger" now contains the value 5 if no error occurred. */

3-94

3-95

Chapter 4 Entities

The main classes extend an abstract base class called an Entity. Every Entity has a set of associated events known as statuses and a set of associated Quality of Service Policies (QosPolicies). In addition, a Listener may be registered with the Entity to be called when status changes occur. Entities may also have attached Conditions, which provide a way to wait for status changes.

This chapter describes the common operations and general designed patterns shared by all

Entities including DomainParticipants, Topics, Publishers, DataWriters, Subscribers, and

DataReaders. In subsequent chapters, the specific statuses, Listeners, Conditions, and QosPolicies for each class will be discussed in detail.

4-1

4.1Common Operations for All Entities

All Entities (DomainParticipants, Topics, Publishers, DataWriters, Subscribers, and DataReaders) provide operations for:

Creating and Deleting Entities (Section 4.1.1)

Enabling Entities (Section 4.1.2)

Getting an Entity’s Instance Handle (Section 4.1.3)

Getting Status and Status Changes (Section 4.1.4)

Getting and Setting Listeners (Section 4.1.5)

Getting the StatusCondition (Section 4.1.6)

Getting and Setting QosPolicies (Section 4.1.7)

4.1.1Creating and Deleting Entities

The factory design pattern is used in creating and deleting Entities. Instead of declaring and constructing or destructing Entities directly, a factory object is used to create an Entity. Almost all entity factories are objects that are also entities. The only exception is the factory for a

DomainParticipant. See Table 4.1.

Table 4.1 Entity Factories

Entity

Created by

 

 

 

 

DomainParticipant

DomainParticipantFactory

(a static singleton object provided by Connext)

 

 

 

Topic

 

 

 

Publisher

 

 

 

Subscriber

DomainParticipant

 

 

DataWritera

 

DataReadera

 

DataWritera

Publisher

DataReadera

Subscriber

a. DataWriters may be created by a DomainParticipant or a Publisher. Similarly, DataReaders may be created by a

DomainParticipant or a Subscriber.

All entities that are factories have:

Operations to create and delete child entities. For example:

DDSPublisher::create_datawriter, DDSDomainParticipant::delete_topic

Operations to get and set the default QoS values used when creating child entities. For example:

DDSSubscriber::get_default_datareader_qos, DDSDomainParticipantFactory::set_default_participant_qos

An ENTITYFACTORY QosPolicy (Section 6.4.2) to specify whether or not the newly created child entity should be automatically enabled upon creation.

An entity that is a factory cannot be deleted until all the child entities created by it have been deleted.

4-2

Each Entity obtained through create_<entity>() must eventually be deleted by calling delete_<entity>, or by calling delete_contained_entities().

4.1.2Enabling Entities

The enable() operation changes an Entity from a non-operational to an operational state. Entity objects can be created disabled or enabled. This is controlled by the value of the ENTITYFACTORY QosPolicy (Section 6.4.2) on the corresponding factory for the Entity (not on the Entity itself).

By default, all Entities are automatically created in the enabled state. This means that as soon as the Entity is created, it is ready to be used. In some cases, you may want to create the Entity in a ‘disabled’ state. For example, by default, as soon as you create a DataReader, the DataReader will start receiving new samples for its Topic if they are being sent. However, your application may still be initializing other components and may not be ready to process the data at that time. In that case, you can tell the Subscriber to create the DataReader in a disabled state. After all of the other parts of the application have been created and initialized, then the DataReader can be enabled to actually receive messages.

To create a particular entity in a disabled state, modify the EntityFactory QosPolicy of its corresponding factory entity before calling create_<entity>(). For example, to create a disabled DataReader, modify the Subscriber’s QoS as follows:

DDS_SubscriberQos subscriber_qos;

subscriber->get_qos(subscriber_qos); subscriber_qos.entity_factory.autoenable_created_entities =

DDS_BOOLEAN_FALSE;

subscriber->set_qos(subscriber_qos);

DDSDataReader* datareader = subscriber->create_datareader( topic, DDS_DATAREADER_QOS_DEFAULT, listener);

When the application is ready to process received data, it can enable the DataReader:

datareader->enable();

4.1.2.1Rules for Calling enable()

In the following, a ‘Factory’ refers to a DomainParticipant, Publisher, or Subscriber; a ‘child’ refers to an entity created by the factory:

If the factory is disabled, its children are always created disabled, regardless of the setting in the factory's EntityFactoryQoS.

If the factory is enabled, its children will be created either enabled or disabled, according to the setting in the factory's EntityFactory Qos.

Calling enable() on a child whose factory object is still disabled will fail and return

DDS_RECODE_RECONDITION_NOT_MET.

Calling enable() on a factory with EntityFactoryQoS set to DDS_BOOLEAN_TRUE will recursively enable all of the factory’s children. If the factory’s EntityFactoryQoS is set to DDS_BOOLEAN_FALSE, only the factory itself will be enabled.

Calling enable() on an entity that is already enabled returns DDS_RETCODE_OK and has no effect.

There is no complementary “disable” operation. You cannot disable an entity after it is enabled. Disabled entities must have been created in that state.

An entity’s Listener will only be invoked if the entity is enabled.

The existence of an entity is not propagated to other DomainParticipants until the entity is enabled (see Chapter 14: Discovery).

4-3

If a DataWriter/DataReader is to be created in an enabled state, then the associated Topic must already be enabled. The enabled state of the Topic does not matter, if the Publisher/ Subscriber has its EntityFactory QosPolicy to create children in a disabled state.

When calling enable() for a DataWriter/DataReader, both the Publisher/Subscriber and the

Topic must be enabled, or the operation will fail and return

DDS_RETCODE_PRECONDITION_NOT_MET.

The following operations may be invoked on disabled Entities:

get_qos() and set_qos() Some DDS-specified QosPolicies are immutable—they cannot be changed after an Entity is enabled. This means that for those policies, if the entity was created in the disabled state, get/set_qos() can be used to change the values of those policies until enabled() is called on the Entity. After the Entity is enabled, changing the values of those policies will not affect the Entity. However, there are mutable QosPolicies whose values can be changed at anytime–even after the Entity has been enabled.

Finally, there are extended QosPolicies that are not a part of the DDS specification but offered by Connext to control extended features for an Entity. Some of those extended QosPolicies cannot be changed after the Entity has been created—regardless of whether the Entity is enabled or disabled.

Into which exact categories a QosPolicy falls—mutable at any time, immutable after enable, immutable after creation—is described in the documentation for the specific policy.

get_status_changes() and get_*_status() The status of an Entity can be retrieved at any time (but the status of a disabled Entity never changes).

get_statuscondition() An Entity’s StatusCondition can be checked at any time (although the status of a disabled Entity never changes).

get_listener() and set_listener() An Entity’s Listener can be changed at any time.

create_*() and delete_*() A factory Entity can still be used to create or delete any child Entity that it can produce. Note: following the rules discussed previously, a disabled Entity will always create its children in a disabled state, no matter what the value of the EntityFactory QosPolicy is.

lookup_*() An Entity can always look up children it has previously created.

Most other operations are not allowed on disabled Entities. Executing one of those operations when an Entity is disabled will result in a return code of DDS_RETCODE_NOT_ENABLED. The documentation for a particular operation will explicitly state if it is not allowed to be used if the Entity is disabled.

Note: The builtin transports are implicitly registered when (a) the DomainParticipant is enabled,

(b) the first DataWriter/DataReader is created, or (c) you look up a builtin data reader, whichever happens first. Any changes to the builtin transport properties that are made after the builtin transports have been registered will have no affect on any DataWriters/DataReaders.

4.1.3Getting an Entity’s Instance Handle

The Entity class provides an operation to retrieve an instance handle for the object. The operation is simply:

InstanceHandle_t get_instance_handle()

An instance handle is a global ID for the entity that can be used in methods that allow user applications to determine if the entity was locally created, if an entity is owned (created) by another entity, etc.

4-4

4.1.4Getting Status and Status Changes

The get_status_changes() operation retrieves the set of events, also known in DDS terminology as communication statuses, in the Entity that have changed since the last time get_status_changes() was called. This method actually returns a value that must be bitwise AND’ed with an enumerated bit mask to test whether or not a specific status has changed. The operation can be used in a polling mechanism to see if any statuses related to the Entity have changed. If an entity is disabled, all communication statuses are in the “unchanged” state so the list returned by the get_status_changes() operation will be empty.

A set of statuses is defined for each class of Entities. For each status, there is a corresponding operation, get_<status-name>_status(), that can be used to get its current value. For example, a

DataWriter has a DDS_OFFERED_DEADLINE_MISSED status; it also has a get_offered_deadline_missed_status() operation:

DDS_StatusMask statuses;

DDS_OfferedDeadlineMissedStatus deadline_stat;

statuses = datawriter->get_status_changes();

if (statuses & DDS_OFFERED_DEADLINE_MISSED_STATUS) { datawriter->get_offered_deadline_missed_status(&deadline_stat); printf(“Deadline missed %d times.\n”,

deadline_stat.total_count);

}

See Section 4.3 for more information about statuses.

4.1.5Getting and Setting Listeners

Each type of Entity has an associated Listener, see Listeners (Section 4.4). A Listener represents a set of functions that users may install to be called asynchronously when the state of communication statuses change.

The get_listener() operation returns the current Listener attached to the Entity.

The set_listener() operation installs a Listener on an Entity. The Listener will only be invoked on the changes of statuses specified by the accompanying mask. Only one listener can be attached to each Entity. If a Listener was already attached, set_listener() will replace it with the new one.

The get_listener() and set_listener() operations are directly provided by the DomainParticipant,

Topic, Publisher, DataWriter, Subscriber, and DataReader classes so that listeners and masks used in the argument list are specific to each Entity.

Note: The set_listener() operation is not synchronized with the listener callbacks, so it is possible to set a new listener on an participant while the old listener is in a callback. Therefore you should be careful not to delete any listener that has been set on an enabled participant unless some application-specific means are available of ensuring that the old listener cannot still be in use.

See Section 4.4 for more information about Listeners.

4.1.6Getting the StatusCondition

Each type of Entity may have an attached StatusCondition, which can be accessed through the get_statuscondition() operation. You can attach the StatusCondition to a WaitSet, to cause your application to wait for specific status changes that affect the Entity.

See Section 4.6 for more information about StatusConditions and WaitSets.

4-5

4.1.7Getting and Setting QosPolicies

Each type of Entity has an associated set of QosPolicies (see Section 4.2). QosPolicies allow you to configure and set properties for the Entity.

While most QosPolicies are defined by the DDS specification, some are offered by Connext as extensions to control parameters specific to the implementation.

There are two ways to specify a QoS policy:

Programmatically, as described in this section.

QosPolicies can also be configured from XML resources (files, strings)—with this approach, you can change the QoS without recompiling the application. The QoS settings are automatically loaded by the DomainParticipantFactory when the first DomainParticipant is created. See Chapter 17: Configuring QoS with XML.

The get_qos() operation retrieves the current values for the set of QosPolicies defined for the

Entity.

QosPolicies can be set programmatically when an Entity is created, or modified with the Entity's set_qos() operation.

The set_qos() operation sets the QosPolicies of the entity. Note: not all QosPolicy changes will take effect instantaneously; there may be a delay since some QosPolicies set for one entity, for example, a DataReader, may actually affect the operation of a matched entity in another application, for example, a DataWriter.

The get_qos() and set_qos() operations are passed QoS structures that are specific to each derived entity class, since the set of QosPolicies that effect each class of entities is different.

Each QosPolicy has default values (listed in the API Reference HTML documentation). If you want to use custom values, there are three ways to change QosPolicy settings:

Before Entity creation (if custom values should be used for multiple Entities). See Section 4.1.7.1.

During Entity creation (if custom values are only needed for a particular Entity). See Section 4.1.7.2.

After Entity creation (if the values initially specified for a particular Entity are no longer appropriate). See Section 4.1.7.3.

Regardless of when or how you make QoS changes, there are some rules to follow:

Some QosPolicies interact with each other and thus must be set in a consistent manner. For instance, the maximum value of the HISTORY QosPolicy’s depth parameter is limited by values set in the RESOURCE_LIMITS QosPolicy. If the values within a QosPolicy structure are inconsistent, then set_qos() will return the error INCONSISTENT_POLICY, and the operation will have no effect.

Some policies can only be set when the Entity is created, or before the Entity is enabled. Others can be changed at any time. In general, all standard DDS QosPolicies can be changed before the Entity is enabled. A subset can be changed after the Entity is enabled. Connext-specific QosPolicies either cannot be changed after creation or can be changed at any time. The changeability of each QosPolicy is documented in the API Reference HTML documentation as well as in Table 4.2. If you attempt to change a policy after it cannot be changed, set_qos() will fail with a return IMMUTABLE_POLICY.

4.1.7.1Changing the QoS Defaults Used to Create Entities: set_default_*_qos()

Each parent factory has a set of default QoS settings that are used when the child entity is created. The DomainParticipantFactory has default QoS values for creating DomainParticipants. A DomainParticipant has a set of default QoS for each type of entity that can be created from the

DomainParticipant (Topic, Publisher, Subscriber, DataWriter, and DataReader). Likewise, a Publisher

4-6

has a set of default QoS values used when creating DataWriters, and a Subscriber has a set of default QoS values used when creating DataReaders.

An entity’s QoS are set when it is created. Once an entity is created, all of its QoS—for itself and its child entities—are fixed unless you call set_qos() or set_qos_with_profile() on that entity. Calling set_default_<entity>_qos() on a parent entity will have no effect on child entities that have already been created.

You can change these default values so that they are automatically applied when new child entities are created. For example, suppose you want all DataWriters for a particular Publisher to have their RELIABILITY QosPolicy set to RELIABLE. Instead of making this change for each DataWriter when it is created, you can change the default used when any DataWriter is created from the Publisher by using the Publisher’s set_default_datawriter_qos() operation.

DDS_DataWriterQos default_datawriter_qos;

// get the current default values publisher->get_default_datawriter_qos(default_datawriter_qos);

// change to desired default values default_datawriter_qos.reliability.kind =

DDS_RELIABLE_RELIABILITY_QOS;

// set the new default values publisher->set_default_datawriter_qos(default_datawriter_qos);

// created datawriters will use new default values

datawriter = publisher->create_datawriter(topic, NULL, NULL, NULL);

Note: It is not safe to get or set the default QoS values for an entity while another thread may be simultaneously calling get_default_<entity>_qos(), set_default_<entity>_qos(), or create_<entity>() with DDS_<ENTITY>_QOS_DEFAULT as the qos parameter (for the same entity).

Another way to make QoS changes is by using XML resources (files, strings). For more information, see Chapter 17: Configuring QoS with XML.

4.1.7.2Setting QoS During Entity Creation

If you only want to change a QosPolicy for a particular entity, you can pass in the desired QosPolicies for an entity in its creation routine.

To customize an entity's QoS before creating it:

1.(C API Only) Initialize a QoS object with the appropriate INITIALIZER constructor.

2.Call the relevant get_<entity>_default_qos() method.

3.Modify the QoS values as desired.

4.Create the entity.

For example, to change the RELIABLE QosPolicy for a DataWriter before creating it:

// Initialize the QoS object DDS_DataWriterQos datawriter_qos;

// Get the default values publisher->get_default_datawriter_qos(datawriter_qos);

// Modify the QoS values as desired datawriter_qos.reliability.kind = DDS_BEST_EFFORT_RELIABILITY_QOS;

// Create the DataWriter with new values datawriter =

publisher->create_datawriter(topic, datawriter_qos, NULL, NULL);

4-7

Another way to set QoS during entity creation is by using a QoS profile. For more information, see Chapter 17: Configuring QoS with XML.

4.1.7.3Changing the QoS for an Existing Entity

Some policies can also be changed after the entity has been created. To change such a policy after the entity has been created, use the entity’s set_qos() operation.

For example, suppose you want to tweak the DEADLINE QoS for an existing DataWriter:

DDS_DataWriterQos datawriter_qos;

// get the current values datawriter->get_qos(datawriter_qos);

// make desired changes datawriter_qos.deadline.period.sec = 3; datawriter_qos.deadline.period.nanosec = 0;

// set new values datawriter->set_qos(datawriter_qos);

Another way to make QoS changes is by using a QoS profile. For more information, see Chapter 17: Configuring QoS with XML.

Note: In the code examples presented in this section, we are not testing for the return code for the set_qos(), set_default_*_qos() functions. If the values used in the QosPolicy structures are inconsistent then the functions will fail and return INCONSISTENT_POLICY. In addition, set_qos() may return IMMUTABLE_POLICY if you try to change a QosPolicy on an Entity after that policy has become immutable. User code should test for and address those anomalous conditions.

4.1.7.4Default Values

Connext provides special constants for each Entity type that can be used in set_qos() and set_default_*_qos() to reset the QosPolicy values to the original DDS default values:

DDS_PARTICIPANT_QOS_DEFAULT

DDS_PUBLISHER_QOS_DEFAULT

DDS_SUBSCRIBER_QOS_DEFAULT

DDS_DATAWRITER_QOS_DEFAULT

DDS_DATAREADER_QOS_DEFAULT

DDS_TOPIC_QOS_DEFAULT

For example, if you want to set a DataWriter’s QoS back to their DDS-specified default values:

datawriter->set_qos(DDS_DATAWRITER_QOS_DEFAULT);

Or if you want to reset the default QosPolicies used by a Publisher to create DataWriters back to their DDS-specified default values:

publisher->set_default_datawriter_qos(DDS_DATAWRITER_QOS_DEFAULT);

Note: These defaults cannot be used to initialize a QoS structure for an entity. For example, the following is NOT allowed:

Not Allowed—> DataWriterQos dataWriterQos = DATAWRITER_QOS_DEFAULT; // modify QoS...

create_datawriter(dataWriterQos);

4-8

4.2QosPolicies

Connext’s behavior is controlled by the Quality of Service (QoS) policies of the data communication entities (DomainParticipant, Topic, Publisher, Subscriber, DataWriter, and

DataReader) used in your applications. This section summarizes each of the QosPolicies that you can set for the various entities.

The QosPolicy class is the abstract base class for all the QosPolicies. It provides the basic mechanism for an application to specify quality of service parameters. Table 4.2 on page 4-9 lists each supported QosPolicy (in alphabetical order), provides a summary, and points to a section in the manual that provides further details.

The detailed description of a QosPolicy that applies to multiple Entities is provided in the first chapter that discusses an Entity whose behavior the QoS affects. Otherwise, the discussion of a QosPolicy can be found in the chapter of the particular Entity to which the policy applies. As you will see in the detailed description sections, all QosPolicies have one or more parameters that are used to configure the policy. The how’s and why’s of tuning the parameters are also discussed in those sections.

As first discussed in Controlling Behavior with Quality of Service (QoS) Policies (Section 2.5.1), QosPolicies may interact with each other, and certain values of QosPolicies can be incompatible with the values set for other policies.

The set_qos() operation will fail if you attempt to specify a set of values would result in an inconsistent set of policies. To indicate a failure, set_qos() will return INCONSISTENT_POLICY. Section 4.2.1 provides further information on QoS compatibility within an Entity as well as across matching Entities, as does the discussion/reference section for each QosPolicy listed in Table 4.2 on page 4-9.

The values of some QosPolicies cannot be changed after the Entity is created or after the Entity is enabled. Others may be changed at any time. The detailed section on each QosPolicy states when each policy can be changed. If you attempt to change a QosPolicy after it becomes immutable (because the associated Entity has been created or enabled, depending on the policy), set_qos() will fail with a return code of IMMUTABLE_POLICY.

Table 4.2 QosPolicies

QosPolicy

Summary

 

 

 

 

Asynchronous-

Configures the mechanism that sends user data in an external middleware thread. See

Publisher

Section 6.4.1.

 

 

 

This QoS policy is used in the context of two features:

 

For a Collaborative DataWriter, specifies the group of DataWriters expected to

Availability

collaboratively provide data and the timeouts that control when to allow data to be

available that may skip samples.

 

For a Durable Subscription, configures a set of Durable Subscriptions on a DataWriter.

 

See Section 6.5.1.

 

 

 

Specifies and configures the mechanism that allows Connext to collect multiple user

Batch

data samples to be sent in a single network packet, to take advantage of the efficiency of

 

sending larger packets and thus increase effective throughput. See Section 6.5.2.

 

 

Database

Various settings and resource limits used by Connext to control its internal database. See

Section 8.5.1.

 

 

 

DataReaderProtocol

This QosPolicy configures the Connext on-the-network protocol, RTPS. See Section 7.6.1.

 

 

DataReaderResourceLimits

Various settings that configure how DataReaders allocate and use physical memory for

internal resources. See Section 7.6.2.

 

 

 

DataWriterProtocol

This QosPolicy configures the Connext on-the-network protocol, RTPS. See Section 6.5.3.

 

 

4-9

Table 4.2 QosPolicies

QosPolicy

Summary

 

 

 

 

 

Controls how many threads can concurrently block on a write() call of this DataWriter.

DataWriterResourceLimits

Also controls the number of batches managed by the DataWriter and the instance-

 

replacement kind used by the DataWriter. See Section 6.5.4.

 

 

 

For a DataReader, specifies the maximum expected elapsed time between arriving data

 

samples.

 

Deadline

For a DataWriter, specifies a commitment to publish samples with no greater elapsed

 

time between them.

 

 

See Section 6.5.5.

 

 

 

 

Controls how Connext will deal with data sent by multiple DataWriters for the same

DestinationOrder

topic. Can be set to "by reception timestamp" or to "by source timestamp." See

 

Section 6.5.6.

 

 

 

Discovery

Configures the mechanism used by Connext to automatically discover and connect with

new remote applications. See Section 8.5.2.

 

 

 

 

 

DiscoveryConfig

Controls the amount of delay in discovering entities in the system and the amount of

discovery traffic in the network. See Section 8.5.3.

 

 

 

DomainParticipantResource-

Various settings that configure how DomainParticipants allocate and use physical

memory for internal resources, including the maximum sizes of various properties. See

Limits

Section 8.5.4.

 

 

 

 

 

Durability

Specifies whether or not Connext will store and deliver data that were previously

published to new DataReaders. See Section 6.5.7.

 

 

 

 

DurabilityService

Various settings to configure the external

Persistence Service used by Connext for

DataWriters with a Durability QoS setting of Persistent Durability. See Section 6.5.8.

 

 

 

EntityFactory

Controls whether or not child entities are created in the enabled state. See Section 6.4.2.

 

 

EntityName

Assigns a name to a DomainParticipant. See Section 8.5.5.

 

 

 

Event

Configures the DomainParticipant’s internal

thread that handles timed events. See

Section 8.5.5.

 

 

 

 

 

 

ExclusiveArea

Configures multi-thread concurrency and

deadlock prevention capabilities. See

Section 6.4.3.

 

 

 

 

 

 

Along with TOPIC_DATA QosPolicy (Section 5.2.1) and USER_DATA QosPolicy

GroupData

(Section 6.5.25), this QosPolicy is used to attach a buffer of bytes to Connext's discovery

 

meta-data. See 6.4.4.

 

 

 

 

Specifies how much data must to stored by Connextfor the DataWriter or DataReader.

History

This QosPolicy affects the RELIABILITY QosPolicy (Section 6.5.19) as well as the

 

DURABILITY QosPolicy (Section 6.5.7). See Section 6.5.10.

 

 

LatencyBudget

Suggestion to Connext on how much time is allowed to deliver data. See Section 6.5.11.

 

 

Lifespan

Specifies how long Connext should consider data sent by an user application to be valid.

See Section 6.5.12.

 

 

 

 

 

Liveliness

Specifies and configures the mechanism that allows DataReaders to detect when

DataWriters become disconnected or "dead." See Section 6.5.13.

 

 

 

Logging

Configures the properties associated with Connext logging. See Section 8.4.1.

 

 

MultiChannel

Configures a DataWriter’s ability to send data on different multicast groups (addresses)

based on the value of the data. See Section 6.5.14.

 

 

 

Ownership

Along with Ownership Strength, specifies if DataReaders for a topic can receive data

from multiple DataWriters at the same time. See Section 6.5.15.

 

 

 

OwnershipStrength

Used to arbitrate among multiple DataWriters of the same instance of a Topic when

Ownership QoSPolicy is EXLUSIVE. See Section 6.5.16.

 

 

 

Partition

Adds string identifiers that are used for matching DataReaders and DataWriters for the

same Topic. See Section 6.4.5.

 

 

 

 

 

 

4-10

Table 4.2 QosPolicies

QosPolicy

Summary

 

 

 

 

Presentation

Controls how Connext presents data received by an application to the DataReaders of the

data. See Section 6.4.6.

 

 

 

Profile

Configures the way that XML documents containing QoS profiles are loaded by RTI.

See Section 8.4.2.

 

 

 

 

Stores name/value(string) pairs that can be used to configure certain parameters of

Property

Connext that are not exposed through formal QoS policies. It can also be used to store

and propagate application-specific name/value pairs, which can be retrieved by user

 

 

code during discovery. See Section 6.5.17.

 

 

 

Specifies how Connext sends application data on the network. By default, data is sent in

PublishMode

the user thread that calls the DataWriter’s write() operation. However, this QosPolicy

 

can be used to tell Connext to use its own thread to send the data. See Section 6.5.18.

 

 

ReaderDataLifeCycle

Controls how a DataReader manages the lifecycle of the data that it has received. See

Section 7.6.3.

 

 

 

ReceiverPool

Configures threads used by Connext to receive and process data from transports (for

example, UDP sockets). See Section 8.5.6.

 

 

 

Reliability

Specifies whether or not Connext will deliver data reliably. See Section 6.5.19.

 

 

 

Controls the amount of physical memory allocated for entities, if dynamic allocations

ResourceLimits

are allowed, and how they occur. Also controls memory usage among different instance

 

values for keyed topics. See Section 6.5.20.

 

 

 

Configures DomainParticipant-independent resources used by Connext. Mainly used to

SystemResourceLimits

change the maximum number of DomainParticipants that can be created within a single

 

process (address space). See Section 8.4.3.

 

 

TimeBasedFilter

Set by a DataReader to limit the number of new data values received over a period of

time. See Section 7.6.4.

 

 

 

TopicData

Along with Group Data QosPolicy and User Data QosPolicy, used to attach a buffer of

bytes to Connext's discovery meta-data. See Section 5.2.1.

 

 

 

TransportBuiltin

Specifies which built-in transport plugins are used. See Section 8.5.7.

 

 

 

Specifies the multicast address on which a DataReader wants to receive its data. Can

TransportMulticast

specify a port number as well as a subset of the available transports with which to

 

receive the multicast data. See Section 7.6.5.

 

 

 

Specifies the automatic mapping between a list of topic expressions and multicast

TransportMulticastMapping

address that can be used by a DataReader to receive data for a specific topic. See

 

Section 8.5.8.

 

 

TransportPriority

Set by a DataWriter to tell Connext that the data being sent is a different "priority" than

other data. See Section 6.5.21.

 

 

 

TransportSelection

Allows you to select which physical transports a DataWriter or DataReader may use to

send or receive its data. See Section 6.5.22.

 

 

 

TransportUnicast

Specifies a subset of transports and port number that can be used by an Entity to receive

data. See Section 6.5.23.

 

 

 

TypeConsistencyEnforcement

Defines rules that determine whether the type used to publish a given data stream is

consistent with that used to subscribe to it. See Section 7.6.6.

 

 

 

Used to attach application-specific value(s) to a DataWriter or DataReader. These values

TypeSupport

are passed to the serialization or deserialization routine of the associated data type. See

 

Section 6.5.24.

 

 

UserData

Along with Topic Data QosPolicy and Group Data QosPolicy, used to attach a buffer of

bytes to Connext's discovery meta-data. See Section 6.5.25.

 

 

 

WireProtocol

Specifies IDs used by the RTPS wire protocol to create globally unique identifiers. See

Section 8.5.9.

 

 

 

WriterDataLifeCycle

Controls how a DataWriter handles the lifecycle of the instances (keys) that the

DataWriter is registered to manage. See Section 6.5.26.

 

 

 

4-11

4.2.1QoS Requested vs. Offered Compatibility—the RxO Property

Some QosPolicies that apply to entities on the sending and receiving sides must have their values set in a compatible manner. This is known as the policy’s ‘requested vs. offered’ (RxO) property. Entities on the publishing side ‘offer’ to provide a certain behavior. Entities on the subscribing side ‘request’ certain behavior. For Connext to connect the sending entity to the receiving entity, the offered behavior must satisfy the requested behavior.

For some QosPolicies, the allowed values may be graduated in a way that the offered value will satisfy the requested value if the offered value is either greater than or less than the requested value. For example, if a DataWriter’s DEADLINE QosPolicy specifies a duration less than or equal to a DataReader’s DEADLINE QosPolicy, then the DataWriter is promising to publish data at least as fast or faster than the DataReader requires new data to be received. This is a compatible situation (see Section 6.5.5).

Other QosPolicies require the values on the sending side and the subscribing side to be exactly equal for compatibility to be met. For example, if a DataWriter’s OWNERSHIP QosPolicy is set to SHARED, and the matching DataReader’s value is set to EXCLUSIVE, then this is an incompatible situation since the DataReader and DataWriter have different expectations of what will happen if more than one DataWriter publishes an instance of the Topic (see OWNERSHIP QosPolicy (Section 6.5.15)).

Finally there are QosPolicies that do not require compatibility between the sending entity and the receiving entity, or that only apply to one side or the other. Whether or not related entities on the publishing and subscribing sides must use compatible settings for a QosPolicy is indicated in the policy’s RxO property, which is provided in the detailed section on each QosPolicy.

RxO = YESThe policy is set at both the publishing and subscribing ends and the values must be set in a compatible manner. What it means to be compatible is defined by the QosPolicy.

RxO = NOThe policy is set only on one end or at both the publishing and subscribing ends, but the two settings are independent. There the requested vs. offered semantics are not used for these QosPolicies.

For those QosPolicies that follow the RxO semantics, Connext will compare the values of those policies for compatibility. If they are compatible, then Connext will connect the sending entity to the receiving entity allowing data to be sent between them. If they are found to be incompatible, then Connext will not interconnect the entities preventing data to be sent between them.

In addition, Connext will record this event by changing the associated communication status in both the sending and receiving applications, see Types of Communication Status (Section 4.3.1). Also, if you have installed Listeners on the associated Entities, then Connext will invoke the associated callback functions to notify user code that an incompatible QoS combination has been found, see Types of Listeners (Section 4.4.1).

For Publishers and DataWriters, the status corresponding to this situation is

OFFERED_INCOMPATIBLE_QOS_STATUS. For Subscribers and DataReaders, the corresponding status is REQUESTED_INCOMPATIBLE_QOS_STATUS. The question of why a DataReader is not receiving data sent from a matching DataWriter can often be answered if you have instrumented the application with Listeners for the statuses noted previously.

4.2.2Special QosPolicy Handling Considerations for C

Many QosPolicy structures contain variable-length sequences to store their parameters. In the C++, C++/CLI, C# and Java languages, the memory allocation related to sequences are handled automatically through constructors/destructors and overloaded operators. However, the C language is limited in what it provides to automatically handle memory management. Thus, Connext provides functions and macros in C to initialize, copy, and finalize (free) QosPolicy structures defined for Entities.

4-12

In the C language, it is not safe to use an Entity’s QosPolicy structure declared in user code unless it has been initialized first. In addition, user code should always finalize an Entity’s QosPolicy structure to release any memory allocated for the sequences–even if the Entity’s QosPolicy structure was declared as a local, stack variable.

Thus, for a general Entity’s QosPolicy, Connext will provide:

DDS_<Entity>Qos_INITIALIZER This is a macro that should be used when a DDS_<Entity>Qos structure is declared in a C application.

struct DDS_<Entity>Qos qos = DDS_<Entity>Qos_INITIALIZER;

DDS_<Entity>Qos_initialize() This is a function that can be used to initialize a DDS_<Entity>Qos structure instead of the macro above.

struct DDS_<Entity>Qos qos; DDS_<Entity>QOS_initialize(&qos);

DDS_<Entity>Qos_finalize() This is a function that should be used to finalize a DDS_<Entity>Qos structure when the structure is no longer needed. It will free any memory allocated for sequences contained in the structure.

struct DDS_<Entity>Qos qos = DDS_<Entity>Qos_INITIALIZER;

...

<use qos>

...

// now done with qos

DDS_<Entity>QoS_finalize(&qos);

DDS<Entity>Qos_copy() This is a function that can be used to copy one DDS_<Entity>Qos structure to another. It will copy the sequences contained in the source structure and allocate memory for sequence elements if needed. In the code below, both dstQos and srcQos must have been initialized at some point earlier in the code.

DDS_<Entity>QOS_copy(&dstQos, &srcQos);

4.3Statuses

This section describes the different statuses that exist for an entity. A status represents a state or an event regarding the entity. For instance, maybe Connext found a matching DataReader for a DataWriter, or new data has arrived for a DataReader.

Your application can retrieve an Entity’s status by:

explicitly checking for any status changes with get_status_changes().

explicitly checking a specific status with get_<statusname>_status().

using a Listener, which provides asynchronous notification when a status changes.

using StatusConditions and WaitSets, which provide a way to wait for status changes.

If you want your application to be notified of status changes asynchronously: create and install a Listener for the Entity. Then internal Connext threads will call the listener methods when the status changes. See Listeners (Section 4.4).

If you want your application to wait for status changes: set up StatusConditions to indicate the statuses of interest, attach the StatusConditions to a WaitSet, and then call the WaitSet’s wait() operation. The call to wait() will block until statuses in the attached Conditions changes (or until a timeout period expires). See Conditions and WaitSets (Section 4.6).

4-13

This section includes the following:

Types of Communication Status (Section 4.3.1)

Special Status-Handling Considerations for C (Section 4.3.2)

4.3.1Types of Communication Status

Each Entity is associated with a set of Status objects representing the “communication status” of that Entity. The list of statuses actively monitored by Connext is provided in Table 4.3 on page 4- 15. A status structure contains values that give you more information about the status; for example, how many times the event has occurred since the last time the user checked the status, or how many time the event has occurred in total.

Changes to status values cause activation of corresponding StatusCondition objects and trigger invocation of the corresponding Listener functions to asynchronously inform the application that the status has changed. For example, a change in a Topic’s INCONSISTENT_TOPIC_STATUS may trigger the TopicListener’s on_inconsistent_topic() callback routine (if such a Listener is installed).

Statuses can be grouped into two categories:

Plain communication status: In addition to a flag that indicates whether or not a status has changed, a plain communication status also contains state and thus has a corresponding structure to hold its current value.

Read communication status: A read communication status is more like an event and has no state other than whether or not it has occurred. Only two statuses listed in Table 4.3 are read communications statuses: DATA_AVAILABLE and DATA_ON_READERS.

As mentioned in Section 4.1.4, all entities have a get_status_changes() operation that can be used to explicitly poll for changes in any status related to the entity. For plain statuses, each entry has operations to get the current value of the status; for example, the Topic class has a get_inconsistent_topic_status() operation. For read statuses, your application should use the take() operation on the DataReader to retrieve the newly arrived data that is indicated by

DATA_AVAILABLE and DATA_ON_READER.

Note that the two read communication statuses do not change independently. If data arrives for a DataReader, then its DATA_AVAILABLE status changes. At the same time, the DATA_ON_READERS status changes for the DataReader’s Subscriber.

Both types of status have a StatusChangedFlag. This flag indicates whether that particular communication status has changed since the last time the status was read by the application. The way the StatusChangedFlag is maintained is slightly different for the plain communication status and the read communication status, as described in the following sections:

Changes in Plain Communication Status (Section 4.3.1.1)

Changes in Read Communication Status (Section 4.3.1.2)

4.3.1.1Changes in Plain Communication Status

As seen in Figure 4.1 on page 4-15, for the plain communication status, the StatusChangedFlag flag is initially set to FALSE. It becomes TRUE whenever the plain communication status changes and is reset to FALSE each time the application accesses the plain communication status via the proper get_<plain communication status>() operation.

The communication status is also reset to FALSE whenever the associated listener operation is called, as the listener implicitly accesses the status which is passed as a parameter to the operation.

The fact that the status is reset prior to calling the listener means that if the application calls the get_<plain communication status>() operation from inside the listener, it will see the status already reset.

4-14

Figure 4.1 Status Changes for Plain Communication Status

status changes

 

 

 

 

 

 

 

 

 

 

 

 

StatusChangedFlag = FALSE

StatusChangedFlag = TRUE

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

User calls get_*_status(), or after listener is invoked

Table 4.3 Communication Statuses

Related

Status (DDS_*_STATUS)

Description

Reference

Entity

 

 

 

 

 

 

 

 

 

 

 

 

 

Another Topic exists with the same name but

 

Topic

INCONSISTENT_TOPIC

different characteristics—for example, a different

Section 5.3.1

 

 

type.

 

 

 

 

 

 

 

This status indicates that a DataWriter has

 

 

 

received an application-level acknowledgment

 

 

APPLICATION_

for a sample. The listener provides the identities

Section 6.3.12

 

ACKNOWLEDGMENT

of the sample and acknowledging DataReader, as

 

 

 

well as user-specified response data sent from the

 

 

 

DataReader by the acknowledgment message.

 

 

 

 

 

 

DATA_WRITER_CACHE

The status of the DataWriter’s cache.

Section 6.3.6.1

 

This status does not have a Listener.

 

 

 

 

 

 

 

 

 

The status of a DataWriter’s internal protocol

 

 

 

related metrics (such as the number of samples

 

 

DATA_WRITER_PROTOCOL

pushed, pulled, filtered) and the status of wire

Section 6.3.6.2

 

 

protocol traffic.

 

 

 

This status does not have a Listener.

 

 

 

 

 

 

 

The liveliness that the DataWriter has committed

 

 

 

to (through its Liveliness QosPolicy) was not

 

 

LIVELINESS_LOST

respected (assert_liveliness() or write() not called

Section 6.3.6.3

Data-

 

in time), thus DataReader entities may consider

 

 

the DataWriter as no longer active.

 

Writer

 

 

 

 

 

OFFERED_DEADLINE_

The deadline that the DataWriter has committed

 

 

 

 

through its Deadline QosPolicy was not

Section 6.3.6.4

 

MISSED

 

respected for a specific instance of the Topic.

 

 

 

 

 

 

 

 

 

OFFERED_INCOMPATIBLE_

An offered QosPolicy value was incompatible

 

 

with what was requested by a DataReader of the

Section 6.3.6.5

 

QOS

 

same Topic.

 

 

 

 

 

 

 

 

 

 

The DataWriter found a DataReader that matches

 

 

PUBLICATION_MATCHED

the Topic, has compatible QoSs and a common

Section 6.3.6.6

 

partition, or a previously matched DataReader has

 

 

been deleted.

 

 

 

 

 

 

RELIABLE_WRITER_

The number of unacknowledged samples in a

 

 

reliable DataWriter's cache has reached one of the

Section 6.3.6.7

 

CACHE_CHANGED

 

predefined trigger points.

 

 

 

 

 

 

 

 

 

 

One or more reliable DataReaders has either been

 

 

RELIABLE_READER_

discovered, deleted, or changed between active

Section 6.3.6.8

 

ACTIVITY_CHANGED

and inactive state as specified by the

 

 

 

LivelinessQosPolicy of the DataReader.

 

 

 

 

 

4-15

Table 4.3 Communication Statuses

Related

Status (DDS_*_STATUS)

Description

Reference

Entity

 

 

 

 

 

 

 

Subscriber

DATA_ON_READERS

New data is available for any of the readers that

Section 7.2.9

 

 

were created from the Subscriber.

 

 

DATA_AVAILABLE

New data (one or more samples) are available for

Section 7.3.7.1

 

 

the specific DataReader.

 

 

DATA_READER_CACHE

The status of the reader's cache.

Section 7.3.7.2

 

This status does not have a Listener.

 

 

 

 

 

 

 

 

 

The status of a DataReader’s internal protocol

 

 

 

related metrics (such as the number of samples

 

 

DATA_READER_PROTOCOL

received, filtered, rejected) and the status of wire

Section 7.3.7.3

 

 

protocol traffic.

 

 

 

This status does not have a Listener.

 

 

 

 

 

 

 

The liveliness of one or more DataWriters that

 

 

 

were writing instances read by the DataReader

 

 

LIVELINESS_CHANGED

has either been discovered, deleted, or changed

Section 7.3.7.4

 

 

between active and inactive state as specified by

 

Data-

 

the LivelinessQosPolicy of the DataWriter.

 

Reader

REQUESTED_DEADLINE_

New data was not received for an instance of the

 

 

Topic within the time period set by the

Section 7.3.7.5

 

MISSED

 

DataReader’s Deadline QosPolicy.

 

 

 

 

 

 

 

 

 

REQUESTED_

A requested QosPolicy value was incompatible

 

 

with what was offered by a DataWriter of the

Section 7.3.7.6

 

INCOMPATIBLE_QOS

 

same Topic.

 

 

 

 

 

 

 

 

 

SAMPLE_LOST

A sample sent by Connext has been lost (never

Section 7.3.7.7

 

 

received).

 

 

SAMPLE_REJECTED

A received sample has been rejected due to a

Section 7.3.7.8

 

 

resource limit (buffers filled).

 

 

 

The DataReader has found a DataWriter that

 

 

SUBSCRIPTION_MATCHED

matches the Topic, has compatible QoSs and a

Section 7.3.7.9

 

 

common partition, or an existing matched

 

 

 

DataWriter has been deleted.

 

 

 

 

 

An exception to this rule is when the associated listener is the 'nil' listener. The 'nil' listener is treated as a NO-OP and the act of calling the 'nil' listener does not reset the communication status. (See Types of Listeners (Section 4.4.1).)

For example, the value of the StatusChangedFlag associated with the REQUESTED_DEADLINE_MISSED status will become TRUE each time new deadline occurs (which increases the RequestedDeadlineMissed status’ total_count field). The value changes to FALSE when the application accesses the status via the corresponding get_requested_deadline_missed_status() operation on the proper Entity.

4.3.1.2Changes in Read Communication Status

As seen in Figure 4.2 on page 4-17, for the read communication status, the StatusChangedFlag flag is initially set to FALSE. The StatusChangedFlag becomes TRUE when either a data sample arrives or the ViewStateKind, SampleStateKind, or InstanceStateKind of any existing sample changes for any reason other than a call to one of the read/take operations. Specifically, any of the following events will cause the StatusChangedFlag to become TRUE:

The arrival of new data.

A change in the InstanceStateKind of a contained instance. This can be caused by either:

Notification that an instance has been disposed by:

4-16

the DataWriter that owns it, if OWNERSHIP = EXCLUSIVE

or by any DataWriter, if OWNERSHIP = SHARED

The loss of liveliness of the DataWriter of an instance for which there is no other

DataWriter.

The arrival of the notification that an instance has been unregistered by the only DataWriter that is known to be writing the instance.

Depending on the kind of StatusChangedFlag, the flag transitions to FALSE again as follows:

The DATA_AVAILABLE StatusChangedFlag becomes FALSE when either on_data_available() is called or the read/take operation (or their variants) is called on the associated DataReader.

The DATA_ON_READERS StatusChangedFlag becomes FALSE when any of the following occurs:

on_data_on_readers() is called.

on_data_available() is called on any DataReader belonging to the Subscriber.

One of the read/take operations (or their variants) is called on any DataReader belonging to the Subscriber.

Figure 4.2 Status Changes for Read Communication Status

4-17

4.3.2Special Status-Handling Considerations for C

Some status structures contain variable-length sequences to store their values. In the C++, C++/ CLI, C# and Java languages, the memory allocation related to sequences are handled automatically through constructors/destructors and overloaded operators. However, the C language is limited in what it provides to automatically handle memory management. Thus, Connext provides functions and macros in C to initialize, copy, and finalize (free) status structures.

In the C language, it is not safe to use a status structure that has internal sequences declared in user code unless it has been initialized first. In addition, user code should always finalize a status structure to release any memory allocated for the sequences–even if the status structure was declared as a local, stack variable.

Thus, for a general status structure, Connext will provide:

DDS_<STATUS>STATUS_INITIALIZER This is a macro that should be used when a DDS_<Status>Status structure is declared in a C application.

struct DDS_<Status>Status status = DDS_<Status>Status_INITIALIZER;

DDS_<Status>Status_initialize() This is a function that can be used to initialize a DDS_<Status>Status structure instead of the macro above.

struct DDS_<Status>Status status; DDS_<Status>Status_initialize(&Status);

DDS_<Status>Status_finalize() This is a function that should be used to finalize a DDS_<Status>Status structure when the structure is no longer needed. It will free any memory allocated for sequences contained in the structure.

struct DDS_<Status>Status status = DDS_<Status>Status_INITIALIZER;

...

<use status>

...

// now done with Status DDS_<Status>Status_finalize(&status);

DDS<Status>Status_copy() This is a function that can be used to copy one DDS_<Status>Status structure to another. It will copy the sequences contained in the source structure and allocate memory for sequence elements if needed. In the code below, both dstStatus and srcStatus must have been initialized at some point earlier in the code.

DDS_<Status>Status_copy(&dstStatus, &srcStatus);

Note that many status structures do not have sequences internally. For those structures, you do not need to use the macro and methods provided above. However, they have still been created for your convenience.

4.4Listeners

This section describes Listeners and how to use them:

Types of Listeners (Section 4.4.1)

Creating and Deleting Listeners (Section 4.4.2)

Special Considerations for Listeners in C (Section 4.4.3)

Hierarchical Processing of Listeners (Section 4.4.4)

4-18

Operations Allowed within Listener Callbacks (Section 4.4.5)

Listeners are triggered by changes in an entity’s status. For instance, maybe Connext found a matching DataReader for a DataWriter, or new data has arrived for a DataReader.

4.4.1Types of Listeners

The Listener class is the abstract base class for all listeners. Each entity class (DomainParticipant, Topic, Publisher, DataWriter, Subscriber, and DataReader) has its own derived Listener class that add methods for handling entity-specific statuses. The hierarchy of Listener classes is presented in Figure 4.3. The methods are called by an internal Connext thread when the corresponding status for the Entity changes value.

Figure 4.3 Listener Class Hierarchy

DDSListener

DDSDataReaderListener DDSDataWriterListener DDSTopicListener

DDSSubscriberListener DDSPublisherListener

DDSDomainParticipantListener

You can choose which changes in status will trigger a callback by installing a listener with a bit- mask. Bits in the mask correspond to different statuses. The bits that are true indicate that the listener will be called back when there are changes in the corresponding status.

You can specify a listener and set its bit-mask before or after you create an Entity:

During Entity creation:

DDS_StatusMask mask = DDS_REQUESTED_DEADLINE_MISSED_STATUS |

DDS_DATA_AVAILABLE_STATUS;

datareader = subscriber->create_datareader(topic, DDS_DATAREADER_QOS_DEFAULT, listener, mask);

or afterwards:

DDS_StatusMask mask = DDS_REQUESTED_DEADLINE_MISSED_STATUS |

DDS_DATA_AVAILABLE_STATUS;

datareader->set_listener(listener, mask);

As you can see in the above examples, there are two components involved when setting up listeners: the listener itself and the mask. Both of these can be null. Table 4.4 describes what happens when a status change occurs. See Hierarchical Processing of Listeners (Section 4.4.4) for more information.

4-19

Table 4.4 Effect of Different Combinations of Listeners and Status Bit Masks

 

No Bits Set in Mask

Some/All Bits Set in Mask

 

 

 

 

 

 

 

 

For the statuses that are enabled in the

Listener is

Connext finds the next most relevant

mask, the most relevant listener will be

called.

Specified

listener for the changed status.

The 'statusChangedFlag' for the relevant

 

 

 

 

status is reset.

 

 

 

Listener is

Connext behaves as if the listener is not

Connext behaves as if the listener callback is

installed and finds the next most relevant

installed, but the callback is doing nothing.

NULL

listener for that status.

This is called a ‘nil’ listener.

 

 

 

 

4.4.2Creating and Deleting Listeners

There is no factory for creating or deleting a Listener; use the natural means in each language binding (for example, “new” or “delete” in C++ or Java). For example:

class HelloWorldListener : public DDSDataReaderListener { virtual void on_data_available(DDSDataReader* reader);

};

void HelloWorldListener::on_data_available(DDSDataReader* reader)

{

printf("received data\n");

}

// Create a Listener

HelloWorldListener *reader_listener = NULL; reader_listener = new HelloWorldListener();

// Delete a Listener delete reader_listener;

A listener cannot be deleted until the entity it is attached to has been deleted. For example, you must delete the DataReader before deleting the DataReader’s listener.

Note: Due to a thread-safety issue, the destruction of a DomainParticipantListener from an enabled DomainParticipant should be avoided—even if the DomainParticipantListener has been removed from the DomainParticipant. (This limitation does not affect the Java API.)

4.4.3Special Considerations for Listeners in C

In C, a Listener is a structure with function pointers to the user callback routines. Often, you may only be interested in a subset of the statuses that can be monitored with the Listener. In those cases, you may not set all of the functions pointers in a listener structure to a valid function. In that situation, we recommend that the unused, callback-function pointers are set to NULL. While setting the DDS_StatusMask to enable only the callbacks for the statuses in which you are interested (and thus only enabling callbacks on the functions that actually exist) is safe, we still recommend that you clear all of the unused callback pointers in the Listener structure.

To help, in the C language, we provide a macro that can be used to initialize a Listener structure so that all of its callback pointers are set to NULL. For example

DDS_<Entity>Listener listener = DDS_<Entity>Listener_INITIALIZER;

// now only need to set the listener callback pointers for statuses // to be monitored

There is no need to do this in languages other than C.

4.4.4Hierarchical Processing of Listeners

As seen in Figure 4.3 on page 4-19, Listeners for some entities derive from the Connext Listeners for related entities. This means that the derived Listener has all of the methods of its parent class.

4-20

You can install Listeners at all levels of the object hierarchy. At the top is the

DomainParticipantListener; only one can be installed in a DomainParticipant. Then every Subscriber and Publisher can have their own Listener. Finally, each Topic, DataReader and DataWriter can have their own listeners. All are optional.

Suppose, however, that an Entity does not install a Listener, or installs a Listener that does not have particular communication status selected in the bitmask. In this case, if/when that particular status changes for that Entity, the corresponding Listener for that Entity’s parent is called. Status changes are “propagated” from child Entity to parent Entity until a Listener is found that is registered for that status. Connext will give up and drop the status-change event only if no Listeners have been installed in the object hierarchy to be called back for the specific status. This is true for plain communication statuses. Read communication statuses are handle somewhat differently, see Processing Read Communication Statuses (Section 4.4.4.1).

For example, suppose that Connext finds a matching DataWriter for a local DataReader. This event will change the SUBSCRIPTION_MATCHED status. So the local DataReader object is checked to see if the application has installed a listener that handles the SUBSCRIPTION_MATCH status. If not, the Subscriber that created the DataReader is checked to see if it has a listener installed that handles the same event. If not, the DomainParticipant is checked. The DomainParticipantListener methods are called only if none of the descendent entities of the DomainParticipant have listeners that handle the particular status that has changed. Again, all listeners are optional. Your application does not have to handle any communication statuses.

Table 4.5 lists the callback functions that are available for each Entity’s status listener.

Table 4.5 Listener Callback Functions

Entity Listener for:

Callback Functions

 

 

 

 

 

 

 

Topics

on_inconsistent_topic()

 

 

 

 

 

on_liveliness_lost()

 

 

 

 

 

on_offered_deadline_missed()

 

 

 

 

Publishers and DataWriters

on_offered_incompatible_qos()

 

 

 

on_publication_matched()

 

 

 

 

 

 

 

on_reliable_reader_activity_changed()

 

 

 

 

 

on_reliable_writer_cache_changed()

DomainParticipants

 

 

Subscribers

on_data_on_readers()

 

 

 

 

 

on_data_available

 

 

 

 

 

on_liveliness_changed()

 

 

 

 

 

on_requested_deadline_missed()

 

Subscribers and DataReaders

 

 

on_requested_incompatible_qos()

 

 

 

 

 

on_sample_lost()

 

 

 

 

 

on_sample_rejected()

 

 

 

 

 

on_subscription_matched()

 

 

 

4.4.4.1Processing Read Communication Statuses

The processing of the DATA_ON_READERS and DATA_AVAILABLE read communication statuses are handled slightly differently since, when new data arrives for a DataReader, both statuses change simultaneously. However, only one, if any, Listener will be called to handle the event.

If there is a Listener installed to handle the DATA_ON_READERS status in the DataReader’s

Subscriber or in the DomainParticipant, then that Listener’s on_data_on_readers() function will be called back. The DataReaderListener’s on_data_available() function is called only if the DATA_ON_READERS status is not handle by any relevant listeners.

4-21

This can be useful if you have generic processing to do whenever new data arrives for any DataReader. You can execute the generic code in the on_data_on_readers() method, and then dispatch the processing of the actual data to the specific DataReaderListener’s on_data_available() function by calling the notify_datareaders() method on the Subscriber.

For example:

void on_data_on_readers (DDSSubscriber *subscriber)

{

//Do some general processing that needs to be done

//whenever new data arrives, but is independent of

//any particular DataReader

< generic processing code here >

//Now dispatch the actual processing of the data

//to the specific DataReader for which the data

//was received

subscriber->notify_datareaders();

}

4.4.5Operations Allowed within Listener Callbacks

Due to the potential for deadlock, some Connext APIs should not be invoked within the functions of listener callbacks. Exactly which Connext APIs are restricted depends on the Entity upon which the Listener is installed, as well as the configuration of ‘Exclusive Areas,’ as discussed in Section 4.5.

Please read and understand Exclusive Areas (EAs) (Section 4.5) and Restricted Operations in Listener Callbacks (Section 4.5.1) to ensure that the calls made from your Listeners are allowed and will not cause potential deadlock situations.

4.5Exclusive Areas (EAs)

Listener callbacks are invoked by internal Connext threads. To prevent undesirable, multi- threaded interaction, the internal threads may take and hold semaphores (mutexes) used for mutual exclusion. In your listener callbacks, you may want to invoke functions provided by the Connext API. Internally, those Connext functions also may take mutexes to prevent errors due to multi-threaded access to critical data or operations.

4-22

Once there are multiple mutexes to protect different critical regions, the possibility for deadlock exists. Consider Figure 4.4’s scenario, in which there are two threads and two mutexes.

Figure 4.4 Multiple Mutexes Leading to a Deadlock Condition

Thread1

Thread2

take(MutexA)

take(MutexB)

take(MutexB)

take(MutexA)

X

X

Deadlock!

Thread1 takes MutexA while simultaneously Thread2 takes MutexB. Then, Thread1 takes MutexB and simultaneously Thread2 takes MutexA. Now both threads are blocked since they hold a mutex that the other thread is trying to take. This is a deadlock condition.

While the probability of entering the deadlock situation in Figure 4.4 depends on execution timing, when there are multiple threads and multiple mutexes, care must be taken in writing code to prevent those situations from existing in the first place. Connext has been carefully created and analyzed so that we know our threads internally are safe from deadlock interactions.

However, when Connext threads that are holding mutexes call user code in listeners, it is possible for user code to inadvertently cause the threads to deadlock if Connext APIs that try to take other mutexes are invoked. To help you avoid this situation, RTI has defined a concept known as Exclusive Areas, some restrictions regarding the use of Connext APIs within user callback code, and a QoS policy that allows you to configure Exclusive Areas.

Connext uses Exclusive Areas (EAs) to encapsulate mutexes and critical regions. Only one thread at a time can be executing code within an EA. The formal definition of EAs and their implementation ensures safety from deadlock and efficient entering and exiting of EAs. While every Entity created by Connext has an associated EA, EAs may be shared among several entities. A thread is automatically in the entity's EA when it is calling the entity’s listener.

Connext allows you to configure all the Entities within an application in a single domain to share a single Exclusive Area. This would greatly restrict the concurrency of thread execution within Connext’s multi-threaded core. However, doing so would release all restrictions on using Connext APIs within your callback code.

You may also have the best of both worlds by configuring a set of Entities to share a global EA and others to have their own. For the Entities that have their own EAs, the types of Connext operations that you can call from the Entity’s callback are restricted.

To understand why the general EA framework limits the operations that can be called in an EA, consider a modification to the example previously presented in Figure 4.4. Suppose we create a rule that is followed when we write our code. “For all situations in which a thread has to take multiple mutexes, we write our code so that the mutexes are always taken in the same order.” Following the rule will ensure us that the code we write cannot enter a deadlock situation due to the taking of the mutexes, see Figure 4.5.

Connext defines an ordering of the mutexes it creates. Generally speaking, there are three ordered levels of Exclusive Areas:

4-23

Figure 4.5 Taking Multiple Mutexes in a Specific Order to Eliminate Deadlock

Thread1

Thread2

take(MutexA)

X take(MutexA)

take(MutexB)

 

 

 

 

 

 

 

 

give(MutexB)

 

 

 

 

 

 

 

 

 

 

 

 

give(MutexA)

 

take(MutexB)

 

 

 

 

 

 

 

 

By creating an order in which multiple mutexes are taken, you can guarantee that no deadlock situation will arise. In this case, if a thread must take both MutexA and MutexB, we write our code so that in those cases MutexA is always taken before MutexB.

ParticipantEA There is only one ParticipantEA per participant. The creation and deletion of all Entities (create_xxx(), delete_xxx()) take the ParticipantEA. In addition, the enable() method for an Entity and the setting of the Entity’s QoS, set_qos(), also take the ParticipantEA

SubscriberEA This EA is created on a per-Subscriber basis by default. You can assume that the methods of a Subscriber will take the SubscriberEA. In addition, the DataReaders created by a Subscriber share the EA of its parent. This means that the methods of a DataReader (including take() and read()) will take the EA of its Subscriber. Therefore, operations on DataReaders of the same Subscriber, will be serialized, even when invoked from multiple concurrent application threads. As mentioned, the enable() and set_qos() methods of both Subscribers and DataReaders will take the ParticipantEA. The same is true for the create_datareader() and delete_datareader() methods of the Subscriber.

PublisherEA This EA is created on a per-Publisher basis by default. You can assume that the methods of a Publisher will take the PublisherEA. In addition, the DataWriters created by a Publisher share the EA of its parent. This means that the methods of a DataWriter including write() will take the EA of its Publisher. Therefore, operations on DataWriters of the same Publisher will be serialized, even when invoked from multiple concurrent application threads. As mentioned, the enable() and set_qos() methods of both Publishers and DataWriters will take the ParticipantEA, as well as the create_datawriter() and delete_datawriter() methods of the Publisher.

In addition, you should also be aware that:

The three EA levels are ordered in the following manner: ParticipantEA < SubscriberEA < PublisherEA

When executing user code in a listener callback of an Entity, the internal Connext thread is already in the EA of that Entity or used by that Entity.

If a thread is in an EA, it can call methods associated with either a higher EA level or that share the same EA. It cannot call methods associated with a lower EA level nor ones that use a different EA at the same level.

4-24

4.5.1Restricted Operations in Listener Callbacks

Based on the background and rules provided in Exclusive Areas (EAs) (Section 4.5), this section describes how EAs restrict you from using various Connext APIs from within the Listener callbacks of different Entities.

Note: these restrictions do not apply to builtin topic listener callbacks.

By default, each Publisher and Subscriber creates and uses its own EA, and shares it with its children DataWriters and DataReaders, respectively. In that case:

Within a DataWriter/DataReader’s Listener callback, do not:

create any entities

delete any entities

enable any entities

set QoS’s on any entities

Within a Subscriber/DataReader’s Listener callback, do not call any operations on:

Other Subscribers

DataReaders that belong to other Subscribers

Publishers/DataWriters that have been configured to use the ParticipantEA (see below)

Within a Publisher/DataWriter Listener callback, do not call any operations on:

Other Publishers

DataWriters that belong to other Publishers

Any Subscribers

Any DataReaders

Connext will enforce the rules to avoid deadlock, and any attempt to call an illegal method from within a Listener callback will return DDS_RETCODE_ILLEGAL_OPERATION.

However, as previously mentioned, if you are willing to trade-off concurrency for flexibility, you may configure individual Publishers and Subscribers (and thus their DataWriters and DataReaders) to share the EA of their participant. In the limit, only a single ParticipantEA is shared among all Entities. When doing so, the restrictions above are lifted at a cost of greatly reduced concurrency. You may create/delete/enable/set_qos’s and generally call all of the methods of any other entity in the Listener callbacks of Entities that share the ParticipantEA.

Use the EXCLUSIVE_AREA QosPolicy (DDS Extension) (Section 6.4.3) of the Publisher or Subscriber to set whether or not to use a shared exclusive area. By default, Publishers and Subscribers will create and use their own individual EAs. You can configure a subset of the Publishers and Subscribers to share the ParticipantEA if you need the Listeners associated with those entities or children entities to be able to call any of the restricted methods listed above.

Regardless of how the EXCLUSIVE_AREA QosPolicy is set, the following operations are never allowed in any Listener callback:

Destruction of the entity to which the Listener is attached. For instance, a DataWriter/

DataReader Listener callback must not destroy its DataWriter/DataReader.

Within the TopicListener callback, you cannot call any operations on DataReaders,

DataWriters, Publishers, Subscribers or DomainParticipants.

4-25

4.6Conditions and WaitSets

Conditions and WaitSets provide another way for Connext to communicate status changes (including the arrival of data) to your application. While a Listener is used to provide a callback for asynchronous access, Conditions and WaitSets provide synchronous data access. In other words, Listeners are notification-based and Conditions are wait-based.

A WaitSet allows an application to wait until one or more attached Conditions becomes true (or until a timeout expires).

Briefly, your application can create a WaitSet, attach one or more Conditions to it, then call the WaitSet’s wait() operation. The wait() blocks until one or more of the WaitSet’s attached Conditions becomes TRUE.

A Condition has a trigger_value that can be TRUE or FALSE. You can retrieve the current value by calling the Condition’s only operation, get_trigger_value().

There are three kinds of Conditions. A Condition is a root class for all the conditions that may be attached to a WaitSet. This basic class is specialized in three classes:

GuardConditions (Section 4.6.6) are created by your application. Each GuardCondition has a single, user-settable, boolean trigger_value. Your application can manually trigger the GuardCondition by calling set_trigger_value(). Connext does not trigger or clear this type of condition—it is completely controlled by your application.

ReadConditions and QueryConditions (Section 4.6.7) are created by your application, but triggered by Connext. ReadConditions provide a way for you to specify the data

samples that you want to wait for, by indicating the desired sample-states, view-states, and instance-states1.

StatusConditions (Section 4.6.8) are created automatically by Connext, one for each Entity. A StatusCondition is triggered by Connext when there is a change to any of that Entity’s enabled statuses.

Figure 4.6 on page 4-27 shows the relationship between these objects and other Entities in the system.

A WaitSet can be associated with more than one Entity (including multiple DomainParticipants). It can be used to wait on Conditions associated with different DomainParticipants. A WaitSet can only be in use by one application thread at a time.

4.6.1Creating and Deleting WaitSets

There is no factory for creating or deleting a WaitSet; use the natural means in each language binding (for example, “new” or “delete” in C++ or Java).

For example, to delete a WaitSet:

delete waitset;

There are two ways to (DDS_WaitSetProperty_t

create a WaitSet—with or without specifying WaitSet properties , described in Table 4.6).

If properties are not specified when the WaitSet is created, the WaitSet will wake up as soon as a trigger event occurs (that is, when an attached Condition becomes true). This is the default behavior if properties are not specified.

This ‘immediate wake-up’ behavior is optimal if you want to minimize latency (to wake

up and process the data or event as soon as possible). However, "waking up" involves a context switch—the operating system must signal and schedule the thread that is

1. These states are described in The SampleInfo Structure (Section 7.4.6).

4-26

Figure 4.6 Conditions and WaitSets

Table 4.6 WaitSet Properties (DDS_WaitSet_Property_t)

Type

Field Name

Description

 

 

 

long

max_event_count

Maximum number of trigger events to cause a WaitSet to wake up.

 

 

 

 

 

Maximum delay from occurrence of first trigger event to cause a

 

 

WaitSet to wake up.

DDS_Duration_t

max_event_delay

This value should reflect the maximum acceptable latency

increase (time delay from occurrence of the event to waking up

 

 

 

 

the waitset) incurred as a result of waiting for additional events

 

 

before waking up the waitset.

 

 

 

waiting on the WaitSet. A context switch consumes significant CPU and therefore waking up on each data update is not optimal in situations where the application needs to maximize throughput (the number of messages processed per second). This is especially true if the receiver is CPU limited.

4-27

To create a WaitSet with default behavior:

WaitSet* waitset = new WaitSet();

If properties are specified when the WaitSet is created, the WaitSet will wait for either (a) up to max_event_count trigger events to occur, (b) up to max_event_delay time from the occurrence of the first trigger event, or (c) up to the timeout maximum wait duration specified in the call to wait().

To create a WaitSet with properties:

DDS_WaitSetProperty_t prop;

Prop.max_event_count = 5;

DDSWaitSet* waitset = new DDSWaitSet(prop);

4.6.2WaitSet Operations

WaitSets have only a few operations, as listed in Table 4.7 on page 4-28. For details, see the API Reference HTML documentation.

Table 4.7 WaitSet Operations

Operation

Description

 

 

 

 

 

Attaches a Condition to this WaitSet.

 

You may attach a Condition to a WaitSet that is currently being waited upon

 

(via the wait() operation). In this case, if the Condition has a trigger_value of

attach_condition

TRUE, then attaching the Condition will unblock the WaitSet.

 

Adding a Condition that is already attached to the WaitSet has no effect. If the

 

Condition cannot be attached, Connext will return an OUT_OF_RESOURCES

 

error code.

 

 

 

Detaches a Condition from the WaitSet. Attempting to detach a Condition that is

detach_condition

not to attached the WaitSet will result in a PRECONDITION_NOT_MET

 

error code.

 

 

wait

Blocks execution of the thread until one or more attached Conditions becomes true, or

until a user-specified timeout expires. See Section 4.6.3.

 

 

 

get_conditions

Retrieves a list of attached Conditions.

 

 

get_property

Retrieves the DDS_WaitSetProperty_t structure of the associated WaitSet.

 

 

set_property

Sets the DDS_WaitSetProperty_t structure, to configure the associated WaitSet to

return after one or more trigger events have occurred.

 

 

 

4.6.3Waiting for Conditions

The WaitSet’s wait() operation allows an application thread to wait for any of the attached Conditions to trigger (become TRUE).

If any of the attached Conditions are already TRUE when wait() is called, it returns immediately. If none of the attached Conditions are TRUE, wait() blocks—suspending the calling thread. The wait() call will return when either (a) one or more of the attached Conditions becomes TRUE or

(b) a user-specified timeout period expires.

Note: The resolution of the timeout period is constrained by the resolution of the system clock.

You can also configure the properties of the WaitSet so that it will wait for up to max_event_count trigger events to occur before returning, or for up to max_event_delay time from the occurrence of the first trigger event before returning. See Creating and Deleting WaitSets (Section 4.6.1).

If wait() does not timeout, it returns a list of the attached Conditions that became TRUE and therefore unblocked the wait.

4-28

If wait() does timeout, it returns TIMEOUT and an empty list of Conditions.

Only one application thread can be waiting on the same WaitSet. If wait() is called on a WaitSet that already has a thread blocking on it, the operation will immediately return PRECONDITION_NOT_MET.

Note: If you detach a Condition from a Waitset that is currently in a wait state (that is, you are waiting on it), wait() may return OK and an empty sequence of conditions.

4.6.3.1How WaitSets Block

The blocking behavior of the WaitSet is illustrated in Figure 4.7. The result of a wait() operation depends on the state of the WaitSet, which in turn depends on whether at least one attached

Condition has a trigger_value of TRUE.

If the wait() operation is called on a WaitSet with state BLOCKED, it will block the calling thread. If wait() is called on a WaitSet with state UNBLOCKED, it will return immediately.

When the WaitSet transitions from BLOCKED to UNBLOCKED, it wakes up the thread (if there is one) that had called wait() on it. There is no implied “event queuing” in the awakening of a WaitSet. That is, if several Conditions attached to the WaitSet have their trigger_value transition to true in sequence, Connext will only unblock the WaitSet once.

Figure 4.7 WaitSet Blocking Behavior

4.6.4Processing Triggered Conditions—What to do when Wait() Returns

When wait() returns, it provides a list of the attached Condition objects that have a trigger_value of true. Your application can use this list to do the following for each Condition in the returned list:

If it is a StatusCondition:

First, call get_status_changes() to see what status changed.

If the status changes refer to plain communication status: call get_<communication_status>() on the relevant Entity.

If the status changes refer to DATA_ON_READERS1: call get_datareaders() on the relevant Subscriber.

If the status changes refer to DATA_AVAILABLE: call read() or take() on the relevant

DataReader.

If it is a ReadCondition or a QueryCondition: You may want to call read_w_condition() or take_w_condition() on the DataReader, with the ReadCondition as a parameter (see read_w_condition and take_w_condition (Section 7.4.3.6)).

1.And then read/take on the returned DataReader objects.

4-29

Note that this is just a suggestion, you do not have to use the “w_condition” operations (or any read/take operations, for that matter) simply because you used a WaitSet. The “w_condition” operations are just a convenient way to use the same status masks that were set on the ReadCondition or QueryCondition.

If it is a GuardCondition: check to see which GuardCondition changed, then react accordingly. Recall that GuardConditions are completely controlled by your application.

See Conditions and WaitSet Example (Section 4.6.5) to see how to determine which of the attached Conditions is in the returned list.

4.6.5Conditions and WaitSet Example

This example creates a WaitSet and then waits for one or more attached Conditions to become true.

// Create a WaitSet

WaitSet* waitset = new WaitSet();

// Attach Conditions DDSCondition* cond1 = ...;

DDSCondition* cond2 = entity->get_statuscondition(); DDSCondition* cond3 = reader->create_readcondition( DDS_NOT_READ_SAMPLE_STATE,

DDS_ANY_VIEW_STATE, DDS_ANY_INSTANCE_STATE);

DDSCondition* cond4 = new DDSGuardCondition();

DDSCondition* cond5 = ...;

DDS_ReturnCode_t retcode;

retcode = waitset->attach_condition(cond1); if (retcode != DDS_RETCODE_OK) {

// ... error

}

retcode = waitset->attach_condition(cond2); if (retcode != DDS_RETCODE_OK) {

// ... error

}

retcode = waitset->attach_condition(cond3); if (retcode != DDS_RETCODE_OK) {

// ... error

}

retcode = waitset->attach_condition(cond4); if (retcode != DDS_RETCODE_OK) {

// ... error

}

retcode = waitset->attach_condition(cond5); if (retcode != DDS_RETCODE_OK) {

// ... error

}

// Wait for a condition to trigger or timeout

DDS_Duration_t timeout = { 0, 1000000 }; // 1ms

DDSConditionSeq active_conditions; // holder for active conditions bool is_cond1_triggered = false;

bool is_cond2_triggered = false; DDS_ReturnCode_t retcode;

retcode = waitset->wait(active_conditions, timeout);

4-30

if (retcode == DDS_RETCODE_TIMEOUT) { // handle timeout

printf("Wait timed out. No conditions were triggered.\n");

}

else if (retcode != DDS_RETCODE_OK) {

//... check for cause of failure

}else {

//success

if (active_conditions.length() == 0) {

printf("Wait timed out!! No conditions triggered.\n");

}else

// check if "cond1" or "cond2" are triggered: for(i = 0; i < active_conditions.length(); ++i) {

if (active_conditions[i] == cond1) { printf("Cond1 was triggered!"); is_cond1_triggered = true;

}

if (active_conditions[i] == cond2) { printf("Cond2 was triggered!"); is_cond2_triggered = true;

}

if (is_cond1_triggered && is_cond2_triggered) { break;

}

}

}

}

if (is_cond1_triggered) {

// ... do something because "cond1" was triggered ...

}

if (is_cond2_triggered) {

// ... do something because "cond2" was triggered ...

}

//Delete the waitset delete waitset; waitset = NULL;

4.6.6GuardConditions

GuardConditions are created by your application. GuardConditions provide a way for your application to manually awaken a WaitSet. Like all Conditions, it has a single boolean trigger_value. Your application can manually trigger the GuardCondition by calling set_trigger_value().

Connext does not trigger or clear this type of condition—it is completely controlled by your application.

A GuardCondition has no factory. It is created as an object directly by the natural means in each language binding (e.g., using “new” in C++ or Java). For example:

//Create a Guard Condition

Condition* my_guard_condition = new GuardCondition();

// Delete a Guard Condition delete my_guard_condition;

4-31

When first created, the trigger_value is FALSE.

A GuardCondition has only two operations, get_trigger_value() and set_trigger_value().

When your application calls set_trigger_value(DDS_BOOLEAN_TRUE), Connext will awaken any WaitSet to which the GuardCondition is attached.

4.6.7ReadConditions and QueryConditions

ReadConditions are created by your application, but triggered by Connext. ReadConditions provide

a way for you to specify the data samples that you want to wait for, by indicating the desired sample-states, view-states, and instance-states1. Then Connext will trigger the ReadCondition when suitable samples are available.

A QueryCondition is a special ReadCondition that allows you to specify a query expression and parameters, so you can filter on the locally available (already received) data. QueryConditions use the same SQL-based filtering syntax as ContentFilteredTopics for query expressions, parameters, etc. Unlike ContentFilteredTopics, QueryConditions are applied to data already received, so they do not affect the reception of data.

Multiple mask combinations can be associated with a single content filter. This is important because the maximum number of content filters that may be created per DataReader is 32, but more than 32 QueryConditions may be created per DataReader, if they are different mask- combinations of the same content filter.

ReadConditions and QueryConditions are created by using the DataReader’s create_readcondition() and create_querycondition() operations. For example:

DDSReadCondition* my_read_condition = reader->create_readcondition( DDS_NOT_READ_SAMPLE_STATE, DDS_ANY_VIEW_STATE, DDS_ANY_INSTANCE_STATE);

DDSQueryCondition* my_query_condition = reader->create_querycondition( DDS_NOT_READ_SAMPLE_STATE, DDS_ANY_VIEW_STATE, DDS_ANY_INSTANCE_STATE query_expression, query_parameters);

Note: If you are using a ReadCondition to simply detect the presence of new data, consider using a StatusCondition (Section 4.6.8) with the DATA_AVAILABLE_STATUS instead, which will perform better in this situation.

A DataReader can have multiple attached ReadConditions and QueryConditions. A ReadCondition or QueryCondition may only be attached to one DataReader.

To delete a ReadCondition or QueryCondition, use the DataReader’s delete_readcondition() operation:

DDS_ReturnCode_t delete_readcondition (DDSReadCondition *condition)

After a ReadCondition is triggered, use the FooDataReader’s read/take “with condition” operations (see Section 7.4.3.6) to access the samples.

Table 4.8 lists the operations available on ReadConditions.

4.6.7.1How ReadConditions are Triggered

A ReadCondition has a trigger_value that determines whether the attached WaitSet is BLOCKED or UNBLOCKED. Unlike the StatusCondition, the trigger_value of the ReadCondition is tied to the

presence of at least one sample with a sample-state, view-state, and instance-state that matches those set in the ReadCondition. Furthermore, for the QueryCondition to have a

1. These states are described in The SampleInfo Structure (Section 7.4.6).

4-32

Table 4.8 ReadCondition and QueryCondition Operations

Operation

 

 

Description

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

get_datareader

Returns the

DataReader

to which

the ReadCondition

or

QueryCondition is

attached.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Returns the instance states that were specified when the ReadCondition or

get_instance_state_mask

QueryCondition was created. These are the sample’s instance states that Connext

 

checks to determine whether or not to trigger the ReadCondition or

 

QueryCondition .

 

 

 

 

 

 

 

 

Returns the sample-states that were specified when the ReadCondition or

get_sample_state_mask

QueryCondition was created. These are the sample states that Connext checks to

 

determine whether or not to trigger the ReadCondition or QueryCondition.

 

 

 

 

 

 

 

Returns the view-states

that were specified when the

ReadCondition

or

get_view_state_mask

QueryCondition was created. These are the view states that Connext checks to

 

determine whether or not to trigger the ReadCondition or QueryCondition.

 

 

 

 

 

 

 

 

 

trigger_value==TRUE,

the data

associated

with the

sample must

be

such that

the

query_expression evaluates to TRUE.

The trigger_value of a ReadCondition depends on the presence of samples on the associated DataReader. This implies that a single ‘take’ operation can potentially change the trigger_value of several ReadConditions or QueryConditions. For example, if all samples are taken, any

ReadConditions and QueryConditions associated with the DataReader that had trigger_value==TRUE before will see the trigger_value change to FALSE. Note that this does not guarantee that WaitSet objects that were separately attached to those conditions will not be awakened. Once we have trigger_value==TRUE on a condition, it may wake up the attached WaitSet, the condition transitioning to trigger_value==FALSE does not necessarily 'unwakeup' the WaitSet, since 'unwakening' may not be possible. The consequence is that an application blocked on a WaitSet may return from wait() with a list of conditions, some of which are no longer “active.” This is unavoidable if multiple threads are concurrently waiting on separate WaitSet objects and taking data associated with the same DataReader.

Consider the following example: A ReadCondition that has a sample_state_mask = {NOT_READ} will have a trigger_value of TRUE whenever a new sample arrives and will transition to FALSE as soon as all the newly arrived samples are either read (so their status changes to READ) or taken (so they are no longer managed by Connext). However, if the same ReadCondition had a sample_state_mask = {READ, NOT_READ}, then the trigger_value would only become FALSE once all the newly arrived samples are taken (it is not sufficient to just read them, since that would only change the SampleState to READ), which overlaps the mask on the

ReadCondition.

4.6.7.2QueryConditions

A QueryCondition is a special ReadCondition that allows your application to also specify a filter on the locally available data.

The query expression is similar to a SQL WHERE clause and can be parameterized by arguments that are dynamically changeable by the set_query_parameters() operation.

QueryConditions are triggered in the same manner as ReadConditions, with the additional requirement that the sample must also satisfy the conditions of the content filter associated with the QueryCondition.

4.6.8StatusConditions

StatusConditions are created automatically by Connext, one for each Entity. Connext will trigger the StatusCondition when there is a change to any of that Entity’s enabled statuses.

By default, when Connext creates a StatusCondition, all status bits are turned on, which means it will check for all statuses to determine when to trigger the StatusCondition. If you only want

4-33

Table 4.9 QueryCondition Operations

Operation

Description

 

 

 

 

get_query_expression

Returns the query expression specified when the QueryCondition was created.

 

 

 

Returns the query parameters associated with the QueryCondition. That is, the

get_query_parameters

parameters specified on the last successful call to set_query_parameters(), or if

set_query_parameters() was never called, the arguments specified when the

 

 

QueryCondition was created.

 

 

set_query_parameters

Changes the query parameters associated with the QueryCondition.

 

 

Connext to check for specific statuses, you can use the StatusCondition’s set_enabled_statuses() operation and set just the desired status bits.

The trigger_value of the StatusCondition depends on the communication status of the Entity (e.g., arrival of data, loss of information, etc.), ‘filtered’ by the set of enabled statuses on the

StatusCondition.

The set of enabled statuses and its relation to Listeners and WaitSets is detailed in How StatusConditions are Triggered (Section 4.6.8.1).

Table 4.10 lists the operations available on StatusConditions.

Table 4.10 StatusCondition Operations

Operation

Description

 

 

 

Defines the list of communication statuses that are taken into account to

 

determine the trigger_value of the StatusCondition. This operation may change the

 

trigger_value of the StatusCondition.

set_enabled_statuses

WaitSets behavior depend on the changes of the trigger_value of their attached

conditions. Therefore, any WaitSet to which the StatusCondition is attached is

 

 

potentially affected by this operation.

 

If this function is not invoked, the default list of enabled statuses includes all the

 

statuses.

 

 

 

Retrieves the list of communication statuses that are taken into account to

get_enabled_statuses

determine the trigger_value of the StatusCondition. This operation returns the

statuses that were explicitly set on the last call to set_enabled_statuses() or, if

 

 

set_enabled_statuses() was never called, the default list

 

 

get_entity

Returns the Entity associated with the StatusCondition. Note that there is exactly

one Entity associated with each StatusCondition.

 

 

 

Unlike other types of Conditions, StatusConditions are created by Connext, not by your application. To access an Entity’s StatusCondition, use the Entity’s get_statuscondition() operation. For example:

Condition* my_status_condition = entity->get_statuscondition();

After a StatusCondition is triggered, call the Entity’s get_status_changes() operation to see which status(es) changed.

4.6.8.1How StatusConditions are Triggered

The trigger_value of a StatusCondition is the boolean OR of the ChangedStatusFlag of all the communication statuses to which it is sensitive. That is, trigger_value==FALSE only if all the values of the ChangedStatusFlags are FALSE.

The sensitivity of the StatusCondition to a particular communication status is controlled by the list of enabled_statuses set on the Condition by means of the set_enabled_statuses() operation.

4-34

4.6.9Using Both Listeners and WaitSets

You can use Listeners and WaitSets in the same application. For example, you may want to use WaitSets and Conditions to access the data, and Listeners to be warned asynchronously of erroneous communication statuses.

We recommend that you choose one or the other mechanism for each particular communication status (not both). However, if both are enabled, the Listener mechanism is used first, then the WaitSet objects are signaled.

4-35

Chapter 5 Topics

For a DataWriter and DataReader to communicate, they need to use the same Topic. A Topic includes a name and an association with a user data type that has been registered with Connext. Topic names are how different parts of the communication system find each other. Topics are named streams of data of the same data type. DataWriters publish samples into the stream; DataReaders subscribe to data from the stream. More than one Topic can use the same user data type, but each Topic needs a unique name.

Topics, DataWriters, and DataReaders relate to each other as follows:

Multiple Topics (each with a unique name) can use the same user data type.

Applications may have multiple DataWriters for each Topic.

Applications may have multiple DataReaders for each Topic.

DataWriters and DataReaders must be associated with the same Topic in order for them to be connected.

Topics are created and deleted by a DomainParticipant, and as such, are owned by that DomainParticipant. When two applications (DomainParticipants) want to use the same Topic, they must both create the Topic (even if the applications are on the same node).

This chapter includes the following sections:

Topics (Section 5.1)

Topic QosPolicies (Section 5.2)

Status Indicator for Topics (Section 5.3)

ContentFilteredTopics (Section 5.4)

Builtin Topics: Connext uses ‘Builtin Topics’ to discover and keep track of remote entities, such as new participants in the domain. Builtin Topics are discussed in Chapter 16.

5.1Topics

Before you can create a Topic, you need a user data type (see Chapter 3) and a DomainParticipant (Section 8.3). The user data type must be registered with the DomainParticipant (as we saw in the User Data Types chapter in Section 3.8.5.1).

Once you have created a Topic, what do you do with it? Topics are primarily used as parameters in other Entities’ operations. For instance, a Topic is required when a Publisher or Subscriber creates a DataWriter or DataReader, respectively. Topics do have a few operations of their own, as

5-1

listed in Table 5.1. For details on using these operations, see the reference section or the API Reference HTML documentation.

Figure 5.1 Topic Module

Note: MultiTopics are not supported.

Table 5.1 Topic Operations

Purpose

Operation

Description

Reference

 

 

 

 

 

enable

Enables the Topic.

Section 4.1.2

 

 

 

 

 

get_qos

Gets the Topic’s current QosPolicy settings. This is most

 

 

often used in preparation for calling set_qos().

 

 

 

 

 

 

 

 

 

 

Sets the Topic’s QoS. You can use this operation to change

 

 

set_qos

the values for the Topic’s QosPolicies. Note, however,

Section 5.1.3

 

that not all QosPolicies can be changed after the Topic has

 

 

been created.

 

 

 

 

 

Configuring

set_qos_with_

Sets the Topic’s QoS based on a specified QoS profile.

 

the Topic

profile

 

 

get_listener

Gets the currently installed Listener.

 

 

 

 

 

 

 

 

 

Sets the Topic’s Listener. If you create the Topic without a

Section 5.1.5

 

set_listener

Listener, you can use this operation to add one later.

 

Setting the listener to NULL will remove the listener

 

 

 

 

 

 

from the Topic.

 

 

 

 

 

 

 

A type-safe way to cast a pointer. This takes a

 

 

narrow

DDSTopicDescription pointer and ‘narrows’ it to a

Section 6.3.7

 

 

DDSTopic pointer.

 

 

 

 

 

5-2

Table 5.1 Topic Operations

Purpose

Operation

Description

Reference

 

 

 

 

 

 

 

 

 

get_inconsistent_

Allows an application to retrieve a Topic’s

Section 5.3.1

Checking

topic_status

INCONSISTENT_TOPIC_STATUS status.

 

 

Gets a list of statuses that have changed since the last

 

Status

 

 

get_status_changes

time the application read the status or the listeners were

Section 4.1.4

 

 

 

called.

 

 

 

 

 

Navigating

get_name

Gets the topic_name string used to create the Topic.

Section 5.1.1

 

 

Relationship

get_type_name

Gets the type_name used to create the Topic.

 

s

 

 

 

get_participant

Gets the DomainParticipant to which this Topic belongs.

Section 5.1.6.1

 

 

 

 

 

5.1.1Creating Topics

Topics are created using the DomainParticipant’s create_topic() or create_topic_with_profile() operation:

DDSTopic * create_topic (const char *topic_name, const char *type_name, const DDS_TopicQos &qos,

DDSTopicListener *listener, DDS_StatusMask mask)

DDSTopic * create_topic_with_profile (

const char *topic_name, const char *type_name, const char *library_name, const char *profile_name,

DDSTopicListener *listener, DDS_StatusMask mask)

A QoS profile is way to use QoS settings from an XML file or string. With this approach, you can change QoS settings without recompiling the application. For details, see Chapter 17: Configuring QoS with XML.

topic_name Name for the new Topic, must not exceed 255 characters.

type_name Name for the user data type, must not exceed 255 characters. It must be the same name that was used to register the type, and the type must be registered with the same DomainParticipant used to create this Topic. See Section 3.6.

qos

If you want to use the default QoS settings (described in the API Reference HTML

 

documentation), use DDS_TOPIC_QOS_DEFAULT for this parameter (see

 

Figure 5.2). If you want to customize any of the QosPolicies, supply a QoS

 

structure (see Section 5.1.3).

 

 

 

If you use DDS_TOPIC_QOS_DEFAULT, it is not safe to create the topic while

 

another

thread may

be

simultaneously calling

the DomainParticipant’s

 

set_default_topic_qos() operation.

 

listener

Listeners are callback routines. Connext uses them to notify your application of

 

specific events (status changes) that may occur with respect to the Topic. The

 

listener parameter may be set to NULL if you do not want to install a Listener. If

 

you use NULL, the Listener of the DomainParticipant to which the Topic belongs

 

will be used instead (if it is set). For more information on TopicListeners, see

 

Section 5.1.5.

 

 

 

mask

This bit-mask indicates which status changes will cause the Listener to be invoked.

 

The bits in the mask that are set must have corresponding callbacks implemented

 

in the

Listener.

If

you use NULL for

the Listener, use

 

DDS_STATUS_MASK_NONE for this parameter. If the Listener implements all

5-3

callbacks, use DDS_STATUS_MASK_ALL. For information on statuses, see Listeners (Section 4.4).

library_name A QoS Library is a named set of QoS profiles. See QoS Libraries (Section 17.10). If NULL is used for library_name, the DomainParticipant’s default library is assumed.

profile_name A QoS profile groups a set of related QoS, usually one per entity. See QoS Profiles (Section 17.9). If NULL is used for profile_name, the DomainParticipant’s default profile is assumed and library_name is ignored.

Note: It is not safe to create a topic while another thread is calling lookup_topicdescription() for that same topic (see Section 8.3.7).

Figure 5.2 Creating a Topic with Default QosPolicies

const char *type_name = NULL;

// register the type

type_name = FooTypeSupport::get_type_name();

retcode = FooTypeSupport::register_type(participant, type_name); if (retcode != DDS_RETCODE_OK) {

// handle error

}

// create the topic

DDSTopic* topic = participant->create_topic("Example Foo", type_name, DDS_TOPIC_QOS_DEFAULT, NULL, DDS_STATUS_MASK_NONE);

if (topic == NULL) {

// process error here

};

For more examples, see Configuring QoS Settings when the Topic is Created (Section 5.1.3.1).

5.1.2Deleting Topics

To delete a Topic, use the DomainParticipant’s delete_topic() operation:

DDS_ReturnCode_t delete_topic (DDSTopic * topic)

Note, however, that you cannot delete a Topic if there are any existing DataReaders or DataWriters (belonging to the same DomainParticipant) that are still using it. All DataReaders and DataWriters associated with the Topic must be deleted first.

5.1.3Setting Topic QosPolicies

A Topic’s QosPolicies control its behavior, or more specifically, the behavior of the DataWriters and DataReaders of the Topic. You can think of the policies as the ‘properties’ for the Topic. The DDS_TopicQos structure has the following format:

DDS_TopicQos struct {

 

DDS_TopicDataQosPolicy

topic_data;

DDS_DurabilityQosPolicy

durability;

DDS_DurabilityServiceQosPolicy

durability_service;

DDS_DeadlineQosPolicy

deadline;

DDS_LatencyBudgetQosPolicy

latency_budget;

DDS_LivelinessQosPolicy

liveliness;

DDS_ReliabilityQosPolicy

reliability;

DDS_DestinationOrderQosPolicy

destination_order;

DDS_HistoryQosPolicy

history;

DDS_ResourceLimitsQosPolicy

resource_limits;

DDS_TransportPriorityQosPolicy

transport_priority;

DDS_LifespanQosPolicy

lifespan;

5-4

DDS_OwnershipQosPolicy ownership; } DDS_TopicQos;

Table 5.2 summarizes the meaning of each policy (arranged alphabetically). For information on why you would want to change a particular QosPolicy, see the section noted in the Reference column. For defaults and valid ranges, please refer to the API Reference HTML documentation for each policy.

Table 5.2 Topic QosPolicies

QosPolicy

Description

 

 

 

For a DataReader, specifies the maximum expected elapsed time between arriving

 

data samples.

Deadline

For a DataWriter, specifies a commitment to publish samples with no greater

 

elapsed time between them.

 

See Section 6.5.5.

 

 

 

Controls how Connext will deal with data sent by multiple DataWriters for the

DestinationOrder

same topic. Can be set to "by reception timestamp" or to "by source timestamp".

 

See Section 6.5.6.

Durability

Specifies whether or not Connext will store and deliver data that were previously

published to new DataReaders. See Section 6.5.7.

 

 

 

DurabilityService

Various settings to configure the external Persistence Service used by Connext for

DataWriters with a Durability QoS setting of Persistent Durability. See Section 6.5.8.

 

 

 

Specifies how much data must to stored by Connext for the DataWriter or

History

DataReader. This QosPolicy affects the RELIABILITY QosPolicy (Section 6.5.19) as

 

well as the DURABILITY QosPolicy (Section 6.5.7). See Section 6.5.10.

 

 

LatencyBudget

Suggestion to Connext on how much time is allowed to deliver data. See

Section 6.5.11.

 

 

 

Lifespan

Specifies how long Connext should consider data sent by an user application to be

valid. See Section 6.5.12.

 

 

 

Liveliness

Specifies and configures the mechanism that allows DataReaders to detect when

DataWriters become disconnected or "dead." See Section 6.5.13.

 

 

 

Ownership

Along with Ownership Strength, specifies if DataReaders for a topic can receive

data from multiple DataWriters at the same time. See Section 6.5.15.

 

 

 

Reliability

Specifies whether or not Connext will deliver data reliably. See Section 6.5.19.

 

 

 

Controls the amount of physical memory allocated for entities, if dynamic

ResourceLimits

allocations are allowed, and how they occur. Also controls memory usage among

 

different instance values for keyed topics. See Section 6.5.20.

 

 

TopicData

Along with Group Data QosPolicy and User Data QosPolicy, used to attach a

buffer of bytes to Connext's discovery meta-data. See Section 5.2.1.

 

 

 

TransportPriority

Set by a DataWriter to tell Connext that the data being sent is a different "priority"

than other data. See Section 6.5.21.

 

 

 

5.1.3.1Configuring QoS Settings when the Topic is Created

As described in Creating Topics (Section 5.1.1), there are different ways to create a Topic, depending on how you want to specify its QoS (with or without a QoS profile).

In Figure 5.2 on page 5-4, we saw an example of how to create a Topic with default QosPolicies by using the special constant, DDS_TOPIC_QOS_DEFAULT, which indicates that the default QoS values for a Topic should be used. The default Topic QoS values are configured in the DomainParticipant; you can change them with the

DomainParticipant’s set_default_topic_qos() or set_default_topic_qos_with_profile() operations (see Section 8.3.6.4).

5-5

To create a Topic with non-default QoS values, without using a QoS profile, use the

DomainParticipant’s get_default_topic_qos() operation to initialize a DDS_TopicQos structure. Then change the policies from their default values before passing the QoS structure to create_topic().

You can also create a Topic and specify its QoS settings via a QoS profile. To do so, call create_topic_with_profile().

If you want to use a QoS profile, but then make some changes to the QoS before creating the Topic, call get_topic_qos_from_profile(), modify the QoS and use the modified QoS when calling create_topic().

5.1.3.2Changing QoS Settings After the Topic Has Been Created

There are 2 ways to change an existing Topic’s QoS after it is has been created—again depending on whether or not you are using a QoS Profile.

To change QoS programmatically (that is, without using a QoS Profile), see the example code in Figure 5.3 on page 5-6. It retrieves the current values by calling the Topic’s get_qos() operation. Then it modifies the value and calls set_qos() to apply the new value. Note, however, that some QosPolicies cannot be changed after the Topic has been enabled—this restriction is noted in the descriptions of the individual QosPolicies.

You can also change a Topic’s (and all other Entities’) QoS by using a QoS Profile. For an example, see Figure 5.4 on page 5-6. For more information, see Chapter 17: Configuring QoS with XML.

Figure 5.3 Changing the QoS of an Existing Topic (without a QoS Profile)

DDS_TopicQos topic_qos;1

// Get current QoS. topic points to an existing DDSTopic. if (topic->get_qos(topic_qos) != DDS_RETCODE_OK) {

// handle error

}

//Next, make changes.

//New ownership kind will be Exclusive

topic_qos.ownership.kind = DDS_EXCLUSIVE_OWNERSHIP_QOS;

// Set the new QoS

if (topic->set_qos(topic_qos) != DDS_RETCODE_OK ) { // handle error

}

1.For the C API, you need to use DDS_TopicQos_INITIALIZER or DDS_TopicQos_initialize(). See Spe- cial QosPolicy Handling Considerations for C (Section 4.2.2)

Figure 5.4 Changing the QoS of an Existing Topic with a QoS Profile

retcode = topic->set_qos_with_profile(

“FooProfileLibrary”,”FooProfile”);

if (retcode != DDS_RETCODE_OK) { // handle error

}

5-6

5.1.4Copying QoS From a Topic to a DataWriter or DataReader

Only the TOPIC_DATA QosPolicy strictly applies to Topics—it is described in this chapter, while the others are described in the sections noted in the Reference column of Table 5.2. The rest of the QosPolicies for a Topic can also be set on the corresponding DataWriters and/or DataReaders. Actually, the values that Connext uses for those policies are taken directly from those set on the DataWriters and DataReaders. The values for those policies are stored only for reference in the

DDS_TopicQos structure.

Because many QosPolicies affect the behavior of matching DataWriters and DataReaders, the DDS_TopicQos structure is provided as a convenient way to set the values for those policies in a single place in the application. Otherwise, you would have to modify the individual QosPolicies within separate DataWriter and DataReader QoS structures. And because some QosPolicies are compared between DataReaders and DataWriters, you will need to make certain that the individual values that you set are compatible (see Section 4.2.1).

The use of the DDS_TopicQos structure to set the values of any QosPolicy except TOPIC_DATA—which only applies to Topics—is really a way to share a single set of values with the associated DataWriters and DataReaders, as well as to avoid creating those entities with inconsistent QosPolicies.

To cause a DataWriter to use its Topic’s QoS settings, either:

Pass DDS_DATAWRITER_QOS_USE_TOPIC_QOS to create_datawriter(), or

Call the Publisher’s copy_from_topic_qos() operation

To cause a DataReader to use its Topic’s QoS settings, either:

Pass DDS_DATAREADER_QOS_USE_TOPIC_QOS to create_datareader(), or

Call the Subscriber’s copy_from_topic_qos() operation

Please refer to the API Reference HTML documentation for the Publisher’s create_datawriter() and Subscriber’s create_datareader() methods for more information about using values from the

Topic QosPolicies when creating DataWriters and DataReaders.

5.1.5Setting Up TopicListeners

When you create a Topic, you have the option of giving it a Listener. A TopicListener includes just one callback routine, on_inconsistent_topic(). If you create a TopicListener (either as part of the Topic creation call, or later with the set_listener() operation), Connext will invoke the TopicListener’s on_inconsistent_topic() method whenever it detects that another application has created a Topic with same name but associated with a different user data type. For more information, see INCONSISTENT_TOPIC Status (Section 5.3.1).

Note: Some operations cannot be used within a listener callback, see Restricted Operations in Listener Callbacks (Section 4.5.1).

If a Topic’s Listener has not been set and Connext detects an inconsistent Topic, the DomainParticipantListener (if it exists) will be notified instead (see Section 8.3.5). So you only need to set up a TopicListener if you need to perform specific actions when there is an error on that particular Topic. In most cases, you can set the TopicListener to NULL and process inconsistent-topic errors in the DomainParticipantListener instead.

5.1.6Navigating Relationships Among Entities

5.1.6.1Finding a Topic’s DomainParticipant

To retrieve a handle to the Topic’s DomainParticipant, use the get_participant() operation:

DDSDomainParticipant*DDSTopicDescription::get_participant()

5-7

Notice that this method belongs to the DDSTopicDescription class, which is the base class for

DDSTopic.

5.1.6.2Retrieving a Topic’s Name or Type Name

If you want to retrieve the topic_name or type_name used in the create_topic() operation, use these methods:

const char* DDSTopicDescription::get_type_name(); const char* DDSTopicDescription::get_name();

Notice that these methods belong to the DDSTopicDescription class, which is the base class for

DDSTopic.

5.2Topic QosPolicies

This section describes the only QosPolicy that strictly applies to Topics (and no other types of Entities)—the TOPIC_DATA QosPolicy. For a complete list of the QosPolicies that can be set for Topics, see Table 5.2 on page 5-5.

Most of the QosPolicies that can be set on a Topic can also be set on the corresponding DataWriter and/or DataReader. The Topic’s QosPolicy is essentially just a place to store QoS settings that you plan to share with multiple entities that use that Topic (see how in Section 5.1.3); they are not used otherwise and are not propagated on the wire.

5.2.1TOPIC_DATA QosPolicy

This QosPolicy provides an area where your application can store additional information related to the Topic. This information is passed between applications during discovery (see Chapter 14: Discovery) using builtin-topics (see Chapter 16: Built-In Topics). How this information is used will be up to user code. Connext does not do anything with the information stored as TOPIC_DATA except to pass it to other applications. Use cases are usually application-to- application identification, authentication, authorization, and encryption purposes.

The value of the TOPIC_DATA QosPolicy is sent to remote applications when they are first discovered, as well as when the Topic’s set_qos() method is called after changing the value of the TOPIC_DATA. User code can set listeners on the builtin DataReaders of the builtin Topics used by Connext to propagate discovery information. Methods in the builtin topic listeners will be called whenever new applications, DataReaders, and DataWriters are found. Within the user callback, you will have access to the TOPIC_DATA that was set for the associated Topic.

Currently, TOPIC_DATA of the associated Topic is only propagated with the information that declares a DataWriter or DataReader. Thus, you will need to access the value of TOPIC_DATA through DDS_PublicationBuiltinTopicData or DDS_SubscriptionBuiltinTopicData (see Chapter 16: Built-In Topics).

The structure for the TOPIC_DATA QosPolicy includes just one field, as seen in Table 5.3. The field is a sequence of octets that translates to a contiguous buffer of bytes whose contents and length is set by the user. The maximum size for the data are set in the DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4).

Table 5.3 DDS_TopicDataQosPolicy

Type

Field Name

Description

 

 

 

DDS_OctetSeq

value

default: empty

 

 

 

This policy is similar to the GROUP_DATA (Section 6.4.4) and USER_DATA (Section 6.5.25) policies that apply to other types of Entities.

5-8

5.2.1.1Example

One possible use of TOPIC_DATA is to send an associated XML schema that can be used to process the data stored in the associated user data structure of the Topic. The schema, which can be passed as a long sequence of characters, could be used by an XML parser to take samples of the data received for a Topic and convert them for updating some graphical user interface, web application or database.

5.2.1.2Properties

This QosPolicy can be modified at any time. A change in the QosPolicy will cause Connext to send packets containing the new TOPIC_DATA to all of the other applications in the domain.

Because Topics are created independently by the applications that use the Topic, there may be different instances of the same Topic (same topic name and data type) in different applications. The TOPIC_DATA for different instances of the same Topic may be set differently by different applications.

5.2.1.3Related QosPolicies

GROUP_DATA QosPolicy (Section 6.4.4)

USER_DATA QosPolicy (Section 6.5.25)

DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4)

5.2.1.4Applicable Entities

Topics (Section 5.1)

5.2.1.5System Resource Considerations

As mentioned earlier, the maximum size of the TOPIC_DATA is set in the topic_data_max_length field of the DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4). Because Connext will allocate memory based on this value, you should only increase this value if you need to. If your system does not use TOPIC_DATA, then you can set this value to 0 to save memory. Setting the value of the TOPIC_DATA QosPolicy to hold data longer than the value set in the topic_data_max_length field will result in failure and an INCONSISTENT_QOS_POLICY return code.

However, should you decide to change the maximum size of TOPIC_DATA, you must make certain that all applications in the domain have changed the value of topic_data_max_length to be the same. If two applications have different limits on the size of TOPIC_DATA, and one application sets the TOPIC_DATA QosPolicy to hold data that is greater than the maximum size set by another application, then the DataWriters and DataReaders of that Topic between the two applications will not connect. This is also true for the GROUP_DATA (Section 6.4.4) and USER_DATA (Section 6.5.25) QosPolicies.

5.3Status Indicator for Topics

There is only one communication status defined for a Topic, ON_INCONSISTENT_TOPIC. You can use the get_inconsistent_topic_status() operation to access the current value of the status or use a TopicListener to catch the change in the status as it occurs. See Section 4.4 for a general discussion on Listeners and Statuses.

5-9

5.3.1INCONSISTENT_TOPIC Status

In order for a DataReader and a DataWriter with the same Topic to communicate, their types must be consistent according to the DataReader’s type-consistency enforcement policy value, defined in its TYPE_CONSISTENCY_ENFORCEMENT QosPolicy (Section 7.6.6)). This status indicates that another DomainParticipant has created a Topic using the same name as the local Topic, but with an inconsistent type.

The status is a structure of type DDS_InconsistentTopicStatus, see Table 5.4. The total_count keeps track of the total number of (DataReader, DataWriter) pairs with topic names that match the Topic to which this status is attached, but whose types are inconsistent. The TopicListener’s on_inconsistent_topic() operation is invoked when this status changes (an inconsistent topic is found). You can also retrieve the current value by calling the Topic’s get_inconsistent_topic_status() operation.

The value of total_count_change reflects the number of inconsistent topics that were found since the last time get_inconsistent_topic_status() was called by user code or on_inconsistent_topic() was invoked by Connext.

Table 5.4 DDS_InconsistentTopicStatus Structure

Type

Field Name

Description

 

 

 

 

 

 

 

 

Total cumulative count of (DataReader, DataWriter) pairs whose topic

DDS_Long

total_count

names match the Topic to which this status is attached, but whose

 

 

types are inconsistent.

 

 

 

DDS_Long

total_count_change

The change in total_count since the last time this status was read.

 

 

 

5.4ContentFilteredTopics

A ContentFilteredTopic is a Topic with filtering properties. It makes it possible to subscribe to topics and at the same time specify that you are only interested in a subset of the Topic’s data.

For example, suppose you have a Topic that contains a temperature reading for a boiler, but you are only interested in temperatures outside the normal operating range. A ContentFilteredTopic can be used to limit the number of data samples a DataReader has to process and may also reduce the amount of data sent over the network.

This section includes the following:

Overview (Section 5.4.1)

Where Filtering is Applied—Publishing vs. Subscribing Side (Section 5.4.2)

Creating ContentFilteredTopics (Section 5.4.3)

Deleting ContentFilteredTopics (Section 5.4.4)

Using a ContentFilteredTopic (Section 5.4.5)

SQL Filter Expression Notation (Section 5.4.6)

STRINGMATCH Filter Expression Notation (Section 5.4.7)

Custom Content Filters (Section 5.4.8)

5.4.1Overview

A ContentFilteredTopic creates a relationship between a Topic, also called the related topic, and user-specified filtering properties. The filtering properties consist of an expression and a set of parameters.

5-10

The filter expression evaluates a logical expression on the Topic content. The filter expression is similar to the WHERE clause in a SQL expression.

The parameters are strings that give values to the 'parameters' in the filter expression. There must be one parameter string for each parameter in the filter expression.

A ContentFilteredTopic is a type of topic description, and can be used to create DataReaders. However, a ContentFilteredTopic is not an entity—it does not have QosPolicies or Listeners.

A ContentFilteredTopic relates to other entities in Connext as follows:

ContentFilteredTopics are used when creating DataReaders, not DataWriters.

Multiple DataReaders can be created with the same ContentFilteredTopic.

A ContentFilteredTopic belongs to (is created/deleted by) a DomainParticipant.

A ContentFilteredTopic and Topic must be in the same DomainParticipant.

A ContentFilteredTopic can only be related to a single Topic.

A Topic can be related to multiple ContentFilteredTopics.

A ContentFilteredTopic can have the same name as a Topic, but ContentFilteredTopics must have unique names within the same DomainParticipant.

A DataReader created with a ContentFilteredTopic will use the related Topic's QoS and

Listeners.

Changing filter parameters on a ContentFilteredTopic causes all DataReaders using the same ContentFilteredTopic to see the change.

A Topic cannot be deleted as long as at least one ContentFilteredTopic that has been created with it exists.

A ContentFilteredTopic cannot be deleted as long as at least one DataReader that has been created with the ContentFilteredTopic exists.

5.4.2Where Filtering is Applied—Publishing vs. Subscribing Side

Filtering may be performed on either side of the distributed application. (The DataWriter obtains the filter expression and parameters from the DataReader during discovery.)

Connext also supports network-switch filtering for multi-channel DataWriters (see Chapter 18: Multi-channel DataWriters).

A DataWriter will automatically filter data samples for a DataReader if all of the following are true; otherwise filtering is performed by the DataReader.

1.The DataWriter is filtering for no more than writer_resource_limits.max_remote_reader_filters DataReaders at the same time.

There is a resource-limit on the DataWriter called writer_resource_limits.max_remote_reader_filters (see DATA_WRITER_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 6.5.4)). This value can be from 0-32. 0 means do not filter any DataReader and 32 (default value) means filter up to 32 DataReaders.

If a DataWriter is filtering max_remote_reader_filters DataReaders at the same time and a new filtered DataReader is created, then the newly created DataReader (max_remote_reader_filters + 1) is not filtered. Even if one of the first (max_remote_reader_filters) DataReaders is deleted, that already created DataReader (max_remote_reader_filters + 1) will still not be filtered. However, any subsequently created DataReaders will be filtered as long as the number of DataReaders currently being filtered is not more than writer_resource_limits.max_remote_reader_filters.

2.The DataReader is not subscribing to data using multicast.

5-11

3.There are no more than 4 matching DataReaders in the same locator (see Peer Descriptor Format (Section 14.2.1)).

4.The DataWriter has infinite liveliness. (See LIVELINESS QosPolicy (Section 6.5.13).)

5.The DataWriter is not using an Asynchronous Publisher. (That is, the DataWriter’s PUBLISH_MODE QosPolicy (DDS Extension) (Section 6.5.18) kind is set to

DDS_SYNCHRONOUS_PUBLISHER_MODE_QOS.) See Note below.

6.If you are using a custom filter (not the default one), it must be registered in the

DomainParticipant of the DataWriter and the DataReader.

Notes:

Connext supports limited writer-side filtering if asynchronous publishing is enabled. The middleware will not send any sample to a destination if the sample is filtered out by all the DataReaders on that destination. However, if there is one DataReader to which the sample has to be sent, all the DataReaders on the destination will do reader side filtering for the incoming sample.

In addition to filtering new samples, a DataWriter can also be configured to filter previously written samples stored in the DataWriter’s queue for newly discovered DataReaders. To do so, use the refilter field in the DataWriter’s HISTORY QosPolicy (Section 6.5.10).

5.4.3Creating ContentFilteredTopics

To create a ContentFilteredTopic that uses the default SQL filter, use the DomainParticipant’s create_contentfilteredtopic() operation:

DDS_ContentFilteredTopic *create_contentfilteredtopic

(const

char

*

name,

const

DDS_Topic * related_topic,

const

char

*

filter_expression,

const

DDS_StringSeq & expression_parameters)

Or, to use a custom filter or the builtin STRINGMATCH filter (see Section 5.4.7), use the create_contentfilteredtopic_with_filter() variation:

DDS_ContentFilteredTopic *create_contentfilteredtopic_with_filter

(const

char

*

name,

DDSTopic

*

related_topic,

const

char

*

filter_expression,

const

DDS_StringSeq & expression_parameters,

const

char

*

filter_name =

 

DDS_SQLFILTER_NAME)

name

Name of the ContentFilteredTopic. Note that it is legal for a

 

ContentFilteredTopic to have the same name as a Topic in the same

 

DomainParticipant, but a ContentFilteredTopic cannot have the same name

 

as another ContentFilteredTopic in the same DomainParticipant. This

 

parameter cannot be NULL.

related_topic The related Topic to be filtered. The related topic must be in the same DomainParticipant as the ContentFilteredTopic. This parameter cannot be NULL. The same related topic can be used in many different ContentFilteredTopics.

filter_expression A logical expression on the contents on the Topic. If the expression evaluates to TRUE, a sample is received; otherwise it is discarded. This parameter cannot be NULL. Once a ContentFilteredTopic is created, its filter_expression cannot be changed. The notation for this expression depends on the filter that you are using (specified by the filter_name parameter). See SQL Filter Expression Notation (Section 5.4.6) and STRINGMATCH Filter Expression Notation (Section 5.4.7).

5-12

expression_parameters A string sequence of filter expression parameters. Each parameter corresponds to a positional argument in the filter expression: element 0

 

corresponds to positional argument 0, element 1 to positional argument 1,

 

and so forth.

 

 

 

 

 

 

 

 

The

expression_parameters

can

be

changed

with

 

set_expression_parameters()

 

 

 

 

(Section 5.4.5.2),

 

append_to_expression_parameter()

(Section 5.4.5.3)

and

 

remove_from_expression_parameter() (Section 5.4.5.4).

 

 

filter_name

Name of the content filter to use for filtering. The filter must have been

 

previously registered with the DomainParticipant (see Registering a Custom

 

Filter

(Section

5.4.8.2)).

 

There

are two

builtin

filters,

 

DDS_SQLFILTER_NAME1

 

(the

default

 

filter)

and

 

DDS_STRINGMATCHFILTER_NAME1—these

are

automatically

 

registered.

 

 

 

 

 

 

 

 

To

use

the

STRINGMATCH

 

filter,

call

 

create_contentfilteredtopic_with_filter()

 

 

 

with

 

"DDS_STRINGMATCHFILTER_NAME"

as

the

filter_name.

 

STRINGMATCH filter expressions have the syntax:

 

 

 

 

<field name> MATCH <string pattern> (see Section 5.4.7).

 

If you run rtiddsgen with -notypecode, then you must use the "with_filter" version with a custom filter instead—do not use the builtin SQL filter or the STRINGMATCH filter with the - notypecode option because they require type-codes. See rtiddsgen Command-Line Arguments (Section 3.6.1).

To summarize:

To use the builtin default SQL filter:

Do not use -notypecode when running rtiddsgen

Call create_contentfilteredtopic()

See SQL Filter Expression Notation (Section 5.4.6)

To use the builtin STRINGMATCH filter:

Do not use -notypecode when running rtiddsgen

Call create_contentfilteredtopic_with_filter(), setting the filter_name to

DDS_STRINGMATCHFILTER_NAME

See STRINGMATCH Filter Expression Notation (Section 5.4.7)

To use a custom filter:

call create_contentfilteredtopic_with_filter(), setting the filter_name to a registered custom filter

To use rtiddsgen with -notypecode:

call create_contentfilteredtopic_with_filter(), setting the filter_name to a registered custom filter

Note: Be careful with memory management of the string sequence in some of the ContentFilteredTopic APIs. See the String Support section in the API Reference HTML documentation (within the Infrastructure module) for details on sequences.

1.In the Java and C# APIs, you can access the names of the builtin filters by using DomainParticipant.SQLFILTER_NAME and DomainParticipant.STRINGMATCHFILTER_NAME.

5-13

5.4.4Deleting ContentFilteredTopics

To delete a ContentFilteredTopic, use the DomainParticipant’s delete_contentfilteredtopic() operation:

1.Make sure no DataReaders are using the ContentFilteredTopic. (If this is not true, the operation returns PRECONDITION_NOT_MET.)

2.Delete the ContentFilteredTopic by using the DomainParticipant’s delete_contentfilteredtopic() operation.

DDS_ReturnCode_t delete_contentfilteredtopic (DDSContentFilteredTopic * a_contentfilteredtopic)

5.4.5Using a ContentFilteredTopic

Once you’ve created a ContentFilteredTopic, you can use the operations listed in Table 5.5.

Table 5.5 ContentFilteredTopic Operations

Operation

Description

Reference

 

 

 

 

 

 

append_to_expression_parameter

Concatenates a string value to the input

Section 5.4.5.3

 

expression parameter

 

get_expression_parameters

Gets the expression parameters.

Section 5.4.5.1

 

 

 

get_filter_expression

Gets the expression.

Section 5.4.5.5

 

 

 

get_related_topic

Gets the related Topic.

Section 5.4.5.6

 

 

 

narrow

Casts a DDS_TopicDescription pointer to a

Section 5.4.5.7

 

ContentFilteredTopic pointer.

 

remove_from_expression_parameter

Removes a string value from the input expression

Section 5.4.5.4

 

parameter

 

set_expression_parameters

Changes the expression parameters.

Section 5.4.5.2

 

 

 

5.4.5.1Getting the Current Expression Parameters

To get the expression parameters, use the ContentFilteredTopic’s get_expression_parameters() operation:

DDS_ReturnCode_t get_expression_parameters

(struct DDS_StringSeq & parameters)

parameters The filter expression parameters.

The memory for the strings in this sequence is managed as described in the String Support section of the API Reference HTML documentation (within the Infrastructure module). In particular, be careful to avoid a situation in which Connext allocates a string on your behalf and you then reuse that string in such a way that Connext believes it to have more memory allocated to it than it actually does. This parameter cannot be NULL.

This operation gives you the expression parameters that were specified on the last successful call to set_expression_parameters() or, if that was never called, the parameters specified when the ContentFilteredTopic was created.

5.4.5.2Setting Expression Parameters

To change the expression parameters associated with a ContentFilteredTopic:

DDS_ReturnCode_t set_expression_parameters

(const struct DDS_StringSeq & parameters)

5-14

parameters The filter expression parameters. Each element in the parameter sequence corresponds to a positional parameter in the filter expression. When using the default DDS_SQLFILTER_NAME, parameter strings are automatically converted to the member type. For example, "4" is converted to the integer 4. This parameter cannot be NULL.

Note: The ContentFilteredTopic’s operations do not manage the sequences; you must ensure that the parameter sequences are valid. Please refer to the String Support section in the API Reference HTML documentation (within the Infrastructure module) for details on sequences.

5.4.5.3Appending a String to an Expression Parameter

To concatenate a string to an expression parameter, use the ContentFilteredTopic's append_to_expression_parameter() operation:

DDS_ReturnCode_t append_to_expression_parameter( const DDS_Long index, const char* value);

When using the STRINGMATCH filter, index must be 0.

This function is only intended to be used with the builtin SQL and STRINGMATCH filters. This function can be used in expression parameters associated with MATCH operators (see SQL Extension: Regular Expression Matching (Section 5.4.6.4)) to add a pattern to the match pattern list. For example, if filter_expression is:

symbol MATCH 'IBM'

Then append_to_expression_parameter(0, "MSFT") would generate the expression:

symbol MATCH 'IBM,MSFT'

5.4.5.4Removing a String from an Expression Parameter

To remove a string from an expression parameter use the ContentFilteredTopic's remove_from_expression_parameter() operation:

DDS_ReturnCode_t remove_from_expression_parameter( const DDS_Long index, const char* value)

When using the STRINGMATCH filter, index must be 0.

This function is only intended to be used with the builtin SQL and STRINGMATCH filters. It can be used in expression parameters associated with MATCH operators (see SQL Extension: Regular Expression Matching (Section 5.4.6.4)) to remove a pattern from the match pattern list. For example, if filter_expression is:

symbol MATCH 'IBM,MSFT'

Then remove_from_expression_parameter(0, "IBM") would generate the expression:

symbol MATCH 'MSFT'

5.4.5.5Getting the Filter Expression

To get the filter expression that was specified when the ContentFilteredTopic was created: const char* get_filter_expression ()

There is no corresponding set operation. The filter expression can only be set when the ContentFilteredTopic is created.

5.4.5.6Getting the Related Topic

To get the related topic that was specified when the ContentFilteredTopic was created:

DDS_Topic * get_related_topic ()

5-15

5.4.5.7‘Narrowing’ a ContentFilteredTopic to a TopicDescription

To safely cast a DDS_TopicDescription pointer to a ContentFilteredTopic pointer, use the ContentFilteredTopic’s narrow() operation:

DDS_TopicDescription* narrow ()

5.4.6SQL Filter Expression Notation

A SQL filter expression is similar to the WHERE clause in SQL. The SQL expression format provided by Connext also supports the MATCH operator as an extended operator (see Section 5.4.6.4).

The following sections provide more information:

SQL Grammar (Section 5.4.6.1)

Token Expressions (Section 5.4.6.2)

Type Compatibility in the Predicate (Section 5.4.6.3)

SQL Extension: Regular Expression Matching (Section 5.4.6.4)

Composite Members (Section 5.4.6.5)

Strings (Section 5.4.6.6)

Enumerations (Section 5.4.6.7)

Pointers (Section 5.4.6.8)

Arrays (Section 5.4.6.9)

Sequences (Section 5.4.6.10)

Example SQL Filter Expressions (Section 5.4.6.11)

5.4.6.1SQL Grammar

This section describes the subset of SQL syntax, in Backus–Naur Form (BNF), that you can use to form filter expressions.

The following notational conventions are used:

NonTerminals are typeset in italics.

'Terminals' are quoted and typeset in a fixed width font. They are written in upper case in most cases in the BNF-grammar below, but should be case insensitive.

TOKENS are typeset in bold.

The notation (element // ',') represents a non-empty, comma-separated list of elements.

Expression ::=

FilterExpression

|

TopicExpression

|

QueryExpression

.

 

FilterExpression

::=

Condition

TopicExpression

::=

SelectFrom { Where } ';'

QueryExpression

::= { Condition }{ 'ORDER BY' (FIELDNAME // ',') }

 

 

.

SelectFrom

::= 'SELECT' Aggregation 'FROM' Selection

 

.

 

Aggregation

::= '*'

 

|

(SubjectFieldSpec // ',')

 

.

 

SubjectFieldSpec

::= FIELDNAME

 

|

FIELDNAME 'AS' IDENTIFIER

5-16

 

 

| FIELDNAME IDENTIFIER

 

 

.

Selection

::=

TOPICNAME

 

|

TOPICNAME NaturalJoin JoinItem

 

.

 

JoinItem

::=

TOPICNAME

 

|

TOPICNAME NaturalJoin JoinItem

 

|

'(' TOPICNAME NaturalJoin JoinItem ')'

 

.

 

NaturalJoin ::=

'INNER JOIN'

 

|

'INNER NATURAL JOIN'

 

|

'NATURAL JOIN'

 

|

'NATURAL INNER JOIN'

 

.

 

Where

::=

'WHERE' Condition

 

.

 

Condition

::=

Predicate

 

|

Condition 'AND' Condition

 

|

Condition 'OR' Condition

 

|

'NOT' Condition

 

|

'(' Condition ')'

 

.

 

Predicate

::=

ComparisonPredicate

 

|

BetweenPredicate

 

.

 

ComparisonPredicate ::= ComparisonTerm RelOp ComparisonTerm

 

.

 

ComparisonTerm

::= FieldIdentifier

 

| Parameter

 

.

 

BetweenPredicate

::=

FieldIdentifier 'BETWEEN' Range

 

|

FieldIdentifier 'NOT BETWEEN' Range

 

.

 

FieldIdentifier

::= FIELDNAME

 

| IDENTIFIER

 

.

 

RelOp

::=

'=' | '>' | '>=' | '<' | '<=' | '<>' | 'LIKE' | 'MATCH'

 

.

 

Range

::=

Parameter 'AND' Parameter

 

.

 

Parameter

::=

INTEGERVALUE

 

|

CHARVALUE

 

|

FLOATVALUE

 

|

STRING

 

|

ENUMERATEDVALUE

 

|

BOOLEANVALUE

 

|

PARAMETER

 

.

 

Note: INNER JOIN, INNER NATURAL JOIN, NATURAL JOIN, and NATURAL INNER JOIN are all aliases, in the sense that they have the same semantics. They are all supported because they all are part of the SQL standard.

5.4.6.2Token Expressions

The syntax and meaning of the tokens used in SQL grammar is described as follows:

IDENTIFIER—An identifier for a FIELDNAME, defined as any series of characters 'a', ..., 'z', 'A', ..., 'Z', '0', ..., '9', '_' but may not start with a digit.

IDENTIFIER: LETTER (PART_LETTER)* where LETTER: [ "A"-"Z","_","a"-"z" ]

5-17

PART_LETTER: [ "A"-"Z","_","a"-"z","0"-"9" ]

FIELDNAME—A reference to a field in the data structure. A dot '.' is used to navigate through nested structures. The number of dots that may be used in a FIELDNAME is unlimited. The FIELDNAME can refer to fields at any depth in the data structure. The names of the field are those specified in the IDL definition of the corresponding structure, which may or may not match the fieldnames that appear on the language-specific (e.g., C/C++, Java) mapping of the structure. To reference the n+1 element in an array or sequence, use the notation '[n]', where n is a natural number (zero included). FIELDNAME must resolve to a primitive IDL type; that is either boolean, octet, (unsigned) short, (unsigned) long, (unsigned) long long, float double, char, wchar, string, wstring, or enum.

FIELDNAME: FieldNamePart ( "." FieldNamePart )* where FieldNamePart : IDENTIFIER ( "[" Index "]" )*

Index> : (["0"-"9"])+

| ["0x","0X"](["0"-"9", "A"-"F", "a"-"f"])+

Primitive IDL types referenced by FIELDNAME are treated as different types in Predicate according to the following table:

Predicate Data Type

IDL Type

 

 

 

 

BOOLEANVALUE

boolean

 

 

INTEGERVALUE

octet, (unsigned) short, (unsigned) long, (unsigned) long long

 

 

FLOATVALUE

float, double

 

 

CHARVALUE

char, wchar

 

 

STRING

string, wstring

 

 

ENUMERATEDVALUE

enum

 

 

TOPICNAME—An identifier for a topic, and is defined as any series of characters 'a', ..., 'z', 'A', ..., 'Z', '0', ..., '9', '_' but may not start with a digit.

TOPICNAME : IDENTIFIER

INTEGERVALUE—Any series of digits, optionally preceded by a plus or minus sign, representing a decimal integer value within the range of the system. A hexadecimal number is preceded by 0x and must be a valid hexadecimal expression.

INTEGERVALUE : (["+","-"])? (["0"-"9"])+ [("L","l")]? | (["+","-"])? ["0x","0X"](["0"-"9",

"A"-"F", "a"-"f"])+ [("L","l")]?

CHARVALUE—A single character enclosed between single quotes.

CHARVALUE : "'" (~["'"])? "'"

FLOATVALUE—Any series of digits, optionally preceded by a plus or minus sign and optionally including a floating point ('.'). A power-of-ten expression may be postfixed, which has the syntax en or En, where n is a number, optionally preceded by a plus or minus sign.

FLOATVALUE : (["+","-"])? (["0"-"9"])* (".")? (["0"-"9"])+ (EXPONENT)?

where EXPONENT: ["e","E"] (["+","-"])? (["0"-"9"])+

STRING—Any series of characters encapsulated in single quotes, except the single quote itself.

STRING : "'" (~["'"])* "'"

5-18

ENUMERATEDVALUE—A reference to a value declared within an enumeration. Enumerated values consist of the name of the enumeration label enclosed in single quotes. The name used for the enumeration label must correspond to the label names specified in the IDL definition of the enumeration.

ENUMERATEDVALUE : "'" ["A" - "Z", "a" - "z"] ["A" - "Z", "a" - "z", "_", "0" - "9"]* "'"

BOOLEANVALUE—Can either be 'TRUE' or 'FALSE', and is case insensitive.

BOOLEANVALUE : ["TRUE","FALSE"]

PARAMETER—Takes the form %n, where n represents a natural number (zero included) smaller than 100. It refers to the (n + 1)th argument in the given context. This argument can only be in primitive type value format. It cannot be a FIELDNAME.

PARAMETER : "%" (["0"-"9"])+

5.4.6.3Type Compatibility in the Predicate

As seen in Table 5.6, only certain combinations of type comparisons are valid in the Predicate.

Table 5.6 Valid Type Comparisons

 

BOOLEAN

INTEGER

FLOAT

CHAR

STRING

ENUMERATED

 

VALUE

VALUE

VALUE

VALUE

VALUE

 

 

 

 

 

 

 

 

 

 

 

 

 

 

BOOLEAN

YES

 

 

 

 

 

 

 

 

 

 

 

 

INTEGERVALUE

 

YES

YES

 

 

 

 

 

 

 

 

 

 

FLOATVALUE

 

YES

YES

 

 

 

 

 

 

 

 

 

 

CHARVALUE

 

 

 

YES

YES

YES

 

 

 

 

 

 

 

STRING

 

 

 

YES

YES a

YES

ENUMERATED

 

YES

 

YES b

YES b

YES c

VALUE

 

 

 

 

 

 

a.See Section 5.4.6.4.

b.Because of the formal notation of the Enumeration values, they are compatible with string and char literals, but they are not compatible with string or char variables, i.e., "MyEnum='EnumValue'" is correct, but "MyEnum=MyS- tring" is not allowed.

c.Only for same-type Enums.

5.4.6.4SQL Extension: Regular Expression Matching

The relational operator MATCH may only be used with string fields. The right-hand operator is a string pattern. A string pattern specifies a template that the left-hand field must match.

MATCH is case-sensitive. These characters have special meaning: ,/?*[]-^!\%

The pattern allows limited "wild card" matching under the rules in Table 5.7 on page 5-20.

The syntax is similar to the POSIX® fnmatch syntax1. The MATCH syntax is also similar to the 'subject' strings of TIBCO Rendezvous®. Some example expressions include:

"symbol MATCH 'NASDAQ/[A-G]*'"

"symbol MATCH 'NASDAQ/GOOG,NASDAQ/MSFT'"

5.4.6.5Composite Members

Any member can be used in the filter expression, with the following exceptions:

1.See http://www.opengroup.org/onlinepubs/000095399/functions/fnmatch.html.

5-19

Table 5.7 Wild Card Matching

Character

 

Meaning

 

 

 

 

 

 

,

 

A , separates a list of alternate patterns. The field string is matched if it matches

 

one or more of the patterns.

 

 

 

 

 

/

 

A / in the pattern string matches a / in the field string. It separates a sequence of

 

mandatory substrings.

 

 

 

 

 

?

 

A ? in the pattern string matches any single non-special characters in the field

 

string.

 

 

 

 

 

*

 

A * in the pattern string matches 0 or more non-special characters in field string.

 

 

 

%

 

This special character is used to designate filter expression parameters.

 

 

 

\

 

(Not supported) Escape character for special characters.

 

 

 

[charlist]

 

Matches any one of the characters in charlist.

 

 

 

[!charlist]

or

(Not supported) Matches any one of the characters not in charlist.

[^charlist]

 

 

[s-e]

 

Matches any character from s to e, inclusive.

 

 

[!s-e] or [^s-e]

(Not supported) Matches any character not in the interval s to e.

 

 

 

128-bit floating point numbers (long doubles) are not supported

bitfields are not supported

LIKE is not supported

Composite members are accessed using the familiar dot notation, such as "x.y.z > 5". For unions, the notation is special due to the nature of the IDL union type.

On the publishing side, you can access the union discriminator with myunion._d and the actual member with myunion._u.mymember. If you want to use a ContentFilteredTopic on the subscriber side and filter a sample with a top-level union, you can access the union discriminator directly with _d and the actual member with mymember in the filter expression.

5.4.6.6Strings

The filter expression and parameters can use IDL strings. String constants must appear between single quotation marks (').

For example:

"fish = 'salmon' "

Strings used as parameter values must contain the enclosing quotation marks (') within the parameter value; do not place the quotation marks within the expression statement. For example, the expression " symbol MATCH %0 " with parameter 0 set to " 'IBM' " is legal, whereas the expression " symbol MATCH '%0' " with parameter 0 set to " IBM " will not compile.

5.4.6.7Enumerations

A filter expression can use enumeration values, such as GREEN, instead of the numerical value. For example, if x is an enumeration of GREEN, YELLOW and RED, the following expressions are valid:

"x = 'GREEN'" "X < 'RED'"

5.4.6.8Pointers

Pointers can be used in filter expressions and are automatically dereferenced to the correct value.

For example:

5-20

struct Point { long x; long y;

};

struct Rectangle { Point *u_l; Point *l_r;

};

The following expression is valid on a Topic of type Rectangle:

"u_l.x > l_r.x"

5.4.6.9Arrays

Arrays are accessed with the familiar [] notation.

For example:

struct ArrayType { long value[255][5];

};

The following expression is valid on a Topic of type ArrayType:

"value[244][2] = 5"

In order to compare an array of bytes(octets in idl), instead of comparing each individual element of the array using [] notation, Connext provides a helper function, hex(). The hex() function can be used to represent an array of bytes (octets in IDL). To use the hex() function, use the notation &hex() and pass the byte array as a sequence of hexadecimal values.

For example:

&hex (07 08 09 0A 0B 0c 0D 0E 0F 10 11 12 13 14 15 16)

Here the leftmost-pair represents the byte and index 0.

Note: If the length of the octet array represented by the hex() function does not match the length of the field being compared, it will result in a compilation error.

For example:

struct ArrayType { octet value[2];

};

The following expression is valid:

"value = &hex(12 0A)"

5.4.6.10Sequences

Sequence elements can be accessed using the () or [] notation.

For example:

struct SequenceType { sequence<long> s;

};

The following expressions are valid on a Topic of type SequenceType:

"s(1) = 5" "s[1] = 5"

5-21

5.4.6.11Example SQL Filter Expressions

Assume that you have a Topic with two floats, X and Y, which are the coordinates of an object moving inside a rectangle measuring 200 x 200 units. This object moves quite a bit, generating lots of samples that you are not interested in. Instead you only want to receive samples outside the middle of the rectangle, as seen in Figure 5.5. That is, you want to filter out data points in the gray box.

Figure 5.5 Filtering Example

The filter expression would look like this (remember the expression is written so that samples that we do want will pass):

"(X < 50 or X > 150) and (Y < 50 or Y > 150)"

While this filter works, it cannot be changed after the ContentFilteredTopic has been created. Suppose you would like the ability to adjust the coordinates that are considered outside the acceptable range (changing the size of the gray box). You can achieve this by using filter parameters. An more flexible way to write the expression is this:

"(X < %0 or X > %1) and (Y < %2 or Y > %3)"

Recall that when you create a ContentFilteredTopic (see Section 5.4.3), you pass a expression_parameters string sequence as one of the parameters. Each element in the string sequence corresponds to one argument.

See the String and Sequence Support sections of the API Reference HTML documentation (from the Modules page, select Infrastructure).

In C++, the filter parameters could be assigned like this:

FilterParameter[0] = "50";

FilterParameter[1] = "150";

FilterParameter[2] = "50";

FilterParameter[3] = "150";

With these parameters, the filter expression is identical to the first approach. However, it is now possible to change the parameters by calling set_expression_parameters(). For example, perhaps you decide that you only want to see data points where X < 10 or X > 190. To make this change:

FilterParameter[0] = 10

FilterParameter[1] = 190 set_expression_parameters(....)

5-22

Note: The new filter parameters will affect all DataReaders that have been created with this ContentFilteredTopic.

5.4.7STRINGMATCH Filter Expression Notation

The STRINGMATCH Filter is a subset of the SQL filter; it only supports the MATCH relational operator on a single string field. It is introduced mainly for the use case of partitioning data according to channels in the DataWriter's MULTI_CHANNEL QosPolicy (DDS Extension) (Section 6.5.14) in Market Data applications.

A STRINGMATCH filter expression has the following syntax:

<field name> MATCH <string pattern>

The STRINGMATCH filter is provided to support the narrow use case of filtering a single string field of the sample against a comma-separated list of matching string values. It is intended to be used in conjunction with ContentFilteredTopic helper routines append_to_expression_parameter() (Section 5.4.5.3) and remove_from_expression_parameter() (Section 5.4.5.4), which allow you to easily append and remove individual string values from the comma-separated list of string values.

The STRINGMATCH filter must contain only one <field name>, and a single occurrence of the MATCH operator. The <string pattern> must be either the single parameter %0, or a single, comma-separated list of strings without intervening spaces.

During creation of a STRINGMATCH filter, the <string pattern> is automatically parameterized. That is, during creation, if the <string pattern> specified in the filter expression is not the parameter %0, then the comma-separated list of strings is copied to the initial contents of parameter 0 and the <string pattern> in the filter expression is replaced with the parameter %0.

The initial matching string list is converted to an explicit parameter value so that subsequent additions and deletions of string values to and from the list of matching strings may be performed with the append_to_expression_parameter() and remove_from_expression_parameter() operations mentioned above.

5.4.7.1Example STRINGMATCH Filter Expressions

This expression evaluates to TRUE if the value of symbol is equal to NASDAQ/MSFT: symbol MATCH 'NASDAQ/MSFT'

This expression evaluates to TRUE if the value of symbol is equal to NASDAQ/IBM or

NASDAQ/MSFT:

symbol MATCH 'NASDAQ/IBM,NASDAQ/MSFT'

This expression evaluates to TRUE if the value of symbol corresponds to NASDAQ and starts with a letter between M and Y:

symbol MATCH 'NASDAQ/[M-Y]*'

5.4.7.2STRINGMATCH Filter Expression Parameters

In the builtin STRINGMATCH filter, there is one, and only one, parameter: parameter 0. (If you want to add more parameters, see Appending a String to an Expression Parameter (Section 5.4.5.3).) The parameter can be specified explicitly using the same syntax as the SQL filter or implicitly by using a constant string pattern. For example:

symbol

MATCH

%0 (Explicit parameter)

symbol

MATCH

‘IBM’ (Implicit parameter initialized to IBM)

Strings used as parameter values must contain the enclosing quotation marks (') within the parameter value; do not place the quotation marks within the expression statement. For

5-23

example, the expression " symbol MATCH %0 " with parameter 0 set to " 'IBM' " is legal, whereas the expression " symbol MATCH '%0' " with parameter 0 set to " IBM " will not compile.

5.4.8Custom Content Filters

By default, a ContentFilteredTopic will use a SQL-like content filter, DDS_SQLFILTER_NAME (see SQL Filter Expression Notation (Section 5.4.6)), which implements a superset of the content filter. There is another builtin filter, DDS_STRINGMATCHFILTER_NAME (see STRINGMATCH Filter Expression Notation (Section 5.4.7)). Both of these are automatically registered.

If you want to use a different filter, you must register it first, then create the ContentFilteredTopic using create_contentfilteredtopic_with_filter() (see Creating ContentFilteredTopics (Section 5.4.3)).

One reason to use a custom filter is that the default filter can only filter based on relational operations between topic members, not on a computation involving topic members. For example, if you want to filter based on the sum of the members, you must create your own filter.

Notes:

The API for using a custom content filter is subject to change in a future release.

Custom content filters are not supported when using the .NET APIs.

5.4.8.1Filtering on the Writer Side with Custom Filters

There are two approaches for performing writer-side filtering. The first approach is to evaluate each written sample against filters of all the readers that have content filter specified and identify the readers whose filter passes the sample.

The second approach is to evaluate the written sample once for the writer and then rely on the filter implementation to provide a set of readers whose filter passes the sample. This approach allows the filter implementation to cache the result of filtering, if possible. For example, consider a scenario where the data is described by the struct shown below, where 10<x<20:

struct MyData { int x;

int y;

};

If the filter expression is based only on the x field, the filter implementation can maintain a hash map for all the different values of x and cache the filtering results in the hash map. Then any future evaluations will only be O(1), because it only requires a lookup in the hash map.

But if in the same example, a reader has a content filter that is based on both x and y, or just y, the filter implementation cannot cache the result—because the filter was only maintaining a hash map for x. In this case, the filter implementation can inform Connext that it will not be caching the result for those DataReaders. The filter can use DDS_ExpressionProperty to indicate to the middleware whether or not it will cache the results for DataReader. Table 5.8 describes DDS_ExpressionProperty.

Table 5.8 DDS_ExpressionProperty

Type

Field Name

Description

 

 

 

 

 

 

DDS_Boolean

key_only_filter

Indicates if the filter expression is based only on key fields. In this

case, Connext itself can cache the filtering results.

 

 

 

 

 

 

 

Indicates if the filter implementation can cache the filtering result for

 

writer_side_filter_

the expression provided. If this is true then Connext will do no

DDS_Boolean

caching or explicit filter evaluation for the associated DataReader. It

 

optimization

will instead rely on the filter implementation to provide appropriate

 

 

 

 

results.

 

 

 

5-24

5.4.8.2Registering a Custom Filter

To use a custom filter, it must be registered in the following places:

Register the custom filter in any subscribing application in which the filter is used to create a ContentFilteredTopic and corresponding DataReader.

In each publishing application, you only need to register the custom filter if you want to perform writer-side filtering. A DataWriter created with an associated filter will use that filter if it discovers a matched DataReader that uses the same filter.

For example, suppose Application A on the subscription side creates a Topic named X and a ContentFilteredTopic named filteredX (and a corresponding DataReader), using a previously registered content filter, myFilter. With only that, you will have filtering on the subscription side. If you also want to perform filtering in any application that publishes Topic X, then you also need to register the same definition of the ContentFilter myFilter in that application.

To register a new filter, use the DomainParticipant’s register_contentfilter() operation1:

DDS_ReturnCode_t register_contentfilter(const char * filter_name, const DDSContentFilter * contentfilter)

)

filter_name The name of the filter. The name must be unique within the DomainParticipant. The filter_name cannot have a length of 0. The same filtering functions and handle can be registered under different names.

content_filter This class specifies the functions that will be used to process the filter.

You must derive from the DDSContentFilter base class and implement the virtual compile, evaluate, and finalize functions described below.

Optionally, you can derive from the DDSWriterContentFilter base class instead, to implement additional filtering operations that will be used by the DataWriter. When performing writer-side filtering, these operations allow a sample to be evaluated once for the DataWriter, instead of evaluating the sample for every DataReader that is matched with the DataWriter. An instance of the derived class is then used as an argument when calling register_contentfilter().

compile

The function that will be used to compile a filter expression and parameters. Connext will call this function when a ContentFilteredTopic is created and when the filter parameters are changed. This parameter cannot be NULL. See Compile Function (Section 5.4.8.5). This is a member of DDSContentFil- ter and DDSWriterContentFilter.

evaluate

The function that will be called by Connext each time a sample is received. Its purpose is to evaluate the sample based on the filter. This parameter cannot be NULL. See Evaluate Function (Section 5.4.8.6). This is a member of DDSContentFilter and DDSWriterContentFilter.

finalize

The function that will be called by Connext when an instance of the custom content filter is no longer needed. This parameter may be NULL. See Final- ize Function (Section 5.4.8.7). This is a member of DDSContentFilter and DDSWriterContentFilter.

1. This operation is an extension to the DDS standard.

5-25

writer_attach

The function that will be used to create some state required to perform filter- ing on the writer side using the operations provided in DDSWriterContent- Filter. Connext will call this function for every DataWriter; it will be called only the first time the DataWriter matches a DataReader using the specified fil- ter. This function will not be called for any subsequent DataReaders that match the DataWriter and are using the same filter. See Writer Attach Func- tion (Section 5.4.8.8). This is a member of DDSWriterContentFilter.

writer_detach

The function that will be used to delete any state created using the writer_attach function. Connext will call this function when the DataWriter is deleted. See Writer Detach Function (Section 5.4.8.9). This is a member of DDSWriterContentFilter.

writer_compile

The function that will be used by the DataWriter to compile filter expression and parameters provided by the reader. Connext will call this function when the DataWriter discovers a DataReader with a ContentFilteredTopic or when a DataWriter is notified of a change in DataReader’s filter parameter. This func- tion will receive as an input a DDS_Cookie_t which uniquely identifies the DataReader for which the function was invoked. See Writer Compile Func- tion (Section 5.4.8.10). This is a member of DDSWriterContentFilter.

writer_evaluate

The function that will be called by Connext every time a DataWriter writes a new sample. Its purpose is to evaluate the sample for all the readers for which the DataWriter is performing writer-side filtering and return the list of DDS_Cookie_t associated with the DataReaders whose filter pass the sample. See Writer Evaluate Function (Section 5.4.8.11).

writer_return_loan

The function that will be called by Connext to return the loan on a sequence of DDS_Cookie_t provided by the writer_evaluate function. See Writer Return Loan Function (Section 5.4.8.12). This is a member of DDSWriterCon- tentFilter.

writer_finalize

The function that will be called by Connext to notify the filter implementa- tion that the DataWriter is no longer matching with a DataReader for which it was previously performing writer-side filtering. This will allow the filter to purge any state it was maintaining for the DataReader. See Writer Finalize Function (Section 5.4.8.13). This is a member of DDSWriterContentFilter.

5.4.8.3Unregistering a Custom Filter

To unregister a filter, use the DomainParticipant’s unregister_contentfilter() operation1, which is useful if you want to reuse a particular filter name. (Note: You do not have to unregister the filter before deleting the parent DomainParticipant. If you do not need to reuse the filter name to register another filter, there is no reason to unregister the filter.)

DDS_ReturnCode_t unregister_contentfilter(const char * filter_name)

filter_name The name of the previously registered filter. The name must be unique within the DomainParticipant. The filter_name cannot have a length of 0.

1. This operation is an extension to the DDS standard.

5-26

If you attempt to unregister a filter that is still being used by a ContentFilteredTopic, unregister_contentfilter() will return

PRECONDITION_NOT_MET.

If there are still existing discovered DataReaders with the same filter_name and the filter's compile function has previously been called on the discovered DataReaders, the filter’s finalize function will be called on those discovered DataReaders before the content filter is unregistered. This means filtering will be performed on the application that is creating the DataReader.

5.4.8.4Retrieving a ContentFilter

If you know the name of a ContentFilter, you can get a pointer to its structure. If the ContentFilter has not already been registered, this operation will return NULL.

DDS_ContentFilter *lookup_contentfilter (const char * filter_name)

5.4.8.5Compile Function

The compile function specified in the ContentFilter will be used to compile a filter expression and parameters. Please note that the term ‘compile’ is intentionally defined very broadly. It is entirely up to you, as the user, to decide what this function should do. The only requirement is that the error_code parameter passed to the compile function must return OK on successful execution. For example:

DDS_ReturnCode_t sample_compile_function(

void **

new_compile_data,

const char *

expression,

const DDS_StringSeq & parameters,

const DDS_TypeCode *

type_code,

const char *

type_class_name,

void *

old_compile_data)

{

*new_compile_data = (void*)DDS_String_dup(parameters[0]); return DDS_RETCODE_OK;

}

new_compile_dataA user-specified opaque pointer of this instance of the content filter. This value is passed to the evaluate and finalize functions.

expression

An ASCIIZ string with the filter expression the ContentFilteredTopic was

 

created with. Note that the memory used by the parameter pointer is

 

owned by Connext. If you want to manipulate this string, you must make

 

a copy of it first. Do not free the memory for this string.

parameters

A string sequence of expression parameters used to create the

 

ContentFilteredTopic. The string sequence is equal (but not identical) to

 

the string sequence passed to create_contentfilteredtopic() (see

 

expression_parameters in Section 5.4.3).

Important:

The sequence passed to the compile function is owned by Connext and

 

must not be referred to outside the compile function.

type_code

A pointer to the type code of the related Topic. A type code is a description

 

of the topic members, such as their type (long, octet, etc.), but does not

 

contain any information with respect to the memory layout of the

 

structures. The type code can be used to write filters that can be used with

 

any type. See Using Generated Types without Connext (Standalone)

 

(Section 3.7). [Note: If you are using the Java API, this parameter will

 

always be NULL.]

type_class_name Fully qualified class name of the related Topic.

5-27

old_compile_data The new_compile_data value from a previous call to this instance of a content filter. If compile is called more than once for an instance of a ContentFilteredTopic (such as if the expression parameters are changed), then the new_compile_data value returned by the previous invocation is passed in the old_compile_data parameter (which can be NULL). If this is a new instance of the filter, NULL is passed. This parameter is useful for freeing or reusing previously allocated resources.

5.4.8.6Evaluate Function

The evaluate function specified in the ContentFilter will be called each time a sample is received. This function’s purpose is to determine if a sample should be filtered out (not put in the receive queue).

For example:

DDS_Boolean sample_evaluate_function(

void* compile_data, const void* sample,

struct DDS_FilterSampleInfo * meta_data) {

char *parameter = (char*)compile_data; DDS_Long x;

Foo *foo_sample = (Foo*)sample;

sscanf(parameter,"%d",&x);

return (foo_sample->x > x ? DDS_BOOLEAN_FALSE : DDS_BOOLEAN_TRUE);

}

The function may use the following parameters:

compile_data The last return value from the compile function for this instance of the content filter. Can be NULL.

sample A pointer to a C structure with the data to filter. Note that the evaluate function always receives deserialized data.

meta_data A pointer to the meta data associated with the sample.

Note: Currently the meta_data field only supports related_sample_identity

(described in Table 6.15, “DDS_WriteParams_t,” on page 6-30).

5.4.8.7Finalize Function

The finalize function specified in the ContentFilter will be called when an instance of the custom content filter is no longer needed. When this function is called, it is safe to free all resources used by this particular instance of the custom content filter.

For example:

void sample_finalize_function ( void* compile_data) { /* free parameter string from compile function */ DDS_String_free((char *)compile_data);

}

The finalize function may use the following optional parameters:

system_key See Section 5.4.8.5.

handle This is the opaque returned by the last call to the compile function.

5-28

A pointer to DDS_ExpressionProperty. This is an output parameter. It allows you to indicate to Connext if a filter expression can be optimized (as described in Filtering on the Writer Side with Custom Filters (Section 5.4.8.1)).

5.4.8.8Writer Attach Function

The writer_attach function specified in the WriterContentFilter will be used to create some state that can be used by the filter to perform writer-side filtering more efficiently. It is entirely up to you, as the implementer of the filter, to decide if the filter requires this state.

The function has the following parameter:

writer_filter_dataA user-specified opaque pointer to some state created on the writer side that will help perform writer-side filtering efficiently.

5.4.8.9Writer Detach Function

The writer_detach function specified in the WriterContentFilter will be used to free up any state that was created using the writer_attach function.

The function has the following parameter:

writer_filter_dataA pointer to the state created using the writer_attach function.

5.4.8.10Writer Compile Function

The writer_compile function specified in the WriterContentFilter will be used by a DataWriter to compile a filter expression and parameters associated with a DataReader for which the DataWriter is performing filtering. The function will receive as input a DDS_Cookie_t that uniquely identifies the DataReader for which the function was invoked.

The function has the following parameters:

writer_filter_dataA pointer to the state created using the writer_attach function. prop

expression

An ASCIIZ string with the filter expression the ContentFilteredTopic was

 

created with. Note that the memory used by the parameter pointer is

 

owned by Connext. If you want to manipulate this string, you must make a

 

copy of it first. Do not free the memory for this string.

parameters

A string sequence of expression parameters used to create the

 

ContentFilteredTopic. The string sequence is equal (but not identical) to the

 

string sequence passed to create_contentfilteredtopic() (see

 

expression_parameters in Creating ContentFilteredTopics (Section 5.4.3)).

 

Important: The sequence passed to the compile function is owned by

 

Connext and must not be referred to outside the writer_compile function.

type_code

A pointer to the type code of the related Topic. A type code is a description

 

of the topic members, such as their type (long, octet, etc.), but does not

 

contain any information with respect to the memory layout of the

 

structures. The type code can be used to write filters that can be used with

 

any type. See Using Generated Types without Connext (Standalone)

 

(Section 3.7). [Note: If you are using the Java API, this parameter will

 

always be NULL.]

type_class_name

The fully qualified class name of the related Topic.

cookie

DDS_Cookie_t to uniquely identify the DataReader for which the

 

writer_compile function was called.

5.4.8.11Writer Evaluate Function

The writer_evaluate function specified in the WriterContentFilter will be used by a DataWriter to retrieve the list of DataReaders whose filter passed the sample. The writer_evaluate function

5-29

returns a sequence of cookies which identifies the set of DataReaders whose filter passes the sample.

The function has the following parameters:

writer_filter_data A pointer to the state created using the writer_attach function.

 

sample

A pointer to the data to be filtered. Note that the writer_evaluate function

 

always receives deserialized data.

 

 

 

 

meta_data

A pointer to the meta-data associated with the sample.

 

 

 

Note:

Currently

the

meta_data

field

only

supports

 

related_sample_identity (described in Table 6.15, “DDS_WriteParams_t,”

 

on page 6-30).

 

 

 

 

 

5.4.8.12Writer Return Loan Function

Connext uses the writer_return_loan function specified in the WriterContentFilter to indicate to the filter implementation that it has finished using the sequence of cookies returned by the filter’s writer_evaluate function. Your filter implementation should not free the memory associated with the cookie sequence before the writer_return_loan function is called.

The function has the following parameters:

writer_filter_data A pointer to the state created using the writer_attach function.

cookies

The sequence of cookies for which the writer_return_loan function was

 

called.

5.4.8.13Writer Finalize Function

The writer_finalize function specified in the WriterContentFilter will be called when the DataWriter no longer matches with a DataReader that was created with ContentFilteredTopic. This will allow the filter implementation to delete any state it was maintaining for the

DataReader.

The function has the following parameters:

writer_filter_data A pointer to the state created using the writer_attach function.

cookie

A DDS_Cookie_t to uniquely identify the DataReader for which the

 

writer_finalize was called.

5-30

Chapter 6 Sending Data

This chapter discusses how to create, configure, and use Publishers and DataWriters to send data. It describes how these entities interact, as well as the types of operations that are available for them.

This chapter includes the following sections:

Preview: Steps to Sending Data (Section 6.1)

Publishers (Section 6.2)

DataWriters (Section 6.3)

Publisher/Subscriber QosPolicies (Section 6.4)

DataWriter QosPolicies (Section 6.5)

FlowControllers (DDS Extension) (Section 6.6)

The goal of this chapter is to help you become familiar with the Entities you need for sending data. For up-to-date details such as formal parameters and return codes on any mentioned operations, please see the API Reference HTML documentation.

6.1Preview: Steps to Sending Data

To send samples of a data instance:

1.Create and configure the required Entities:

a.Create a DomainParticipant (see Section 8.3.1).

b.Register user data types1 with the DomainParticipant. For example, the ‘FooDataType’.

c.Use the DomainParticipant to create a Topic with the registered data type.

d.Optionally2, use the DomainParticipant to create a Publisher.

e.Use the Publisher or DomainParticipant to create a DataWriter for the Topic.

f.Use a type-safe method to cast the generic DataWriter created by the Publisher to a type-specific DataWriter. For example, ‘FooDataWriter.

1.Type registration is not required for built-in types (see Section 3.2.1).

2.You are not required to explicitly create a Publisher; instead, you can use the 'implicit Publisher' created from the DomainParticipant. See Creating Publishers Explicitly vs. Implicitly (Section 6.2.1).

6-1

g.Optionally, register data instances with the DataWriter. If the Topic’s user data type contain key fields, then registering a data instance (data with a specific key value) will improve performance when repeatedly sending data with the same key. You may register many different data instances; each registration will return an instance handle corresponding to the specific key value. For non-keyed data types, instance registration has no effect. See Section 2.2.2 for more information on keyed data types and instances.

2.Every time there is changed data to be published:

a.Store the data in a variable of the correct data type (for instance, variable ‘Foo’ of the type ‘FooDataType’).

b.Call the FooDataWriters write() operation, passing it a reference to the variable ‘Foo’. For non-keyed data types or for non-registered instances, also pass in

DDS_HANDLE_NIL.

For keyed data types, you should pass in the instance handle corresponding to the instance stored in ‘Foo’, if you have registered the instance previously. This means that the data stored in ‘Foo’ has the same key value that was used to create instance handle.

c.The write() function will take a snapshot of the contents of ‘Foo’ and store it in Connext internal buffers from where the data sample is sent under the criteria set by the Publisher’s and DataWriter’s QosPolicies. If there are matched DataReaders, then the data sample will have been passed to the physical transport plug-in/device driver by the time that write() returns.

6.2Publishers

An application that intends to publish information needs the following Entities: DomainParticipant, Topic, Publisher, and DataWriter. All Entities have a corresponding specialized Listener and a set of QosPolicies. A Listener is how Connext notifies your application of status changes relevant to the Entity. The QosPolicies allow your application to configure the behavior and resources of the Entity.

A DomainParticipant defines the domain in which the information will be made available.

A Topic defines the name under which the data will be published, as well as the type (format) of the data itself.

An application writes data using a DataWriter. The DataWriter is bound at creation time to a Topic, thus specifying the name under which the DataWriter will publish the data and the type associated with the data. The application uses the DataWriter’s write() operation to indicate that a new value of the data is available for dissemination.

A Publisher manages the activities of several DataWriters. The Publisher determines when the data is actually sent to other applications. Depending on the settings of various QosPolicies of the Publisher and DataWriter, data may be buffered to be sent with the data of other DataWriters or not sent at all. By default, the data is sent as soon as the DataWriter’s write() function is called.

You may have multiple Publishers, each managing a different set of DataWriters, or you may choose to use one Publisher for all your DataWriters.

For more information, see Creating Publishers Explicitly vs. Implicitly (Section 6.2.1).

6-2

Figure 6.1 on page 6-3 shows how these Entities are related, as well as the methods defined for each Entity.

Figure 6.1 Publication Module

Publishers are used to perform the operations listed in Table 6.1 on page 6-4. You can find more information about the operations by looking in the section listed under the Reference column. For details such as formal parameters and return codes, please see the API Reference HTML documentation.

Note: Some operations cannot be used within a listener callback, see Restricted Operations in Listener Callbacks (Section 4.5.1).

6.2.1Creating Publishers Explicitly vs. Implicitly

To send data, your application must have a Publisher. However, you are not required to explicitly create one. If you do not create one, the middleware will implicitly create a Publisher the first

6-3

Table 6.1 Publisher Operations

Working

Operation

 

 

Description

 

 

Reference

with ...

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

begin_coherent_

Indicates that the application will begin a coherent set

Section 6.3.10

 

changes

of modifications.

 

 

 

 

 

 

create_datawriter

Creates a DataWriter that will belong to the Publisher.

 

 

 

 

Section 6.3.1

 

create_datawriter_

Sets the DataWriter’s QoS based on a specified QoS

 

with_profile

profile.

 

 

 

 

 

 

 

 

 

 

 

copy_from_topic_qos

Copies relevant QosPolicies from a Topic into a

Section 6.2.4.5

 

 

DataWriterQoS structure.

 

 

 

 

 

delete_contained_

Deletes all of the DataWriters that were created by the

Section 6.2.3.1

 

entities

Publisher.

 

 

 

 

 

 

 

delete_datawriter

Deletes a DataWriter that belongs to the Publisher.

Section 6.3.3

 

 

 

 

 

 

 

 

 

 

end_coherent_changes

Ends

the

coherent

set

initiated

by

Section 6.3.10

 

 

begin_coherent_changes().

 

 

 

 

 

get_all_datawriters

Retrieves all the DataWriters created from this

Section 6.3.2

DataWriters

 

Publisher.

 

 

 

 

 

 

 

get_default_

Copies the Publisher’s default DataWriterQoS values

Section 6.3.15

 

datawriter_qos

into a DataWriterQos structure.

 

 

 

 

get_status_changes

Will always return 0 since there are no Statuses

Section 4.1.4

 

 

currently defined for Publishers.

 

 

 

 

lookup_datawriter

Retrieves a DataWriter previously created for a specific

Section 6.2.6

 

 

Topic.

 

 

 

 

 

 

 

set_default_datawriter_

Sets or changes the default DataWriterQos values.

 

 

qos

 

 

 

 

 

 

Section 6.2.4.4

 

set_default_datawriter_

Sets or changes the default DataWriterQos values

 

 

 

qos_with_profile

based on a QoS profile.

 

 

 

 

 

 

 

 

 

 

Blocks until all data written by the Publisher’s reliable

 

 

wait_for_

DataWriters are acknowledged by all matched reliable

Section 6.2.7

 

acknowledgments

DataReaders, or until the a specified timeout duration,

 

 

max_wait, elapses.

 

 

 

 

 

 

 

 

 

 

get_default_library

Gets the Publisher’s default QoS profile library.

 

 

 

 

 

 

 

 

get_default_profile

Gets the Publisher’s default QoS profile.

 

 

 

 

 

 

 

Libraries

get_default_profile_

Gets the library that contains the Publisher’s

default

Section 6.2.4.3

and Profiles

library

QoS profile.

 

 

 

 

 

 

 

 

 

 

set_default_library

Sets the default library for a Publisher.

 

 

 

 

 

 

 

 

 

 

set_default_profile

Sets the default profile for a Publisher.

 

 

 

 

 

 

 

Participants

get_participant

Gets the DomainParticipant that was used to create the

Section 6.2.6

 

 

Publisher.

 

 

 

 

 

 

6-4

Table 6.1 Publisher Operations

Working

Operation

Description

Reference

with ...

 

 

 

 

 

 

 

 

 

 

 

 

enable

Enables the Publisher.

Section 4.1.2

 

 

 

 

 

get_qos

Gets the Publisher’s current QosPolicy settings. This is

 

 

most often used in preparation for calling set_qos().

 

 

 

 

 

 

 

 

 

 

Sets the Publisher’s QoS. You can use this operation to

 

 

set_qos

change the values for the Publisher’s QosPolicies. Note,

Section 6.2.4

 

 

however, that not all QosPolicies can be changed after

 

 

 

the Publisher has been created.

 

 

 

 

 

 

set_qos_with_profile

Sets the Publisher’s QoS based on a specified QoS

 

Publishers

profile.

 

 

 

 

 

 

 

get_listener

Gets the currently installed Listener.

 

 

 

 

 

 

set_listener

Sets the Publisher’s Listener. If you created the

Section 6.2.5

 

Publisher without a Listener, you can use this

 

 

 

operation to add one later.

 

 

 

 

 

 

 

Provides a hint that multiple data-objects within the

 

 

suspend_publications

Publisher are about to be written. Connext does not

Section 6.2.9

 

 

currently use this hint.

 

 

 

 

 

 

 

 

resume_publications

Reverses the action of suspend_publications().

 

 

 

 

 

time you create a DataWriter using the DomainParticipant’s operations. It will be created with default QoS (DDS_PUBLISHER_QOS_DEFAULT) and no Listener.

A Publisher (implicit or explicit) gets its own default QoS and the default QoS for its child DataWriters from the DomainParticipant. These default QoS are set when the Publisher is created. (This is true for Subscribers and DataReaders, too.)

The 'implicit Publisher' can be accessed using the DomainParticipant’s get_implicit_publisher() operation (see Section 8.3.9). You can use this ‘implicit Publisher’ just like any other Publisher (it has the same operations, QosPolicies, etc.). So you can change the mutable QoS and set a Listener if desired.

DataWriters are created by calling create_datawriter() or create_datawriter_with_profile()— these operations exist for DomainParticipants and Publishers. If you use the DomainParticipant to create a DataWriter, it will belong to the implicit Publisher. If you use a Publisher to create a DataWriter, it will belong to that Publisher.

The middleware will use the same implicit Publisher for all DataWriters that are created using the

DomainParticipant’s operations.

Having the middleware implicitly create a Publisher allows you to skip the step of creating a Publisher. However, having all your DataWriters belong to the same Publisher can reduce the concurrency of the system because all the write operations will be serialized.

6.2.2Creating Publishers

Before you can explicitly create a Publisher, you need a DomainParticipant (see Section 8.3). To create a Publisher, use the DomainParticipant’s create_publisher() or create_publisher_with_profile() operations:

DDSPublisher * create_publisher (const DDS_PublisherQos &qos,

DDSPublisherListener *listener,

DDS_StatusMask mask)

DDSPublisher * create_publisher_with_profile (

const char *library_name, const char *profile_name,

6-5

DDSPublisherListener *listener,

DDS_StatusMask mask)

A QoS profile is way to use QoS settings from an XML file or string. With this approach, you can change QoS settings without recompiling the application. For details, see Chapter 17: Configuring QoS with XML.

qos If you want the default QoS settings (described in the API Reference HTML documentation), use DDS_PUBLISHER_QOS_DEFAULT for this parameter (see Figure 6.2). If you want to customize any of the QosPolicies, supply a QoS structure (see Figure 6.3). The QoS structure for a Publisher is described in Section 6.4.

Note: If you use DDS_PUBLISHER_QOS_DEFAULT, it is not safe to create the Publisher while another thread may be simultaneously calling set_default_publisher_qos().

listener Listeners are callback routines. Connext uses them to notify your application when specific events (status changes) occur with respect to the Publisher or the DataWriters created by the Publisher. The listener parameter may be set to NULL if you do not want to install a Listener. If you use NULL, the Listener of the DomainParticipant to which the Publisher belongs will be used instead (if it is set). For more information on

PublisherListeners, see Section 6.2.5.

mask This bit-mask indicates which status changes will cause the Publisher’s Listener to be invoked. The bits set in the mask must have corresponding callbacks implemented in the Listener. If you use NULL for the Listener, use DDS_STATUS_MASK_NONE for this parameter. If the Listener implements all callbacks, use DDS_STATUS_MASK_ALL. For information on statuses, see Listeners (Section 4.4).

library_name A QoS Library is a named set of QoS profiles. See QoS Libraries (Section 17.10). If NULL is used for library_name, the DomainParticipant’s default library is assumed (see Section 6.2.4.3).

profile_name A QoS profile groups a set of related QoS, usually one per entity. See QoS Profiles (Section 17.9). If NULL is used for profile_name, the DomainParticipant’s default profile is assumed and library_name is ignored.

Figure 6.2 Creating a Publisher with Default QosPolicies

// create the publisher DDSPublisher* publisher =

participant->create_publisher(DDS_PUBLISHER_QOS_DEFAULT, NULL, DDS_STATUS_MASK_NONE);

if (publisher == NULL) { // handle error

};

For more examples, see Configuring QoS Settings when the Publisher is Created (Section 6.2.4.1).

After you create a Publisher, the next step is to use the Publisher to create a DataWriter for each Topic, see Section 6.3.1. For a list of operations you can perform with a Publisher, see Table 6.1 on page 6-4.

6-6

6.2.3Deleting Publishers

This section applies to both implicitly and explicitly created Publishers. To delete a Publisher:

1.You must first delete all DataWriters that were created with the Publisher. Use the Publisher’s delete_datawriter() operation to delete them one at a time, or use the delete_contained_entities() operation (Section 6.2.3.1) to delete them all at the same time.

DDS_ReturnCode_t delete_datawriter (DDSDataWriter *a_datawriter)

2. Delete the Publisher by using the DomainParticipant’s delete_publisher() operation.

DDS_ReturnCode_t delete_publisher (DDSPublisher *p)

Note: A Publisher cannot be deleted within a Listener callback, see Restricted Operations in Listener Callbacks (Section 4.5.1).

6.2.3.1Deleting Contained DataWriters

The Publisher’s delete_contained_entities() operation deletes all the DataWriters that were created by the Publisher.

DDS_ReturnCode_t delete_contained_entities ()

After this operation returns successfully, the application may delete the Publisher (see Section 6.2.3).

6.2.4Setting Publisher QosPolicies

A Publisher’s QosPolicies control its behavior. Think of the policies as the configuration and behavior ‘properties’ of the Publisher. The DDS_PublisherQos structure has the following format:

DDS_PublisherQos struct {

 

DDS_PresentationQosPolicy

presentation;

DDS_PartitionQosPolicy

partition;

DDS_GroupDataQosPolicy

group_data;

DDS_EntityFactoryQosPolicy

entity_factory;

DDS_AsynchronousPublisherQosPolicy asynchronous_publisher;

DDS_ExclusiveAreaQosPolicy

exclusive_area;

} DDS_PublisherQos;

 

Note: set_qos() cannot always be used in a listener callback; see Restricted Operations in Listener Callbacks (Section 4.5.1).

Table 6.2 summarizes the meaning of each policy. (They appear alphabetically in the table.) For information on why you would want to change a particular QosPolicy, see the referenced section. For defaults and valid ranges, please refer to the API Reference HTML documentation for each policy.

Table 6.2 Publisher QosPolicies

QosPolicy

Description

 

 

 

 

ASYNCHRONOUS_PUBLISHER

Configures the mechanism that sends user data in an

QosPolicy (DDS Extension) (Section 6.4.1)

external middleware thread.

 

 

ENTITYFACTORY QosPolicy (Section

Controls whether or not child entities are created in the

6.4.2)

enabled state.

 

 

EXCLUSIVE_AREA QosPolicy (DDS

Configures multi-thread concurrency and deadlock

Extension) (Section 6.4.3)

prevention capabilities.

 

 

6-7

Table 6.2 Publisher QosPolicies

QosPolicy

Description

Along with TOPIC_DATA QosPolicy (Section 5.2.1) and

GROUP_DATA QosPolicy (Section 6.4.4)

USER_DATA QosPolicy (Section 6.5.25), this QosPolicy is used to attach a buffer of bytes to Connext's discovery meta- data.

PARTITION QosPolicy (Section 6.4.5)

Adds string identifiers that are used for matching

DataReaders and DataWriters for the same Topic.

PRESENTATION QosPolicy (Section 6.4.6)

Controls how Connext presents data received by an application to the DataReaders of the data.

6.2.4.1Configuring QoS Settings when the Publisher is Created

As described in Creating Publishers (Section 6.2.2), there are different ways to create a Publisher, depending on how you want to specify its QoS (with or without a QoS Profile).

In Figure 6.2 on page 6-6 we saw an example of how to explicitly create a Publisher with default QosPolicies. It used the special constant, DDS_PUBLISHER_QOS_DEFAULT, which indicates that the default QoS values for a Publisher should be used. Default Publisher QosPolicies are configured in the DomainParticipant; you can change them with the DomainParticipant’s set_default_publisher_qos() or set_default_publisher_qos_with_profile() operation (see Section 8.3.6.4).

To create a Publisher with non-default QoS settings, without using a QoS profile, see Figure 6.3 on page 6-9. It uses the DomainParticipant’s get_default_publisher_qos() method to initialize a DDS_PublisherQos structure. Then the policies are modified from their default values before the QoS structure is passed to create_publisher().

You can also create a Publisher and specify its QoS settings via a QoS Profile. To do so, call create_publisher_with_profile(), as seen in Figure 6.4 on page 6-9.

If you want to use a QoS profile, but then make some changes to the QoS before creating the Publisher, call the DomainParticipantFactory’s get_publisher_qos_from_profile(), modify the QoS and use the modified QoS structure when calling create_publisher(), as seen in Figure 6.5 on page 6-10.

For more information, see Creating Publishers (Section 6.2.2) and Chapter 17: Configuring QoS with XML.

6-8

Figure 6.3 Creating a Publisher with Non-default QosPolicies (not from a profile)

DDS_PublisherQos publisher_qos;1

// get defaults

if (participant->get_default_publisher_qos(publisher_qos) != DDS_RETCODE_OK){

// handle error

}

//make QoS changes here

//for example, this changes the ENTITY_FACTORY QoS publisher_qos.entity_factory.autoenable_created_entities =

DDS_BOOLEAN_FALSE;

// create the publisher DDSPublisher* publisher =

participant->create_publisher(publisher_qos,

NULL, DDS_STATUS_MASK_NONE);

if (publisher == NULL) { // handle error

}

1. For the C API, you need to use DDS_PublisherQos_INITIALIZER or DDS_PublisherQos_initialize(). See Section 4.2.2

Figure 6.4 Creating a Publisher with a QoS Profile

// create the publisher with QoS profile DDSPublisher* publisher =

participant->create_publisher_with_profile(

“MyPublisherLibary”,

“MyPublisherProfile”,

NULL, DDS_STATUS_MASK_NONE);

if (publisher == NULL) { // handle error

}

6-9

Figure 6.5 Getting QoS Values from a Profile, Changing QoS Values, Creating a Publisher with Modified QoS Values

DDS_PublisherQos publisher_qos;1

// Get publisher QoS from profile

retcode = factory->get_publisher_qos_from_profile(publisher_qos, “PublisherLibrary”, “PublisherProfile”);

if (retcode != DDS_RETCODE_OK) { // handle error

}

//Makes QoS changes here

//New entity_factory autoenable_created_entities will be true publisher_qos.entity_factory.autoenable_created_entities =

DDS_BOOLEAN_TRUE;

// create the publisher with modified QoS

DDSPublisher* publisher = participant->create_publisher( “Example Foo”, type_name, publisher_qos,

NULL, DDS_STATUS_MASK_NONE);

if (publisher == NULL) { // handle error

}

1. For the C API, you need to use DDS_PublisherQos_INITIALIZER or DDS_PublisherQos_initialize(). See Section 4.2.2

6.2.4.2Changing QoS Settings After the Publisher Has Been Created

There are 2 ways to change an existing Publisher’s QoS after it is has been created—again depending on whether or not you are using a QoS Profile.

To change an existing Publisher’s QoS programmatically (that is, without using a QoS profile): get_qos() and set_qos(). See the example code in Figure 6.6. It retrieves the current values by calling the Publisher’s get_qos() operation. Then it modify the value and call set_qos() to apply the new value. Note, however, that some QosPolicies cannot be changed after the Publisher has been enabled—this restriction is noted in the descriptions of the individual QosPolicies.

You can also change a Publisher’s (and all other Entities’) QoS by using a QoS Profile and calling set_qos_with_profile(). For an example, see Figure 6.7. For more information, see Chapter 17: Configuring QoS with XML.

6-10

Figure 6.6 Changing the Qos of an Existing Publisher

DDS_PublisherQos publisher_qos;1

// Get current QoS. publisher points to an existing DDSPublisher. if (publisher->get_qos(publisher_qos) != DDS_RETCODE_OK) {

// handle error

}

//make changes

//New entity_factory autoenable_created_entities will be true

publisher_qos.entity_factory.autoenable_created_entities =DDS_BOOLEAN_TRUE; // Set the new QoS

if (publisher->set_qos(publisher_qos) != DDS_RETCODE_OK ) { // handle error

}

1.For the C API, you need to use DDS_PublisherQos_INITIALIZER or DDS_PublisherQos_Initialize(). See Section 4.2.2

Figure 6.7 Changing the QoS of an Existing Publisher with a QoS Profile

retcode = publisher->set_qos_with_profile( “PublisherProfileLibrary”,”PublisherProfile”);

if (retcode != DDS_RETCODE_OK) { // handle error

}

6.2.4.3Getting and Setting the Publisher’s Default QoS Profile and Library

You can retrieve the default QoS profile used to create Publishers with the get_default_profile() operation.

You can also get the default library for Publishers, as well as the library that contains the Publisher’s default profile (these are not necessarily the same library); these operations are called get_default_library() and get_default_library_profile(), respectively. These operations are for informational purposes only (that is, you do not need to use them as a precursor to setting a library or profile.) For more information, see Chapter 17: Configuring QoS with XML.

virtual const char * get_default_library () const char * get_default_profile ()

const char * get_default_profile_library ()

There are also operations for setting the Publisher’s default library and profile:

DDS_ReturnCode_t set_default_library (const char * library_name) DDS_ReturnCode_t set_default_profile (const char * library_name, const char * profile_name)

These operations only affect which library/profile will be used as the default the next time a default Publisher library/profile is needed during a call to one of this Publisher’s operations.

When calling a Publisher operation that requires a profile_name parameter, you can use NULL to refer to the default profile. (This same information applies to setting a default library.) If the default library/profile is not set, the Publisher inherits the default from the DomainParticipant.

set_default_profile() does not set the default QoS for DataWriters created by the Publisher; for this functionality, use the Publisher’s set_default_datawriter_qos_with_profile(), see

Section 6.2.4.4 (you may pass in NULL after having called the Publisher’s set_default_profile()).

set_default_profile() does not set the default QoS for newly created Publishers; for this functionality, use the DomainParticipant’s set_default_publisher_qos_with_profile() operation,

6-11

see Section 8.3.6.4.

6.2.4.4Getting and Setting Default QoS for DataWriters

These operations set the default QoS that will be used for new DataWriters if create_datawriter() is called with DDS_DATAWRITER_QOS_DEFAULT as the ‘qos’ parameter:

DDS_ReturnCode_t set_default_datawriter_qos (const DDS_DataWriterQos &qos)

DDS_ReturnCode_t set_default_datawriter_qos_with_profile (

const char *library_name, const char *profile_name)

The above operations may potentially allocate memory, depending on the sequences contained in some QoS policies.

To get the default QoS that will be used for creating DataWriters if create_datawriter() is called with DDS_PARTICIPANT_QOS_DEFAULT as the ‘qos’ parameter:

DDS_ReturnCode_t get_default_datawriter_qos (DDS_DataWriterQos & qos)

This operation gets the QoS settings that were specified on the last successful call to set_default_datawriter_qos() or set_default_datawriter_qos_with_profile(), or if the call was never made, the default values listed in DDS_DataWriterQos.

Note: It is not safe to set the default DataWriter QoS values while another thread may be simultaneously calling get_default_datawriter_qos(), set_default_datawriter_qos(), or create_datawriter() with DDS_DATAWRITER_QOS_DEFAULT as the qos parameter. It is also not safe to get the default DataWriter QoS values while another thread may be simultaneously calling set_default_datawriter_qos(),

6.2.4.5Other Publisher QoS-Related Operations

Copying a Topic’s QoS into a DataWriter’s QoS This method is provided as a convenience for setting the values in a DataWriterQos structure before using that structure to create a DataWriter. As explained in Section 5.1.3, most of the policies in a TopicQos structure do not apply directly to the Topic itself, but to the associated DataWriters and DataReaders of that Topic. The TopicQos serves as a single container where the values of QosPolicies that must be set compatibly across matching DataWriters and DataReaders can be stored.

Thus instead of setting the values of the individual QosPolicies that make up a DataWriterQos structure every time you need to create a DataWriter for a Topic, you can use the Publisher’s copy_from_topic_qos() operation to “import” the Topic’s QosPolicies into a DataWriterQos structure. This operation copies the relevant policies in the TopicQos to the corresponding policies in the DataWriterQos.

This copy operation will often be used in combination with the Publisher’s get_default_datawriter_qos() and the Topic’s get_qos() operations. The Topic’s QoS values are merged on top of the Publisher’s default DataWriter QosPolicies with the result used to create a new DataWriter, or to set the QoS of an existing one (see Section 6.3.15).

Copying a Publisher’s QoS C API users should use the DDS_PublisherQos_copy() operation rather than using structure assignment when copying between two QoS structures. The copy() operation will perform a deep copy so that policies that allocate heap memory such as sequences are copied correctly. In C++, C++/CLI, C# and Java, a copy constructor is provided to take care of sequences automatically.

Clearing QoS-Related Memory Some QosPolicies contain sequences that allocate memory dynamically as they grow or shrink. The C API’s DDS_PublisherQos_finalize() operation frees the memory used by sequences but otherwise leaves the QoS unchanged. C API users should call finalize() on all

6-12

DDS_PublisherQos objects before they are freed, or for QoS structures allocated on the stack, before they go out of scope. In C++, C++/CLI, C# and Java, the memory used by sequences is freed in the destructor.

6.2.5Setting Up PublisherListeners

Like all Entities, Publishers may optionally have Listeners. Listeners are user-defined objects that implement a DDS-defined interface (i.e. a pre-defined set of callback functions). Listeners provide the means for Connext to notify applications of any changes in Statuses (events) that may be relevant to it. By writing the callback functions in the Listener and installing the Listener into the Publisher, applications can be notified to handle the events of interest. For more general information on Listeners and Statuses, see Section 4.4.

Note: Some operations cannot be used within a listener callback, see Restricted Operations in Listener Callbacks (Section 4.5.1).

As illustrated in Figure 6.1 on page 6-3, the PublisherListener interface extends the DataWriterListener interface. In other words, the PublisherListener interface contains all the functions in the DataWriterListener interface. There are no Publisher-specific statuses, and thus there are no Publisher-specific functions.

Instead, the methods of a PublisherListener will be called back for changes in the Statuses of any of the DataWriters that the Publisher has created. This is only true if the DataWriter itself does not have a DataWriterListener installed, see Section 6.3.4. If a DataWriterListener has been installed and has been enabled to handle a Status change for the DataWriter, then Connext will call the method of the DataWriterListener instead.

If you want a Publisher to handle status events for its DataWriters, you can set up a PublisherListener during the Publisher’s creation or use the set_listener() method after the Publisher is created. The last parameter is a bit-mask with which you should set which Status events that the PublisherListener will handle. For example,

DDS_StatusMask mask = DDS_OFFERED_DEADLINE_MISSED_STATUS | DDS_OFFERED_INCOMPATIBLE_QOS_STATUS;

publisher = participant->create_publisher(DDS_PUBLISHER_QOS_DEFAULT, listener, mask);

or

DDS_StatusMask mask = DDS_OFFERED_DEADLINE_MISSED_STATUS | DDS_OFFERED_INCOMPATIBLE_QOS_STATUS;

publisher->set_listener(listener, mask);

As previously mentioned, the callbacks in the PublisherListener act as ‘default’ callbacks for all the DataWriters contained within. When Connext wants to notify a DataWriter of a relevant Status change (for example, PUBLICATION_MATCHED), it first checks to see if the DataWriter has the corresponding DataWriterListener callback enabled (such as the on_publication_matched() operation). If so, Connext dispatches the event to the DataWriterListener callback. Otherwise, Connext dispatches the event to the corresponding PublisherListener callback.

A particular callback in a DataWriter is not enabled if either:

The application installed a NULL DataWriterListener (meaning there are no callbacks for the DataWriter at all).

The application has disabled the callback for a DataWriterListener. This is done by turning off the associated status bit in the mask parameter passed to the set_listener() or create_datawriter() call when installing the DataWriterListener on the DataWriter. For more information on DataWriterListeners, see Section 6.3.4.

Similarly, the callbacks in the DomainParticipantListener act as ‘default’ callbacks for all the Publishers that belong to it. For more information on DomainParticipantListeners, see Section 8.3.5.

6-13

For example, Figure 6.8 shows how to create a Publisher with a Listener that simply prints the events it receives.

Figure 6.8 Example Code to Create a Publisher with a Simple Listener

class MyPublisherListener : public DDSPublisherListener { public:

virtual void on_offered_deadline_missed(DDSDataWriter* writer, const DDS_OfferedDeadlineMissedStatus& status);

virtual void on_liveliness_lost(DDSDataWriter* writer, const DDS_LivelinessLostStatus& status);

virtual void on_offered_incompatible_qos(DDSDataWriter* writer, const DDS_OfferedIncompatibleQosStatus& status);

virtual void on_publication_matched(DDSDataWriter* writer, const DDS_PublicationMatchedStatus& status);

virtual void

on_reliable_writer_cache_changed(DDSDataWriter* writer, const DDS_ReliableWriterCacheChangedStatus& status);

virtual void on_reliable_reader_activity_changed (DDSDataWriter* writer,

const DDS_ReliableReaderActivityChangedStatus& status);

};

void MyPublisherListener::on_offered_deadline_missed( DDSDataWriter* writer,

const DDS_OfferedDeadlineMissedStatus& status)

{

printf(“on_offered_deadline_missed\n”);

}

// ...Implement all remaining listeners in a similar manner...

DDSPublisherListener *myPubListener = new MyPublisherListener();

DDSPublisher* publisher = participant->create_publisher( DDS_PUBLISHER_QOS_DEFAULT, myPubListener, DDS_STATUS_MASK_ALL);

6.2.6Finding a Publisher’s Related Entities

These Publisher operations are useful for obtaining a handle to related entities:

get_participant(): Gets the DomainParticipant with which a Publisher was created.

lookup_datawriter(): Finds a DataWriter created by the Publisher with a Topic of a particular name. Note that in the event that multiple DataWriters were created by the same Publisher with the same Topic, any one of them may be returned by this method.

DDS_Publisher_as_Entity(): This method is provided for C applications and is necessary when invoking the parent class Entity methods on Publishers. For example, to call the Entity method get_status_changes() on a Publisher, my_pub, do the following:

DDS_Entity_get_status_changes(DDS_Publisher_as_Entity(my_pub))

DDS_Publisher_as_Entity() is not provided in the C++, C++/CLI, C# and Java APIs because the object-oriented features of those languages make it unnecessary.

6-14

6.2.7Waiting for Acknowledgments in a Publisher

The Publisher’s wait_for_acknowledgments() operation blocks the calling thread until either all data written by the Publisher’s reliable DataWriters is acknowledged or the duration specified by the max_wait parameter elapses, whichever happens first.

Note that if a thread is blocked in the call to wait_for_acknowledgments() on a Publisher and a different thread writes new samples on any of the Publisher’s reliable DataWriters, the new samples must be acknowledged before unblocking the thread that is waiting on wait_for_acknowledgments().

DDS_ReturnCode_t wait_for_acknowledgments

(const DDS_Duration_t & max_wait)

This operation returns DDS_RETCODE_OK if all the samples were acknowledged, or

DDS_RETCODE_TIMEOUT if the max_wait duration expired first.

There is a similar operation available for individual DataWriters, see Section 6.3.11.

The reliability protocol used by Connext is discussed in Chapter 10: Reliable Communications.

6.2.8Statuses for Publishers

There are no statuses specific to the Publisher itself. The following statuses can be monitored by the PublisherListener for the Publisher’s DataWriters.

OFFERED_DEADLINE_MISSED Status (Section 6.3.6.4)

LIVELINESS_LOST Status (Section 6.3.6.3)

OFFERED_INCOMPATIBLE_QOS Status (Section 6.3.6.5)

PUBLICATION_MATCHED Status (Section 6.3.6.6)

RELIABLE_WRITER_CACHE_CHANGED Status (DDS Extension) (Section 6.3.6.7)

RELIABLE_READER_ACTIVITY_CHANGED Status (DDS Extension) (Section 6.3.6.8)

6.2.9Suspending and Resuming Publications

The operations suspend_publications() and resume_publications() provide a hint to Connext that multiple data-objects within the Publisher are about to be written. Connext does not currently use this hint.

6.3DataWriters

To create a DataWriter, you need a DomainParticipant and a Topic.

You need a DataWriter for each Topic that you want to publish. Once you have a DataWriter, you can use it to perform the operations listed in Table 6.3. The most important operation is write(), described in Section 6.3.8. For more details on all operations, see the API Reference HTML documentation.

DataWriters are created by using operations on a DomainParticipant or a Publisher, as described in Section 6.3.1. If you use the DomainParticipant’s operations, the DataWriter will belong to an implicit Publisher that is automatically created by the middleware. If you use a Publisher’s operations, the DataWriter will belong to that Publisher. So either way, the DataWriter belongs to a

Publisher.

Note: Some operations cannot be used within a listener callback, see Restricted Operations in Listener Callbacks (Section 4.5.1).

6-15

Table 6.3 DataWriter Operations

Working with

Operation

 

 

 

Description

 

 

Reference

...

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

assert_liveliness

Manually asserts the liveliness of the DataWriter.

Section 6.3.17

 

 

 

 

 

 

 

 

enable

Enables the DataWriter.

 

 

 

Section 4.1.2

 

 

 

 

 

 

 

 

 

 

get_qos

Gets the QoS.

 

 

 

 

 

Section 6.3.15

 

 

 

 

 

 

 

lookup_instance

Gets a handle, given an instance.

(Useful

for

Section 6.3.14.3

DataWriters

 

keyed data types only.)

 

 

 

 

 

set_qos

Modifies the QoS.

 

 

 

Section 6.3.15

 

 

 

 

 

 

set_qos_with_profile

Modifies the QoS based on a QoS profile.

 

Section 6.3.15

 

 

 

 

 

 

 

get_listener

Gets the currently installed Listener.

 

 

Section 6.3.4

 

 

 

 

 

 

 

 

 

 

set_listener

Replaces the Listener.

 

 

 

 

 

 

 

 

 

 

 

 

 

dispose

States that the instance no longer exists. (Useful

 

 

for keyed data types only.)

 

 

 

 

 

 

 

 

 

 

 

 

 

Section 6.3.14.2

 

 

Same as dispose, but allows the application to

 

dispose_w_timestamp

override the automatic source_timestamp.

 

 

 

(Useful for keyed data types only.)

 

 

 

 

 

 

 

 

flush

Makes the batch available to be sent on the

Section 6.3.9

 

 

network.

 

 

 

 

 

 

 

 

get_key_value

Maps an instance_handle to the corresponding

Section 6.3.14.4

 

 

key.

 

 

 

 

 

 

 

 

 

A type-safe way to cast a pointer. This takes a

 

 

narrow

DDSDataWriter pointer and ‘narrows’ it to a

Section 6.3.7

 

‘FooDataWriter’ where ‘Foo’ is the related data

 

 

type.

 

 

 

 

 

 

 

 

 

 

 

FooData-

 

States the intent of the DataWriter to write values

 

Writer

register_instance

of the data-instance that matches a specified key.

 

(See

Improves the performance of subsequent writes

 

 

 

Section 6.3.7)

 

to the instance. (Useful for keyed data types only.)

 

 

register_instance_w_

Like register_instance, but allows the application

 

 

to override

the

automatic

source_timestamp.

 

 

timestamp

 

 

(Useful for keyed data types only.)

 

 

 

 

 

 

 

Section 6.3.14.1

 

 

 

 

 

 

 

 

 

 

 

Reverses

register_instance.

Relinquishes

the

 

 

 

 

unregister_instance

ownership of the instance. (Useful for keyed data

 

 

 

types only.)

 

 

 

 

 

 

 

 

 

 

 

 

Like unregister_instance, but allows the

 

 

unregister_instance_w_

application

to

override

the

automatic

 

 

timestamp

source_timestamp. (Useful for keyed data types

 

 

 

only.)

 

 

 

 

 

 

 

 

 

 

 

 

 

write

Writes a new value for a data-instance.

 

 

 

 

 

 

 

 

 

Section 6.3.8

 

write_w_timestamp

Same as

write,

but allows

the application

to

 

override the automatic source_timestamp.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

6-16

Table 6.3 DataWriter Operations

Working with

Operation

Description

 

Reference

...

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Same as write, but allows the application to

 

 

write_w_params

specify parameters such as source timestamp and

Section 6.3.8

 

 

instance handle.

 

 

 

 

 

 

 

 

Same as dispose, but allows the application to

 

FooData-

dispose_w_params

specify parameters such as source timestamp and

Section 6.3.14.2

 

instance handle..

 

 

Writer

 

 

 

 

 

 

 

(See

 

Same as register, but allows the application to

 

Section 6.3.7)

register_w_params

specify parameters such as source timestamp,

 

 

 

instance handle.

 

Section 6.3.14.1

 

 

 

 

 

 

Same as unregister, but allows the application to

 

 

 

 

unregister_w_params

specify parameters such as source timestamp, and

 

 

 

instance handle.

 

 

 

 

 

 

 

 

Gets a list of subscriptions that have a matching

 

 

get_matched_

Topic and compatible QoS. These are the

 

 

subscriptions

subscriptions currently associated with the

 

 

 

DataWriter.

 

 

 

 

 

 

 

Matched

get_matched_

Gets information on a subscription with

a

Section 6.3.16.1

Subscriptions

subscription_data

matching Topic and compatible QoS.

 

 

 

 

 

Gets a list of locators for subscriptions that have a

 

 

get_matched_

matching Topic and compatible QoS. These are

 

 

subscription_locators

the subscriptions currently associated with the

 

 

 

DataWriter.

 

 

 

 

 

 

 

 

Gets a list of statuses that have changed since the

 

 

get_status_changes

last time the application read the status or the

Section 4.1.4

 

 

listeners were called.

 

 

 

 

 

 

 

 

get_liveliness_lost_status

Gets LIVELINESS_LOST status.

 

 

 

 

 

 

 

 

get_offered_deadline_

Gets OFFERED_DEADLINE_MISSED status.

 

 

 

missed_status

 

 

 

 

 

 

 

 

 

 

 

 

get_offered_

Gets OFFERED_INCOMPATIBLE_QOS status.

 

 

 

incompatible_qos_status

 

 

 

 

 

 

 

 

 

 

 

 

get_publication_match_

Gets PUBLICATION_MATCHED_QOS status.

 

 

 

status

 

 

 

 

 

 

 

 

 

 

 

get_reliable_writer_

Gets RELIABLE_WRITER_CACHE_CHANGED

Section 6.3.6

 

cache_changed_status

status

 

 

 

 

 

 

 

 

 

Status

get_reliable_reader_

Gets

 

 

 

RELIABLE_READER_ACTIVITY_CHANGED

 

 

 

activity_changed_status

 

 

 

status

 

 

 

 

 

 

 

 

 

 

 

 

get_datawriter_cache_

Gets DATA_WRITER_CACHE_status

 

 

 

status

 

 

 

 

 

 

 

 

 

 

 

 

get_datawriter_protocol_

Gets DATA_WRITER_PROTOCOL status

 

 

 

status

 

 

 

 

get_matched_

Gets DATA_WRITER_PROTOCOL status for this

 

 

subscription_datawriter_

DataWriter, per matched subscription identified

 

 

protocol_status

by the subscription_handle.

 

 

 

 

 

 

Section 6.3.6

 

get_matched_

Gets DATA_WRITER_PROTOCOL status for this

 

subscription_datawriter_

 

 

DataWriter, per matched subscription

as

 

 

protocol_status_

identified by a locator.

 

 

 

by_locator

 

 

 

 

 

 

 

 

 

 

 

6-17

Table 6.3 DataWriter Operations

Working with

Operation

Description

Reference

...

 

 

 

 

 

 

 

 

 

 

 

 

get_publisher

Gets the Publisher to which the DataWriter

 

 

belongs.

Section 6.3.16.2

 

 

 

get_topic

Get the Topic associated with the DataWriter.

 

Other

 

 

 

 

Blocks the calling thread until either all data

 

 

 

 

 

wait_for_

written by the DataWriter is acknowledged by all

Section 6.3.11

 

acknowledgements

matched Reliable DataReaders, or until the a

 

 

 

specified timeout duration, max_wait, elapses.

 

 

 

 

 

6.3.1Creating DataWriters

Before you can create a DataWriter, you need a DomainParticipant, a Topic, and optionally, a

Publisher.

DataWriters are created by calling create_datawriter() or create_datawriter_with_profile()— these operations exist for DomainParticipants and Publishers. If you use the DomainParticipant to create a DataWriter, it will belong to the implicit Publisher described in Section 6.2.1. If you use a Publisher’s operations to create a DataWriter, it will belong to that Publisher.

DDSDataWriter* create_datawriter ( DDSTopic *topic,

const DDS_DataWriterQos &qos,

DDSDataWriterListener *listener, DDS_StatusMask mask)

DDSDataWriter * create_datawriter_with_profile ( DDSTopic * topic,

const char * library_name, const char * profile_name,

DDSDataWriterListener * listener, DDS_StatusMask mask)

A QoS profile is way to use QoS settings from an XML file or string. With this approach, you can change QoS settings without recompiling the application. For details, see Chapter 17: Configuring QoS with XML.

topic The Topic that the DataWriter will publish. This must have been previously created by the same DomainParticipant.

qos If you want the default QoS settings (described in the API Reference HTML documentation), use the constant DDS_DATAWRITER_QOS_DEFAULT for this parameter (see Figure 6.9 on page 6-19). If you want to customize any of the QosPolicies, supply a QoS structure (see Section 6.3.15).

Note: If you use DDS_DATAWRITER_QOS_DEFAULT for the qos parameter, it is not safe to create the DataWriter while another thread may be simultaneously calling the Pub- lisher’s set_default_datawriter_qos() operation.

listener Listeners are callback routines. Connext uses them to notify your application of specific events (status changes) that may occur with respect to the DataWriter. The listener parameter may be set to NULL; in this case, the PublisherListener (or if that is NULL, the DomainParticipantListener) will be used instead. For more information, see Section 6.3.4.

mask This bit-mask indicates which status changes will cause the Listener to be invoked. The bits set in the mask must have corresponding callbacks implemented in the Listener. If you use NULL for the Listener, use DDS_STATUS_MASK_NONE for this parameter. If the Listener implements all callbacks, use DDS_STATUS_MASK_ALL. For information on statuses, see Listeners (Section 4.4).

library_name A QoS Library is a named set of QoS profiles. See QoS Libraries (Section 17.10).

6-18

profile_name A QoS profile groups a set of related QoS, usually one per entity. See QoS Profiles (Section 17.9).

For more examples on how to create a DataWriter, see Configuring QoS Settings when the DataWriter is Created (Section 6.3.15.1)

After you create a DataWriter, you can use it to write data. See Writing Data (Section 6.3.8).

Note: When a DataWriter is created, only those transports already registered are available to the DataWriter. The built-in transports are implicitly registered when (a) the DomainParticipant is enabled, (b) the first DataWriter is created, or (c) you look up a built-in data reader, whichever happens first.

Figure 6.9 Creating a DataWriter with Default QosPolicies and a Listener

// MyWriterListener is user defined, extends DDSDataWriterListener DDSDataWriterListener* writer_listener = new MyWriterListener();

DDSDataWriter* writer = publisher->create_datawriter( topic,

DDS_DATAWRITER_QOS_DEFAULT, writer_listener, DDS_STATUS_MASK_ALL);

if (writer == NULL) { // ... error

};

// narrow it for your specific data type

FooDataWriter* foo_writer = FooDataWriter::narrow(writer);

6.3.2Getting All DataWriters

To retrieve all the DataWriters created by the Publisher, use the Publisher’s get_all_datawriters() operation:

DDS_ReturnCode_t get_all_datawriters(DDS_Publisher* self,

struct DDS_DataWriterSeq* writers);

6-19

6.3.3Deleting DataWriters

To delete a single DataWriter, use the Publisher’s delete_datawriter() operation:

DDS_ReturnCode_t delete_datawriter (DDSDataWriter *a_datawriter)

Note: A DataWriter cannot be deleted within its own writer listener callback, see Restricted Operations in Listener Callbacks (Section 4.5.1)

To delete all of a Publisher’s DataWriters, use the Publisher’s delete_contained_entities() operation (see Section 6.2.3.1).

Special instructions for deleting DataWriters if you are using the ‘Timestamp’ APIs and BY_SOURCE_TIMESTAMP Destination Order:

This note only applies when the DataWriter’s DestinationOrderQosPolicy’s kind is BY_SOURCE_TIMESTAMP.

Calls to delete_datawriter() may fail if your application has previously used the “with timestamp” APIs (write_w_timestamp(), register_instance_w_timestamp(), unregister_instance_w_timestamp(), or dispose_w_timestamp()) with a timestamp that is larger than the time at which delete_datawriter() is called.

To prevent delete_datawriter() from failing in this situation, either:

Change the WriterDataLifeCycle QoS Policy so that Connext will not auto-dispose unregistered instances:

writer_qos.writer_data_lifecycle. autodispose_unregistered_instances =

DDS_BOOLEAN_FALSE; or

Explicitly call unregister_instance_w_timestamp() for all instances modified with the

*_w_timestamp() APIs before calling delete_datawriter().

6.3.4Setting Up DataWriterListeners

DataWriters may optionally have Listeners. Listeners are essentially callback routines and provide the means for Connext to notify your application of the occurrence of events (status changes) relevant to the DataWriter. For more general information on Listeners, see Listeners (Section 4.4).

Note: Some operations cannot be used within a listener callback, see Restricted Operations in Listener Callbacks (Section 4.5.1).

If you do not implement a DataWriterListener, the associated PublisherListener is used instead. If that Publisher also does not have a Listener, then the DomainParticipant’s Listener is used if one exists (see Section 6.2.5 and Section 8.3.5).

Listeners are typically set up when the DataWriter is created (see Section 6.2). You can also set one up after creation by using the set_listener() operation. Connext will invoke a DataWriter’s

6-20

Listener to report the status changes listed in Table 6.4 (if the Listener is set up to handle the particular status, see Section 6.3.4).

Table 6.4 DataWriterListener Callbacks

This DataWriterListener callback...

 

 

 

... is triggered by ...

 

 

 

 

 

 

A replacement of an existing instance by a new instance;

on_instance_replaced()

see Configuring DataWriter Instance Replacement (Section

 

6.5.20.2)

 

 

 

 

 

on_liveliness_lost

A change to LIVELINESS_LOST Status (Section 6.3.6.3)

 

 

 

 

 

 

on_offered_deadline_missed

A

change

to

OFFERED_DEADLINE_MISSED

Status

(Section 6.3.6.4)

 

 

 

 

 

 

 

 

 

 

 

on_offered_incompatible_qos

A

change

to

OFFERED_INCOMPATIBLE_QOS

Status

(Section 6.3.6.5)

 

 

 

 

 

 

 

on_publication_matched

A change to PUBLICATION_MATCHED Status (Section

6.3.6.6)

 

 

 

 

 

 

 

 

 

 

 

on_reliable_writer_cache_changed

A

change

to RELIABLE_WRITER_CACHE_CHANGED

Status (DDS Extension) (Section 6.3.6.7)

 

 

 

 

 

on_reliable_reader_activity_changed

A change to RELIABLE_READER_ACTIVITY_CHANGED

Status (DDS Extension) (Section 6.3.6.8)

 

 

 

 

 

 

 

 

 

6.3.5Checking DataWriter Status

You can access an individual communication status for a DataWriter with the operations shown in Table 6.5.

Table 6.5 DataWriter Status Operations

Use this operation...

...to retrieve this status:

 

 

 

 

 

 

 

get_datawriter_cache_status

DATA_WRITER_CACHE_STATUS (Section 6.3.6.1)

 

 

 

 

get_datawriter_protocol_status

 

 

 

 

 

get_matched_subscription_datawriter_

 

 

protocol_status

DATA_WRITER_PROTOCOL_STATUS (Section 6.3.6.2)

 

 

 

get_matched_subscription_datawriter_

 

 

protocol_status_by_locator

 

 

 

 

 

get_liveliness_lost_status

LIVELINESS_LOST Status (Section 6.3.6.3)

 

 

 

get_offered_deadline_missed_status

OFFERED_DEADLINE_MISSED Status (Section 6.3.6.4)

 

 

get_offered_incompatible_qos_status

OFFERED_INCOMPATIBLE_QOS Status (Section 6.3.6.5)

 

 

 

get_publication_match_status

PUBLICATION_MATCHED Status (Section 6.3.6.6)

 

 

 

 

get_reliable_writer_cache_changed_status

RELIABLE_WRITER_CACHE_CHANGED Status

(DDS

Extension) (Section 6.3.6.7)

 

 

 

 

 

 

get_reliable_reader_activity_changed_status

RELIABLE_READER_ACTIVITY_CHANGED

Status

 

(DDS Extension) (Section 6.3.6.8)

 

get_status_changes

A list of what changed in all of the above.

 

 

 

 

These methods are useful in the event that no Listener callback is set to receive notifications of status changes. If a Listener is used, the callback will contain the new status information, in which case calling these methods is unlikely to be necessary.

The get_status_changes() operation provides a list of statuses that have changed since the last time the status changes were ‘reset.’ A status change is reset each time the application calls the

6-21

corresponding get_*_status(), as well as each time Connext returns from calling the Listener callback associated with that status.

For more on status, see Setting Up DataWriterListeners (Section 6.3.4), Statuses for DataWriters (Section 6.3.6), and Listeners (Section 4.4).

6.3.6Statuses for DataWriters

There are several types of statuses available for a DataWriter. You can use the get_*_status() operations (Section 6.3.15) to access them, or use a DataWriterListener (Section 6.3.4) to listen for changes in their values. Each status has an associated data structure and is described in more detail in the following sections.

DATA_WRITER_CACHE_STATUS (Section 6.3.6.1)

DATA_WRITER_PROTOCOL_STATUS (Section 6.3.6.2)

LIVELINESS_LOST Status (Section 6.3.6.3)

OFFERED_DEADLINE_MISSED Status (Section 6.3.6.4)

OFFERED_INCOMPATIBLE_QOS Status (Section 6.3.6.5)

PUBLICATION_MATCHED Status (Section 6.3.6.6)

RELIABLE_WRITER_CACHE_CHANGED Status (DDS Extension) (Section 6.3.6.7)

RELIABLE_READER_ACTIVITY_CHANGED Status (DDS Extension) (Section 6.3.6.8)

6.3.6.1DATA_WRITER_CACHE_STATUS

This status keeps track of the number of samples in the DataWriter’s queue.

This status does not have an associated Listener. You can access this status by calling the DataWriter’s get_datawriter_cache_status() operation, which will return the status structure described in Table 6.6.

Table 6.6 DDS_DataWriterCacheStatus

Type

Field Name

Description

 

 

 

 

 

 

DDS_Long

sample_count_peak

Highest number of samples in the DataWriter’s queue over the

lifetime of the DataWriter.

 

 

 

 

 

DDS_Long

sample_count

Current number of samples in the DataWriter’s queue.

 

 

 

6.3.6.2DATA_WRITER_PROTOCOL_STATUS

This status includes internal protocol related metrics (such as the number of samples pushed, pulled, filtered) and the status of wire-protocol traffic.

Pulled samples are samples sent for repairs (that is, samples that had to be resent), for late joiners, and all samples sent by the local DataWriter when push_on_write (in DATA_WRITER_PROTOCOL QosPolicy (DDS Extension) (Section 6.5.3)) is DDS_BOOLEAN_FALSE.

Pushed samples are samples sent on write() when push_on_write is DDS_BOOLEAN_TRUE.

Filtered samples are samples that are not sent due to DataWriter filtering (time-based filtering and ContentFilteredTopics).

This status does not have an associated Listener. You can access this status by calling the following operations on the DataWriter (all of which return the status structure described in Table 6.7 on page 6-23):

get_datawriter_protocol_status() returns the sum of the protocol status for all the matched subscriptions for the DataWriter.

6-22

get_matched_subscription_datawriter_protocol_status() returns the protocol status of a particular matched subscription, identified by a subscription_handle.

get_matched_subscription_datawriter_protocol_status_by_locator() returns the protocol status of a particular matched subscription, identified by a locator. (See Locator Format (Section 14.2.1.1).)

Note: Status for a remote entity is only kept while the entity is alive. Once a remote entity is no longer alive, its status is deleted. If you try to get the matched subscription status for a remote entity that is no longer alive, the ‘get status’ call will return an error.

Table 6.7 DDS_DataWriterProtocolStatus

Type

Field Name

Description

 

 

 

 

 

 

 

pushed_sample_count

The number of user samples pushed on write from a

 

local DataWriter to a matching remote DataReader.

 

 

 

 

 

 

 

The incremental change in the number of user samples

 

pushed_sample_count_change

pushed on write from a local DataWriter to a matching

 

remote DataReader since the last time the status was

 

 

 

 

read.

DDS_LongLong

 

 

 

The number of bytes of user samples pushed on write

 

pushed_sample_bytes

from a local DataWriter to a matching remote

 

 

DataReader.

 

 

 

 

 

The incremental change in the number of bytes of user

 

pushed_sample_bytes_change

samples pushed on write from a local DataWriter to a

 

matching remote DataReader since the last time the

 

 

 

 

status was read.

 

 

 

 

filtered_sample_count

The number of user samples preemptively filtered by a

 

local DataWriter due to Content-Filtered Topics.

 

 

 

 

 

 

 

The incremental change in the number of user samples

 

filtered_sample_count_change

preemptively filtered by a local DataWriter due to

 

ContentFilteredTopics since the last time the status

 

 

DDS_LongLong

 

was read.

 

 

filtered_sample_bytes

The number of user samples preemptively filtered by a

 

 

local DataWriter due to ContentFilteredTopics.

 

 

 

 

 

 

 

The incremental change in the number of user samples

 

filtered_sample_bytes_change

preemptively filtered by a local DataWriter due to

 

ContentFilteredTopics since the last time the status

 

 

 

 

was read.

 

 

 

 

sent_heartbeat_count

The number of Heartbeats sent between a local

 

DataWriter and matching remote DataReaders.

 

 

 

 

 

 

 

The incremental change in the number of Heartbeats

 

sent_heartbeat_count_change

sent between a local DataWriter and matching remote

 

 

DataReaders since the last time the status was read.

DDS_LongLong

 

 

sent_heartbeat_bytes

The number of bytes of Heartbeats sent between a

 

local DataWriter and matching remote DataReader.

 

 

 

 

 

 

 

The incremental change in the number of bytes of

 

sent_heartbeat_bytes_change

Heartbeats sent between a local DataWriter and

 

matching remote DataReaders since the last time the

 

 

 

 

status was read.

 

 

 

6-23

Table 6.7 DDS_DataWriterProtocolStatus

Type

Field Name

Description

 

 

 

 

 

 

 

pulled_sample_count

The number of user samples pulled from local

 

DataWriter by matching DataReaders.

 

 

 

 

 

 

 

The incremental change in the number of user samples

 

pulled_sample_count_change

pulled from local DataWriter by matching DataReaders

DDS_LongLong

 

since the last time the status was read.

 

 

pulled_sample_bytes

The number of bytes of user samples pulled from local

 

 

DataWriter by matching DataReaders.

 

 

 

 

 

 

 

The incremental change in the number of bytes of user

 

pulled_sample_bytes_change

samples pulled from local DataWriter by matching

 

 

DataReaders since the last time the status was read.

 

 

 

 

received_ack_count

The number of ACKs from a remote DataReader

 

received by a local DataWriter.

 

 

 

 

 

 

 

The incremental change in the number of ACKs from a

 

received_ack_count_change

remote DataReader received by a local DataWriter since

DDS_LongLong

 

the last time the status was read.

 

 

received_ack_bytes

The number of bytes of ACKs from a remote

 

 

DataReader received by a local DataWriter.

 

 

 

 

 

 

 

The incremental change in the number of bytes of

 

received_ack_bytes_change

ACKs from a remote DataReader received by a local

 

 

DataWriter since the last time the status was read.

 

 

 

 

received_nack_count

The number of NACKs from a remote DataReader

 

received by a local DataWriter.

 

 

 

 

 

 

 

The incremental change in the number of NACKs from

 

received_nack_count_change

a remote DataReader received by a local DataWriter

DDS_LongLong

 

since the last time the status was read.

 

 

received_nack_bytes

The number of bytes of NACKs from a remote

 

 

DataReader received by a local DataWriter.

 

 

 

 

 

 

 

The incremental change in the number of bytes of

 

received_nack_bytes_change

NACKs from a remote DataReader received by a local

 

 

DataWriter since the last time the status was read.

 

 

 

 

sent_gap_count

The number of GAPs sent from local DataWriter to

 

matching remote DataReaders.

 

 

 

 

 

 

 

The incremental change in the number of GAPs sent

 

sent_gap_count_change

from local DataWriter to matching remote DataReaders

DDS_LongLong

 

since the last time the status was read.

 

 

sent_gap_bytes

The number of bytes of GAPs sent from local

 

 

DataWriter to matching remote DataReaders.

 

 

 

 

 

 

 

The incremental change in the number of bytes of

 

sent_gap_bytes_change

GAPs sent from local DataWriter to matching remote

 

 

DataReaders since the last time the status was read.

 

 

 

 

rejected_sample_count

The number of times a sample is rejected for

 

unanticipated reasons in the send path.

 

 

DDS_LongLong

 

 

 

The incremental change in the number of times a

 

rejected_sample_count_change

sample is rejected due to exceptions in the send path

 

 

since the last time the status was read.

 

 

 

DDS_Long

send_window_size

Current maximum number of outstanding samples

allowed in the DataWriter's queue.

 

 

 

 

 

6-24

Table 6.7 DDS_DataWriterProtocolStatus

Type

Field Name

 

Description

 

 

 

 

 

 

 

first_available_sample_

Sequence number of the first available sample in the

 

sequence_number

DataWriter's reliability queue.

 

 

 

 

last_available_sample_

Sequence number of the last available sample in the

 

sequence_number

DataWriter's reliability queue.

 

 

 

 

first_unacknowledged_sample_

Sequence number of the first unacknowledged sample

DDS_Sequence

sequence_number

in the DataWriter's reliability queue.

Number_t

first_available_sample_virtual_

Virtual sequence number of the first available sample

 

sequence_number

in the DataWriter's reliability queue.

 

 

 

 

last_available_sample_virtual_

Virtual sequence number of the last available sample

 

sequence_number

in the DataWriter's reliability queue.

 

 

 

 

first_unacknowledged_sample_virtual_

Virtual sequence number of the first unacknowledged

 

sequence_number

sample in the DataWriter's reliability queue.

 

 

 

 

first_unacknowledged_sample_

Instance Handle of the matching remote DataReader for

 

which the DataWriter has kept the first available

 

subscription_handle

DDS_Sequence

sample in the reliability queue.

 

Number_t

first_unelapsed_keep_duration_

Sequence number

of the first sample kept in the

 

DataWriter's queue

whose keep_duration (applied

 

sample_sequence_number

 

when disable_positive_acks is set) has not yet elapsed.

 

 

 

 

 

 

6.3.6.3LIVELINESS_LOST Status

A change to this status indicates that the DataWriter failed to signal its liveliness within the time specified by the LIVELINESS QosPolicy (Section 6.5.13).

It is different than the RELIABLE_READER_ACTIVITY_CHANGED Status (DDS Extension) (Section 6.3.6.8) status that provides information about the liveliness of a DataWriter’s matched DataReaders; this status reflects the DataWriter’s own liveliness.

The structure for this status appears in Table 6.8 on page 6-25.

Table 6.8 DDS_LivelinessLostStatus

Type

Field Name

Description

 

 

 

 

 

 

DDS_Long

total_count

Cumulative number of times the DataWriter failed to explicitly signal

its liveliness within the liveliness period.

 

 

 

 

 

DDS_Long

total_count_change

The change in total_count since the last time the Listener was called

 

 

or the status was read.

The DataWriterListener’s on_liveliness_lost() callback is invoked when this status changes. You can also retrieve the value by calling the DataWriter’s get_liveliness_lost_status() operation.

6.3.6.4OFFERED_DEADLINE_MISSED Status

A change to this status indicates that the DataWriter failed to write data within the time period set in its DEADLINE QosPolicy (Section 6.5.5).

The structure for this status appears in Table 6.9.

The DataWriterListener’s on_offered_deadline_missed() operation is invoked when this status changes. You can also retrieve the value by calling the DataWriter’s get_deadline_missed_status() operation.

6-25

Table 6.9 DDS_OfferedDeadlineMissedStatus

Type

Field Name

Description

 

 

 

 

 

 

DDS_Long

total_count

Cumulative number of times the DataWriter failed to write

within its offered deadline.

 

 

 

 

 

DDS_Long

total_count_change

The change in total_count since the last time the Listener was

called or the status was read.

 

 

 

 

 

DDS_Instance

last_instance_handle

Handle to the last data-instance in the DataWriter for which an

Handle_t

offered deadline was missed.

 

 

 

 

6.3.6.5OFFERED_INCOMPATIBLE_QOS Status

A change to this status indicates that the DataWriter discovered a DataReader for the same Topic, but that DataReader had requested QoS settings incompatible with this DataWriter’s offered QoS.

The structure for this status appears in Table 6.10.

Table 6.10 DDS_OfferedIncompatibleQoSStatus

Type

Field Name

Description

 

 

 

 

 

 

 

 

Cumulative number of times the DataWriter discovered a

DDS_Long

total_count

DataReader for the same Topic with a requested QoS that is

 

 

incompatible with that offered by the DataWriter.

 

 

 

DDS_Long

total_count_change

The change in total_count since the last time the Listener was

called or the status was read.

 

 

 

 

 

The ID of the QosPolicy that was found to be incompatible the

DDS_QosPolicyId_t

last_policy_id

last time an incompatibility was detected. (Note: if there are

multiple incompatible policies, only one of them is reported

 

 

 

 

here.)

 

 

 

 

 

A list containing—for each policy—the total number of times

DDS_

policies

that the DataWriter discovered a DataReader for the same Topic

QosPolicyCountSeq

with a requested QoS that is incompatible with that offered by

 

 

the DataWriter.

 

 

 

The DataWriterListener’s on_offered_incompatible_qos() changes. You can also retrieve the value get_offered_incompatible_qos_status() operation.

callback is invoked when this status by calling the DataWriter’s

6.3.6.6PUBLICATION_MATCHED Status

A change to this status indicates that the DataWriter discovered a matching DataReader.

A ‘match’ occurs only if the DataReader and DataWriter have the same Topic, same data type (implied by having the same Topic), and compatible QosPolicies. In addition, if user code has directed Connext to ignore certain DataReaders, then those DataReaders will never be matched. See Section 16.4.2 for more on setting up a DomainParticipant to ignore specific DataReaders.

The structure for this status appears in Table 6.11.

The DataWriterListener’s on_publication_matched() callback is invoked when this status changes. You can also retrieve the value by calling the DataWriter’s get_publication_match_status() operation.

6-26

Table 6.11 DDS_PublicationMatchedStatus

Type

Field Name

Description

 

 

 

 

 

 

 

 

 

total_count

Cumulative number of times

the DataWriter discovered a

 

"match" with a DataReader.

 

 

 

 

 

 

 

 

total_count_change

The change in total_count since the last time the Listener was

 

called or the status was read.

 

 

 

 

DDS_Long

 

 

 

current_count

The number of DataReaders

currently matched to the

 

DataWriter.

 

 

 

 

 

 

 

 

current_count_peak

The highest value that current_count has reached until now.

 

 

 

 

current_count_change

The change in current_count since the last time the listener

 

was called or the status was read.

 

 

 

 

 

DDS_Instance

last_subscription_handle

Handle to the last DataReader that matched the DataWriter

Handle_t

causing the status to change.

 

 

 

 

 

6.3.6.7RELIABLE_WRITER_CACHE_CHANGED Status (DDS Extension)

A change to this status indicates that the number of unacknowledged samples1 in a reliable DataWriter's cache has reached one of these trigger points:

The cache is empty (contains no unacknowledged samples)

The cache is full (the number of unacknowledged samples has reached the value specified in DDS_ResourceLimitsQosPolicy::max_samples)

The number of unacknowledged samples has reached a high or low watermark. See the high_watermark and low_watermark fields in Table 6.36 of the DATA_WRITER_PROTOCOL QosPolicy (DDS Extension) (Section 6.5.3).

For more about the reliable protocol used by Connext and specifically, what it means for a sample to be ‘unacknowledged,’ see Chapter 10: Reliable Communications.

 

The structure for

this status appears in

Table 6.12. The

supporting

structure,

 

DDS_ReliableWriterCacheEventCount, is described in Table 6.13.

 

 

 

 

 

Table 6.12 DDS_ReliableWriterCacheChangedStatus

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Type

 

Field Name

 

 

Description

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

empty_reliable_writer_

How many times the reliable DataWriter's cache of

 

 

 

cache

unacknowledged samples has become empty.

 

 

 

 

 

 

 

 

 

 

full_reliable_writer_

How many times the reliable DataWriter's cache of

 

 

 

cache

unacknowledged samples has become full.

 

 

 

 

DDS_ReliableWriter

 

 

 

 

 

 

 

 

 

low_watermark_

How

many times

the reliable

DataWriter's

cache of

 

CacheEventCount

 

unacknowledged

samples

has

fallen

to

the

low

 

 

reliable_writer_cache

 

 

 

watermark.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

high_watermark_

How

many times

the reliable

DataWriter's

cache of

 

 

 

unacknowledged

samples

has

risen to

the

high

 

 

 

reliable_writer_cache

 

 

 

watermark.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

unacknowledged_

The current number of unacknowledged samples in the

 

DDS_Long

 

sample_count

DataWriter's cache.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

unacknowledged_

The highest value that unacknowledged_sample_count

 

 

 

 

 

 

sample_count_peak

has reached until now.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

1. If batching is enabled, this still refers to a number of samples, not batches.

6-27

Table 6.13 DDS_ReliableWriterCacheEventCount

Type

Field Name

Description

 

 

 

 

 

 

DDS_Long

total_count

The total number of times the event has occurred.

 

 

 

DDS_Long

total_count_change

The number of times the event has occurred since the Listener was

last invoked or the status read.

 

 

 

 

 

The DataWriterListener’s on_reliable_writer_cache_changed() status changes. You can also retrieve the value get_reliable_writer_cache_changed_status() operation.

callback is invoked when this by calling the DataWriter’s

6.3.6.8RELIABLE_READER_ACTIVITY_CHANGED Status (DDS Extension)

This status indicates that one or more reliable DataReaders has become active or inactive.

This status is the reciprocal status to the LIVELINESS_CHANGED Status (Section 7.3.7.4) on the DataReader. It is different than LIVELINESS_LOST Status (Section 6.3.6.3) status on the DataWriter, in that the latter informs the DataWriter about its own liveliness; this status informs the DataWriter about the liveliness of its matched DataReaders.

A reliable DataReader is considered active by a reliable DataWriter with which it is matched if that DataReader acknowledges the samples that it has been sent in a timely fashion. For the definition of "timely" in this context, see DATA_WRITER_PROTOCOL QosPolicy (DDS Extension) (Section 6.5.3).

This status is only used for DataWriters whose RELIABILITY QosPolicy (Section 6.5.19) is set to RELIABLE. For best-effort DataWriters, all counts in this status will remain at zero.

The structure for this status appears in Table 6.14.

Table 6.14 DDS_ReliableReaderActivityChangedStatus

Type

Field Name

Description

 

 

 

 

 

 

 

active_count

The current number of reliable readers currently matched with

 

this reliable DataWriter.

 

 

 

 

 

 

 

The number of reliable readers that have been dropped by this

 

not_active_count

reliable DataWriter because they failed to send

DDS_Long

 

acknowledgements in a timely fashion.

 

active_count_change

The change in the number of active reliable DataReaders since the

 

Listener was last invoked or the status read.

 

 

 

 

 

 

inactive_count_change

The change in the number of inactive reliable DataReaders since

 

 

the Listener was last invoked or the status read.

DDS_Instance

last_instance_handle

The instance handle of the last reliable DataReader to be

Handle_t

 

determined to be inactive.

The DataWriterListener’s on_reliable_reader_activity_changed() callback is invoked when this status changes. You can also retrieve the value by calling the DataWriter’s get_reliable_reader_activity_changed_status() operation.

6.3.7Using a Type-Specific DataWriter (FooDataWriter)

Recall that a Topic is bound to a data type that specifies the format of the data associated with the Topic. Data types are either defined dynamically or in code generated from definitions in IDL or XML; see Chapter 3: Data Types and Data Samples. For each of your application's generated data types, such as 'Foo', there will be a FooDataWriter class (or a set of functions in C). This class allows the application to use a type-safe interface to interact with samples of type 'Foo'.

6-28

You will use the FooDataWriter's write() operation used to send data. For dynamically defined data-types, you will use the DynamicDataWriter class.

In fact, you will use the FooDataWriter any time you need to perform type-specific operations, such as registering or writing instances. Table 6.3 indicates which operations must be called using FooDataWriter. For operations that are not type-specific, you can call the operation using either a FooDataWriter or a DDSDataWriter object1.

You may notice that the Publisher’s create_datawriter() operation returns a pointer to an object of type DDSDataWriter; this is because the create_datawriter() method is used to create DataWriters of any data type. However, when executed, the function actually returns a specialization (an object of a derived class) of the DataWriter that is specific for the data type of the associated Topic. For a Topic of type ‘Foo’, the object actually returned by create_datawriter() is a FooDataWriter.

To safely cast a generic DDSDataWriter pointer to a FooDataWriter pointer, you should use the static narrow() method of the FooDataWriter class. The narrow() method will return NULL if the generic DDSDataWriter pointer is not pointing at an object that is really a FooDataWriter.

For instance, if you create a Topic bound to the type ‘Alarm’, all DataWriters created for that Topic will be of type ‘AlarmDataWriter.’ To access the type-specific methods of AlarmDataWriter, you must cast the generic DDSDataWriter pointer returned by create_datawriter(). For example:

DDSDataWriter* writer = publisher->create_datawriter(topic,writer_qos, NULL, NULL);

AlarmDataWriter *alarm_writer = AlarmDataWriter::narrow(writer); if (alarm_writer == NULL) {

// ... error

};

In the C API, there is also a way to do the opposite of narrow(). FooDataWriter_as_datawriter() casts a FooDataWriter as a DDSDataWriter, and FooDataReader_as_datareader() casts a FooDataReader as a DDSDataReader.

6.3.8Writing Data

The write() operation informs Connext that there is a new value for a data-instance to be published for the corresponding Topic. By default, calling write() will send the data immediately over the network (assuming that there are matched DataReaders). However, you can configure and execute operations on the DataWriter’s Publisher to buffer the data so that it is sent in a batch with data from other DataWriters or even to prevent the data from being sent. Those sending “modes” are configured using the PRESENTATION QosPolicy (Section 6.4.6) as well as the Publisher’s suspend/resume_publications() operations. The actual transport-level communications may be done by a separate, lower-priority thread when the Publisher is configured to send the data for its DataWriters. For more information on threads, see Chapter 19: Connext Threading Model.

When you call write(), Connext automatically attaches a stamp of the current time that is sent with the data sample to the DataReader(s). The timestamp appears in the source_timestamp field of the DDS_SampleInfo structure that is provided along with your data using DataReaders (see The SampleInfo Structure (Section 7.4.6)).

DDS_ReturnCode_t write (const Foo &instance_data,

const DDS_InstanceHandle_t &handle)

You can use an alternate DataWriter operation called write_w_timestamp(). This performs the same action as write(), but allows the application to explicitly set the source_timestamp. This is

1. In the C API, the non type-specific operations must be called using a DDS_DataWriter pointer.

6-29

useful when you want the user application to set the value of the timestamp instead of the default clock used by Connext.

DDS_ReturnCode_t write_w_timestamp (const Foo &instance_data, const DDS_InstanceHandle_t &handle, const DDS_Time_t &source_timestamp)

Note that, in general, the application should not mix these two ways of specifying timestamps. That is, for each DataWriter, the application should either always use the automatic timestamping mechanism (by calling the normal operations) or always specify a timestamp (by calling the “w_timestamp” variants of the operations). Mixing the two methods may result in not receiving sent data.

You can also use an alternate DataWriter operation, write_w_params(), which performs the same action as write(), but allows the application to explicitly set the fields contained in the DDS_WriteParams structure, see Table 6.15 on page 6-30.

Table 6.15 DDS_WriteParams_t

Type

Field Name

 

 

 

Description

 

 

 

 

 

 

 

 

 

 

 

Allows retrieving the actual value of those fields that were

 

 

automatic.

 

 

 

 

 

 

DDS_Boolean

replace_auto

When this field is set to true, the fields that were configured

with

an

automatic

value

(for

example,

 

 

 

 

DDS_AUTO_SAMPLE_IDENTITY in identity) receive their

 

 

actual value after write_w_params is called.

 

 

 

 

 

 

 

 

Identity of the sample being written. The identity consists of a

 

 

pair (Virtual Writer GUID, Virtual Sequence Number).

 

 

 

When the value DDS_AUTO_SAMPLE_IDENTITY is used, the

 

 

write_w_params() operation will determine the sample

 

 

identity as follows:

 

 

 

 

 

 

 

The Virtual Writer GUID (writer_guid) is the virtual

 

 

 

GUID associated with the DataWriter writing the

 

 

 

sample. This virtual GUID is configured using the

 

 

 

member

 

 

virtual_guid

 

 

in

DDS_

identity

 

DATA_WRITER_PROTOCOL_STATUS (Section 6.3.6.2).

The Virtual

 

 

 

 

 

SampleIdentity_t

Sequence Number (sequence_number) is

 

 

 

 

increased by one with respect to the previous value.

 

 

 

The virtual sequence numbers for a given virtual GUID must be

 

 

strictly monotonically increasing. If you try to write a sample

 

 

with a sequence number smaller or equal to the last sequence

 

 

number, the write operation will fail.

 

 

 

 

 

A DataReader can inspect the identity of a received sample by

 

 

accessing the fields original_publication_virtual_guid and

 

 

original_publication_virtual_sequence_number

in

The

 

 

SampleInfo Structure (Section 7.4.6).

 

 

 

 

 

 

 

 

 

 

 

 

 

6-30

Table 6.15 DDS_WriteParams_t

Type

Field Name

 

 

Description

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

The identity of another sample related to this one.

 

 

 

 

The value of this field identifies another sample that is logically

 

 

related to the one that is written.

 

 

 

 

 

 

For example, the DataWriter created by a Replier (sets

 

 

Chapter 22: Introduction to the Request-Reply Communication

 

 

Pattern) uses this field to associate the identity of the request

DDS_

related_sample_

sample to reponse sample.

 

 

 

 

 

SampleIdentity_t

identity

To specify that there is no related sample identity use the value

 

 

DDS_UNKNOWN_SAMPLE_IDENTITY,

 

 

 

 

 

A DataReader can inspect the related sample identity of a

 

 

received

sample

by

 

accessing

the

fields

 

 

related_original_publication_virtual_guid

 

 

and

 

 

related_original_publication_virtual_sequence_number

 

in

 

 

The SampleInfo Structure (Section 7.4.6).

 

 

 

 

 

 

 

 

Source timestamp that will be associated to the sample that is

 

 

written.

 

 

 

 

 

 

 

 

 

If source_timestamp is set to DDS_TIMER_INVALID, the

DDS_Time

source_timestamp

middleware will assign the value.

 

 

 

 

 

 

A DataReader can inspect the source_timestamp value of a

 

 

received sample by accessing the field source_timestamp

The

 

 

SampleInfo Structure (Section 7.4.6).

 

 

 

 

 

 

 

 

 

 

 

 

DDS_

 

The instance handle.

 

 

 

 

 

 

handle

This value can be either the handle returned by a previous call

InstanceHandle_t

 

to register_instance or the special value DDS_HANDLE_NIL.

 

 

 

 

 

 

 

Positive integer designating the relative priority of the sample,

 

 

used to determine the transmission order of pending

 

 

transmissions.

 

 

 

 

 

 

 

 

To use publication priorities, the DataWriter’s PUBLISH_MODE

 

 

QosPolicy (DDS Extension) (Section 6.5.18) must be set for

 

 

asynchronous publishing and the DataWriter must use a

DDS_Long

priority

FlowController

with

a

highest-priority

 

first

 

 

scheduling_policy.

 

 

 

 

 

 

 

 

For Multi-channel DataWriters, the publication priority of

 

 

a sample may be used as a filter criteria for determining

 

 

channel membership.

 

 

 

 

 

 

 

For additional information in Priority Samples see Prioritized

 

 

Samples (Section 6.6.4).

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Note: Prioritized samples are not supported when using the Java, Ada, or .NET APIs. Therefore the priority field in DDS_WriteParams_t does not exist when using these APIs.

When using the C API, a newly created variable of type DDS_WriteParams_t should be initialized by setting it to DDS_WRITEPARAMS_DEFAULT.

The write() operation also asserts liveliness on the DataWriter, the associated Publisher, and the associated DomainParticipant. It has the same effect with regards to liveliness as an explicit call to assert_liveliness(), see Section 6.3.17 and the LIVELINESS QosPolicy (Section 6.5.13). Maintaining liveliness is important for DataReaders to know that the DataWriter still exists and for the proper behavior of the OWNERSHIP QosPolicy (Section 6.5.15).

See also: Clock Selection (Section 8.6).

6.3.8.1Blocking During a write()

The write() operation may block if the RELIABILITY QosPolicy (Section 6.5.19) kind is set to Reliable and the modification would cause data to be lost or cause one of the limits specified in

6-31

the RESOURCE_LIMITS QosPolicy (Section 6.5.20) to be exceeded. Specifically, write() may block in the following situations (note that the list may not be exhaustive), even if its HISTORY QosPolicy (Section 6.5.10) is KEEP_LAST:

If max_samples1 < max_instances, then the DataWriter may block regardless of the depth field in the HISTORY QosPolicy (Section 6.5.10).

If max_samples < (max_instances * depth), then in the situation where the max_samples resource limit is exhausted, Connext may discard samples of some other instance, as long as at least one sample remains for such an instance. If it is still not possible to make space available to store the modification, the writer is allowed to block.

If min_send_window_size < max_samples), then it is possible for the send_window_size limit to be reached before Connext is allowed to discard samples, in which case the DataWriter will block.

This operation may also block when using BEST_EFFORT Reliability (Section 6.5.20) and ASYNCHRONOUS Publish Mode (Section 6.5.18) QoS settings. In this case, the DataWriter will queue samples until they are sent by the asynchronous publishing thread. The number of samples that can be stored is determined by the HISTORY QosPolicy (Section 6.5.10). If the asynchronous thread does not send samples fast enough (such as when using a slow FlowController (Section 6.6)), the queue may fill up. In that case, subsequent write calls will block.

If this operation does block for any of the above reasons, the RELIABILITY max_blocking_time configures the maximum time the write operation may block (waiting for space to become available). If max_blocking_time elapses before the DataWriter can store the modification without exceeding the limits, the operation will fail and return RETCODE_TIMEOUT.

6.3.9Flushing Batches of Data Samples

The flush() operation makes a batch of data samples available to be sent on the network.

DDS_ReturnCode_t flush ()

If the DataWriter’s PUBLISH_MODE QosPolicy (DDS Extension) (Section 6.5.18) kind is not ASYNCHRONOUS, the batch will be sent on the network immediately in the context of the calling thread.

If the DataWriter’s PublishModeQosPolicy kind is ASYNCHRONOUS, the batch will be sent in the context of the asynchronous publishing thread.

The flush() operation may block based on the conditions described in Blocking During a write() (Section 6.3.8.1).

If this operation does block, the max_blocking_time in the RELIABILITY QosPolicy (Section 6.5.19) configures the maximum time the write operation may block (waiting for space to become available). If max_blocking_time elapses before the DataWriter is able to store the modification without exceeding the limits, the operation will fail and return TIMEOUT.

For more information on batching, see the BATCH QosPolicy (DDS Extension) (Section 6.5.2).

6.3.10Writing Coherent Sets of Data Samples

A publishing application can request that a set of data-sample changes be propagated in such a way that they are interpreted at the receivers' side as a cohesive set of modifications. In this case, the receiver will only be able to access the data after all the modifications in the set are available at the subscribing end.

This is useful in cases where the values are inter-related. For example, suppose you have two data-instances representing the ‘altitude’ and ‘velocity vector’ of the same aircraft. If both are

1.max_samples in is DDS_ResourceLimitsQosPolicy

6-32

changed, it may be important to ensure that reader see both together (otherwise, it may erroneously interpret that the aircraft is on a collision course).

To use this mechanism:

1.Call the Publisher’s begin_coherent_changes() operation to indicate the start a coherent set.

2.For each sample in the coherent set: call the FooDataWriter’s write() operation.

3.Call the Publisher’s end_coherent_changes() operation to terminate the set.

Calls to begin_coherent_changes() and end_coherent_changes() can be nested.

See also: the coherent_access field in the PRESENTATION QosPolicy (Section 6.4.6).

6.3.11Waiting for Acknowledgments in a DataWriter

The DataWriter’s wait_for_acknowledgments() operation blocks the calling thread until either all data written by the reliable DataWriter is acknowledged by (a) all reliable DataReaders that are matched and alive and (b) by all required subscriptions (see Required Subscriptions (Section 6.3.13)), or until the duration specified by the max_wait parameter elapses, whichever happens first.

Note that if a thread is blocked in the call to wait_for_acknowledgments() on a DataWriter and a different thread writes new samples on the same DataWriter, the new samples must be acknowledged before unblocking the thread waiting on wait_for_acknowledgments().

DDS_ReturnCode_t wait_for_acknowledgments (

const DDS_Duration_t & max_wait)

This operation returns DDS_RETCODE_OK if all the samples were acknowledged, or

DDS_RETCODE_TIMEOUT if the max_wait duration expired first.

If the DataWriter does not have its RELIABILITY QosPolicy (Section 6.5.19) kind set to RELIABLE, the operation will immediately return DDS_RETCODE_OK.

There is a similar operation available at the Publisher level, see Waiting for Acknowledgments in a Publisher (Section 6.2.7).

The reliability protocol used by Connext is discussed in Chapter 10: Reliable Communications. The application acknowledgment mechanism is discussed in Application Acknowledgment (Section 6.3.12) and Chapter 13: Guaranteed Delivery of Data.

6.3.12Application Acknowledgment

The RELIABILITY QosPolicy (Section 6.5.19) determines whether or not data published by a DataWriter will be reliably delivered by Connext to matching DataReaders. The reliability protocol used by Connext is discussed in Chapter 10: Reliable Communications.

With protocol-level reliability alone, the producing application knows that the information is received by the protocol layer on the consuming side. However, the producing application cannot be certain that the consuming application read that information or was able to successfully understand and process it. The information could arrive in the consumer’s protocol stack and be placed in the DataReader cache but the consuming application could either crash before it reads it from the cache, not read its cache, or read the cache using queries or conditions that prevent that particular data sample from being accessed. Furthermore, the consuming application could access the sample, but not be able to interpret its meaning or process it in the intended way.

The mechanism to let a DataWriter know to keep the sample around, not just until it has been acknowledged by the reliability protocol, but until the application has been able to process the sample is aptly called Application Acknowledgment. A reliable DataWriter will keep the samples until the application acknowledges the samples. When the subscriber application is restarted,

6-33

the middleware will know that the application did not acknowledge successfully processing the samples and will resend them.

6.3.12.1Application Acknowledgment Kinds

Connext supports three kinds of application acknowledgment, which is configured in the RELIABILITY QosPolicy (Section 6.5.19)):

1.DDS_PROTOCOL_ACKNOWLEDGMENT_MODE (Default): In essence, this mode is identical to using no application-level acknowledgment. Samples are acknowledged according to the Real-Time Publish-Subscribe (RTPS) reliability protocol. RTPS AckNack messages will acknowledge that the middleware received the sample.

2.DDS_APPLICATION_AUTO_ACKNOWLEDGMENT_MODE: Samples are automatically acknowledged by the middleware after the subscribing application accesses them, either through calling take() or read() on the sample. The samples are acknowledged after return_loan() is called.

3.DDS_APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE: Samples are acknowledged after the subscribing application explicitly calls acknowledge on the sample. This can be done by either calling the DataReader’s acknowledge_sample() or acknowledge_all() operations. When using acknowledge_sample(), the application will provide the DDS_SampleInfo to identify the sample being acknowledge. When using acknowledge_all, all the samples that have been read or taken by the reader will be acknowledged.

Note: Even in DDS_APPLICATION_EXPLICIT_ACKNOWLEDGMENT_MODE, some samples may be automatically acknowledged. This is the case when samples are filtered out by the reader using time-based filter, or using content filters. Additionally, when the reader is explicitly configured to use KEEP_LAST history kind, samples may be replaced in the reader queue due to resource constraints. In that case, the sample will be automat- ically acknowledged by the middleware if it has not been read by the application before it was replaced. To truly guarantee successful processing of samples, it is recommended to use KEEP_ALL history kind.

6.3.12.2Explicitly Acknowledging a Single Sample (C++)

void MyReaderListener::on_data_available(DDSDataReader *reader)

{

Foo sample; DDS_SampleInfo info;

FooDataReader* fooReader = FooDataReader::narrow(reader); DDS_ReturnCode_t retcode = fooReader->take_next_sample(sample, info); if (retcode == DDS_RETCODE_OK) {

if (info.valid_data) { // Process sample

..

retcode = reader->acknowledge_sample(info); if (retcode != DDS_RETCODE_OK) {

// Error

}

}

}else {

//Not OK or NO DATA

}

6.3.12.3Explicitly Acknowledging All Samples (C++)

void MyReaderListener::on_data_available(DDSDataReader *reader)

{

...

// Loop while samples available

6-34

for(;;) {

retcode = string_reader->take_next_sample(sample, info); if (retcode == DDS_RETCODE_NO_DATA) {

// No more samples break;

}

// Process sample

...

}

retcode = reader->acknowledge_all(); if (retcode != DDS_RETCODE_OK) {

// Error

}

}

6.3.12.4Notification of Delivery with Application Acknowledgment

A DataWriter can use the wait_for_acknowledgments() operation to be notified when all the samples in the DataWriter’s queue have been acknowledged. See Waiting for Acknowledgments in a DataWriter (Section 6.3.11).

retCode = fooWriter->write(sample, DDS_HANDLE_NIL); if (retCode != DDS_RETCODE_OK) {

// Error

}

retcode = writer->wait_for_acknowledgments(timeout); if (retCode != DDS_RETCODE_OK) {

if (retCode != DDS_RETCODE_TIMEOUT) {

//Timeout: Sample not acknowledged yet

}else {

//Error

}

}

Connext does not provide a way to get delivery notifications on a per DataReader and sample basis. If your application requires acknowledgment of message receipt, use the Request/Reply communication pattern with an Acknowledgment type (see Chapter 22: Introduction to the Request-Reply Communication Pattern).

6.3.12.5Application-Level Acknowledgment Protocol

When the subscribing application confirms it has successfully processed a sample, an AppAck RTPS message is sent to the publishing application. This message will be resent until the

6-35

publishing application confirms receipt of the AppAck message by sending an AppAckConf RTPS message. See Figures 6.10 through 6.12.

Figure 6.10 AppAck RTPS Messages Sent when Application Acknowledges a Sample

6.3.12.6Periodic and Non-Periodic AppAck Messages

You can configure whether AppAck RTPS messages are sent immediately or periodically through the DATA_READER_PROTOCOL QosPolicy (DDS Extension) (Section 7.6.1 on page 7- 50). The samples_per_app_ack (in Table 7.20, “DDS_RtpsReliableReaderProtocol_t,” on page 7- 52) determines the minimum number of samples acknowledged by one application-level Acknowledgment message. The middleware will not send an AppAck message until it has at least this many samples pending acknowledgment. By default, samples_per_app_ack is 1 and the AppAck RTPS message is sent immediately. Independently, the app_ack_period (in

6-36

Figure 6.11 AppAck RTPS Messages Resent Until Acknowledged Through AppAckConf RTPS Message

Table 7.20, “DDS_RtpsReliableReaderProtocol_t,” on page 7-52) determines the rate at which a DataReader will send AppAck messages.

6.3.12.7Application Acknowledgment and Persistence Service

Application Acknowledgment is fully supported by RTI Persistence Service. The combination of Application Acknowledgment and Persistence Service is actually a common configuration. In addition to keeping samples available until fully acknowledged, Persistence Service, when used in peer-to-peer mode, can take advantage of AppAck messages to avoid sending duplicate messages to the subscribing application. Because AppAck messages are sent to all matching

6-37

Figure 6.12 AppAck RTPS Messages Sent as a Sequence of Intervals, Combined to Optimize for Bandwidth

6-38

writers, when the subscriber acknowledges the original publisher, Persistence Service will also be notified of this event and will not send out duplicate messages. This is illustrated in Figure 6.13.

Figure 6.13 Application Acknowledgment and Persistence Service

A single AppAck notifies both the original DataWriter and Persistence Service.

 

AppAck

DataWriter

Global

 

Dataspace

AppAck

Persistence Service

(Peer-to-Peer mode)

AppAck

DataReader

Samples acknowledged to the Original DataWriter are not sent by the Persistence service.

6.3.12.8Application Acknowledgment and Routing Service

Application Acknowledgment is supported by RTI Routing Service: That is, Routing Service will acknowledge the sample it has processed. Routing Service is an active participant in the Connext system and not transparent to the publisher or subscriber. As such, Routing Service will acknowledge to the publisher, and the subscriber will acknowledge to Routing Service. However, the publisher will not get a notification from the subscriber directly.

6.3.13Required Subscriptions

The DURABILITY QosPolicy (Section 6.5.7) specifies whether acknowledged samples need to be kept in the DataWriter’s queue and made available to late-joining applications. When a late joining application is discovered, available samples will be sent to the late joiner. With the Durability QoS alone, there is no way to specify or characterize the intended consumers of the information and the user does not have control over which samples will be kept for late-joining applications. If while waiting for late-joining applications, the middleware needs to free up samples, it will reclaim samples if they have been previously acknowledged by active/matching readers.

There are scenarios where you know a priori that a particular set of applications will join the system: e.g., a logging service or a known processing application. The Required Subscription feature is designed to keep data until these known late joining applications acknowledge the data.

Another use case is when DataReaders become temporarily inactive due to not responding to heartbeats, or when the subscriber temporarily became disconnected and purged from the discovery database. In both cases, the DataWriter will no longer keep the sample for this

DataReader. The Required Subscription feature will keep the data until these known DataReaders have acknowledged the data.

6-39

To use Required Subscriptions, the DataReaders and DataWriters must have their RELIABILITY QosPolicy (Section 6.5.19) kind set to RELIABLE.

6.3.13.1Named, Required and Durable Subscriptions

Before describing the Required Subscriptions, it is important to understand a few concepts:

Named Subscription: Through the ENTITY_NAME QosPolicy (DDS Extension) (Section 6.5.9), each DataReader can be given a specific name. This name can be used by tools to identify a specific DataReader. Additionally, the DataReader can be given a role_name. For example: LOG_APP_1 DataReader belongs to the logger applications (role_name = “LOGGER”).

Required Subscription is a named subscription to which a DataWriter is configured to deliver data to. This is true even if the DataReaders serving those subscriptions are not available yet. The DataWriter must store the sample until it has been acknowledged by all active reliable DataReaders and acknowledged by all required subscriptions. The DataWriter is not waiting for a specific DataReader, rather it is waiting for DataReaders belonging to the required subscription by setting their role_name to the subscription name.

Durable Subscription is a required subscription where samples are stored and forwarded by an external service. In this case, the required subscription is served by RTI Persistence Service. See Configuring Durable Subscriptions in Persistence Service (Section 27.9).

6.3.13.2Durability QoS and Required Subscriptions

The DURABILITY QosPolicy (Section 6.5.7) and the Required Subscriptions feature complement each other.

The DurabilityQosPolicy determines whether or not Connext will store and deliver previously acknowledged samples to new DataReaders that join the network later. You can specify to either not make the samples available (DDS_VOLATILE_DURABILITY_QOS kind), or to make them available and declare you are storing the samples in memory (DDS_TRANSIENT_LOCAL_DURABILITY_QOS or DDS_TRANSIENT_DURABILITY_QOS kind) or in permanent storage (DDS_PERSISTENT_DURABILITY_QOS).

Required subscriptions help answer the question of when a sample is considered acknowledged before the DurabilityQosPolicy determines whether to keep it. When required subscriptions are used, a sample is considered acknowledged by a DataWriter when both the active DataReaders and a quorum of required subscriptions have acknowledged the sample. (Acknowledging a sample can be done either at the protocol or application level—see Application Acknowledgment (Section 6.3.12)).

6.3.13.3Required Subscriptions Configuration

Each DataReader can be configured to be part of a named subscription, by giving it a role_name using the ENTITY_NAME QosPolicy (DDS Extension) (Section 6.5.9). A DataWriter can then be configured using the AVAILABILITY QosPolicy (DDS Extension) (Section 6.5.1) (required_matched_endpoint_groups) with a list of required named subscriptions identified by the role_name. Additionally, the DataWriter can be configured with a quorum or minimum number of DataReaders from a given named subscription that must receive a sample.

When configured with a list of required subscriptions, a DataWriter will store a sample until the sample is acknowledged by all active reliable DataReaders, as well as all required subscriptions. When a quorum is specified, a minimum number of DataReaders of the required subscription must acknowledge a sample in order for the sample to be considered acknowledged. Specifying a quorum provides a level of redundancy in the system as multiple applications or services acknowledge they have received the sample. Each individual DataReader is identified using its

6-40

own virtual GUID (see DATA_READER_PROTOCOL QosPolicy (DDS Extension) (Section 7.6.1)).

6.3.14Managing Data Instances (Working with Keyed Data Types)

This section applies only to data types that use keys, see Samples, Instances, and Keys (Section 2.2.2). Using the following operations for non-keyed types has no effect.

Topics come in two flavors: those whose associated data type has specified some fields as defining the ‘key,’ and those whose associated data type has not. An example of a data-type that specifies key fields is shown in Figure 6.14.

Figure 6.14 Data Type with a Key

typedef struct Flight { long flightId; //@key string departureAirport; string arrivalAirport; Time_t departureTime;

Time_t estimatedArrivalTime; Location_t currentPosition;

};

If the data type has some fields that act as a ‘key,’ the Topic essentially defines a collection of data-instances whose values can be independently maintained. In Figure 6.14, the flightId is the ‘key’. Different flights will have different values for the key. Each flight is an instance of the Topic. Each write() will update the information about a single flight. DataReaders can be informed when new flights appear or old ones disappear.

Since the key fields are contained within the data structure, Connext could examine the key fields each time it needs to determine which data-instance is being modified. However, for performance and semantic reasons, it is better for your application to declare all the data- instances it intends to modify—prior to actually writing any samples. This is known as registration, described below in Section 6.3.14.1.

The register_instance() operation provides a handle to the instance (of type DDS_InstanceHandle_t) that can be used later to refer to the instance.

6.3.14.1Registering and Unregistering Instances

If your data type has a key, you may improve performance by registering an instance (data associated with a particular value of the key) before you write data for the instance. You can do this for any number of instances up the maximum number of instances configured in the DataWriter’s RESOURCE_LIMITS QosPolicy (Section 6.5.20). Instance registration is completely optional.

Registration tells Connext that you are about to modify (write or dispose of) a specific instance. This allows Connext to pre-configure itself to process that particular instance, which can improve performance.

If you write without registering, you can pass the NIL instance handle as part of the write() call.

If you register the instance first, Connext can look up the instance beforehand and return a handle to that instance. Then when you pass this handle to the write() operation, Connext no longer needs to analyze the data to check what instance it is for. Instead, it can directly update the instance pointed to by the instance handle.

In summary, by registering an instance, all subsequent write() calls to that instance become more efficient. If you only plan to write once to a particular instance, registration does not ‘buy’ you much in performance, but in general, it is good practice.

To register an instance, use the DataWriter’s register_instance() operation. For best performance, it should be invoked prior to calling any operation that modifies the instance, such as write(), write_w_timestamp(), dispose(), or dispose_w_timestamp().

6-41

When you are done using that instance, you can unregister it. To unregister an instance, use the DataWriter’s unregister_instance() operation. Unregistering tells Connext that the DataWriter does not intend to modify that data-instance anymore, allowing Connext to recover any resources it allocated for the instance. It does not delete the instance; that is done with the dispose_instance() operation, see Section 6.3.14.2. unregister_instance() should only be used on instances that have been previously registered. The use of these operations is illustrated in Figure 6.15.

Figure 6.15 Registering an Instance

Flight myFlight;

// writer is a previously-created FlightDataWriter myFlight.flightId = 265;

DDS_InstanceHandle_t fl265Handle = writer->register_instance(myFlight);

...

// Each time we update the flight, we can pass the handle

myFlight.departureAirport

= “SJC”;

myFlight.arrivalAirport

= “LAX”;

myFlight.departureTime

= {120000, 0};

myFlight.estimatedArrivalTime

=

{130200, 0};

myFlight.currentPosition

=

{ {37, 20}, {121, 53} };

if (writer->write(myFlight, fl265Handle) != DDS_RETCODE_OK) { // ... handle error

}

...

// Once we are done updating the flight, it can be unregistered if (writer->unregister_instance(myFlight, fl265Handle) !=

DDS_RETCODE_OK) { // ... handle error

}

Once an instance has been unregistered, and assuming that no other DataWriters are writing values for the instance, the matched DataReaders will eventually get an indication that the instance no longer has any DataWriters. This is communicated to the DataReaders by means of the DDS_SampleInfo that accompanies each data-sample (see Section 7.4.6). Once there are no DataWriters for the instance, the DataReader will see the value of DDS_InstanceStateKind for that instance to be NOT_ALIVE_NO_WRITERS.

The unregister_instance() operation may affect the ownership of the data instance (see the OWNERSHIP QosPolicy (Section 6.5.15)). If the DataWriter was the exclusive owner of the instance, then calling unregister_instance() relinquishes that ownership, and another DataWriter can become the exclusive owner of the instance.

The unregister_instance() operation indicates only that a particular DataWriter no longer has anything to say about the instance.

Note that this is different than the dispose() operation discussed in the next section, which informs DataReaders that the data-instance is no longer “alive.” The state of an instance is stored in the DDS_SampleInfo structure that accompanies each sample of data that is received by a DataReader. User code can access the instance state to see if an instance is “alive”—meaning there is at least one DataWriter that is publishing samples for the instance, see Instance States (Section 7.4.6.4).

6-42

6.3.14.2Disposing of Data

The dispose() operation informs DataReaders that, as far as the DataWriter knows, the data- instance no longer exists and can be considered “not alive.” When the dispose() operation is called, the instance state stored in the DDS_SampleInfo structure, accessed through DataReaders, will change to NOT_ALIVE_DISPOSED for that particular instance.

autodispose_unregistered_instances in the WRITER_DATA_LIFECYCLE QoS Policy (Section 6.5.26) controls whether instances are automatically disposed when they are unregistered.

For example, in a flight tracking system, when a flight lands, a DataWriter may dispose the data- instance corresponding to the flight. In that case, all DataReaders who are monitoring the flight will see the instance state change to NOT_ALIVE_DISPOSED, indicating that the flight has landed.

Note that this is different than unregister_instance() (Section 6.3.14.1), which indicates only that a particular DataWriter no longer wishes to modify an instance—an important distinction if there are multiple writers on the same instance.

If a particular instance is never disposed, its instance state will eventually change from ALIVE to NOT_ALIVE_NO_WRITERS once all the DataWriters that were writing that instance unregister the instance or lose their liveliness. For more information on DataWriter liveliness, see the LIVELINESS QosPolicy (Section 6.5.13).

See also: Propagating Serialized Keys with Disposed-Instance Notifications (Section 6.5.3.5).

6.3.14.3Looking Up an Instance Handle

Some operations, such as write(), require an instance_handle parameter. If you need to get such as handle, you can call the FooDataWriter’s lookup_instance() operation, which takes an instance as a parameter and returns a handle to that instance. This is useful for keyed data types.

DDS_InstanceHandle_t lookup_instance (const Foo & key_holder)

The instance must have already been registered (see Section 6.3.14.1). If the instance is not registered, this operation returns DDS_HANDLE_NIL.

6.3.14.4Getting the Key Value for an Instance

Once you have an instance handle (using register_instance() or lookup_instance()), you can use the DataWriter’s get_key_value() operation to retrieve the value of the key of the corresponding instance. The key fields of the data structure passed into get_key_value() will be filled out with the original values used to generate the instance handle. The key fields are defined when the data type is defined, see Samples, Instances, and Keys (Section 2.2.2) for more information.

Following our example in Figure 6.15 on page 6-42, register_instance() returns a

DDS_InstanceHandle_t (fl265Handle) that can be used in the call to the FlightDataWriter’s get_key_value() operation. The value of the key is returned in a structure of type Flight with the flightId field filled in with the integer 265.

See also: Propagating Serialized Keys with Disposed-Instance Notifications (Section 6.5.3.5).

6.3.15Setting DataWriter QosPolicies

The DataWriter’s QosPolicies control its resources and behavior.

The DDS_DataWriterQos structure has the following format:

DDS_DataWriterQos struct {

 

DDS_DurabilityQosPolicy

durability;

DDS_DurabilityServiceQosPolicy

durability_service;

DDS_DeadlineQosPolicy

deadline;

DDS_LatencyBudgetQosPolicy

latency_budget;

DDS_LivelinessQosPolicy

liveliness;

DDS_ReliabilityQosPolicy

reliability;

6-43

DDS_DestinationOrderQosPolicy

destination_order;

DDS_HistoryQosPolicy

history;

DDS_ResourceLimitsQosPolicy

resource_limits;

DDS_TransportPriorityQosPolicy

transport_priority;

DDS_LifespanQosPolicy

lifespan;

DDS_UserDataQosPolicy

user_data;

DDS_OwnershipQosPolicy

ownership;

DDS_OwnershipStrengthQosPolicy

ownership_strength;

DDS_WriterDataLifecycleQosPolicy

writer_data_lifecycle;

// extensions to the DDS standard: DDS_DataWriterResourceLimitsQosPolicy writer_resource_limits;

DDS_DataWriterProtocolQosPolicy

protocol;

DDS_TransportSelectionQosPolicy

transport_selection;

DDS_TransportUnicastQosPolicy

unicast;

DDS_PublishModeQosPolicy

publish_mode;

DDS_PropertyQosPolicy

property;

DDS_BatchQosPolicy

batch;

DDS_MultiChannelQosPolicy

multi_channel;

DDS_AvailabilityQosPolicy

availability;

DDS_EntityNameQosPolicy

publication_name;

DDS_TypeSupportQosPolicy

type_support;

} DDS_DataWriterQos;

 

Note: set_qos() cannot always be used within a listener callback, see Restricted Operations in Listener Callbacks (Section 4.5.1).

Table 6.16 summarizes the meaning of each policy. (They appear alphabetically in the table.) For information on why you would want to change a particular QosPolicy, see the referenced section. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 6.16 DataWriter QosPolicies

QosPolicy

Description

 

 

 

 

 

This QoS policy is used in the context of two features:

 

Availability QoS Policy and Collaborative DataWriters (Section 6.5.1.1)

 

Availability QoS Policy and Required Subscriptions (Section 6.5.1.2)

 

For Collaborative DataWriters, Availability specifies the group of

Availability

DataWriters expected to collaboratively provide data and the timeouts that

 

control when to allow data to be available that may skip samples.

 

For Required Subscriptions, Availability configures a set of Required

 

Subscriptions on a DataWriter.

 

See Section 6.5.1

 

 

 

Specifies and configures the mechanism that allows Connext to collect

Batch

multiple user data samples to be sent in a single network packet, to take

advantage of the efficiency of sending larger packets and thus increase

 

 

effective throughput. See Section 6.5.2.

 

 

DataWriterProtocol

This QosPolicy configures the Connext on-the-network protocol, RTPS. See

Section 6.5.3.

 

 

 

DataWriterResourceLimits

Controls how many threads can concurrently block on a write() call of this

DataWriter. See Section 6.5.4.

 

 

 

 

• For a DataReader, it specifies the maximum expected elapsed time

 

between arriving data samples.

Deadline

• For a DataWriter, it specifies a commitment to publish samples with no

 

greater elapsed time between them.

 

See Section 6.5.5.

 

 

 

Controls how Connext will deal with data sent by multiple DataWriters for

DestinationOrder

the same topic. Can be set to "by reception timestamp" or to "by source

 

timestamp". See Section 6.5.6.

 

 

6-44

Table 6.16 DataWriter QosPolicies

QosPolicy

Description

 

 

 

 

Durability

Specifies whether or not Connext will store and deliver data that were

previously published to new DataReaders. See Section 6.5.7.

 

 

 

 

Various settings to configure the external Persistence Servicea used by Connext

DurabilityService

for DataWriters with a Durability QoS setting of Persistent Durability. See

 

Section 6.5.8.

 

 

EntityName

Assigns a name to a DataWriter. See Section 6.5.9.

 

 

 

Specifies how much data must to stored by Connextfor the DataWriter or

History

DataReader. This QosPolicy affects the RELIABILITY QosPolicy (Section

6.5.19) as well as the DURABILITY QosPolicy (Section 6.5.7). See

 

 

Section 6.5.10.

 

 

LatencyBudget

Suggestion to Connext on how much time is allowed to deliver data. See

Section 6.5.11.

 

 

 

Lifespan

Specifies how long Connext should consider data sent by an user application

to be valid. See Section 6.5.12.

 

 

 

Liveliness

Specifies and configures the mechanism that allows DataReaders to detect

when DataWriters become disconnected or "dead." See Section 6.5.13.

 

 

 

MultiChannel

Configures a DataWriter’s ability to send data on different multicast groups

(addresses) based on the value of the data. See Section 6.5.14.

 

 

 

Ownership

Along with OwnershipStrength, specifies if DataReaders for a topic can

receive data from multiple DataWriters at the same time. See Section 6.5.15.

 

 

 

OwnershipStrength

Used to arbitrate among multiple DataWriters of the same instance of a Topic

when Ownership QosPolicy is EXLUSIVE. See Section 6.5.16.

 

 

 

Partition

Adds string identifiers that are used for matching DataReaders and

DataWriters for the same Topic. See Section 6.4.5.

 

 

 

 

Stores name/value (string) pairs that can be used to configure certain

 

parameters of Connext that are not exposed through formal QoS policies. It

Property

can also be used to store and propagate application-specific name/value

 

pairs, which can be retrieved by user code during discovery. See

 

Section 6.5.17.

 

 

 

Specifies how Connext sends application data on the network. By default,

PublishMode

data is sent in the user thread that calls the DataWriter’s write() operation.

However, this QosPolicy can be used to tell Connext to use its own thread to

 

 

send the data. See Section 6.5.18.

 

 

Reliability

Specifies whether or not Connext will deliver data reliably. See Section 6.5.19.

 

 

 

Controls the amount of physical memory allocated for entities, if dynamic

ResourceLimits

allocations are allowed, and how they occur. Also controls memory usage

 

among different instance values for keyed topics. See Section 6.5.20.

 

 

TransportPriority

Set by a DataWriter to tell Connext that the data being sent is a different

"priority" than other data. See Section 6.5.21.

 

 

 

TransportSelection

Allows you to select which physical transports a DataWriter or DataReader

may use to send or receive its data. See Section 6.5.22.

 

 

 

TransportUnicast

Specifies a subset of transports and port number that can be used by an

Entity to receive data. See Section 6.5.23.

 

 

 

 

Used to attach application-specific value(s) to a DataWriter or DataReader.

TypeSupport

These values are passed to the serialization or deserialization routine of the

 

associated data type. See Section 6.5.24.

 

 

6-45

Table 6.16 DataWriter QosPolicies

QosPolicy

Description

UserData

Along with Topic Data QosPolicy and Group Data QosPolicy, used to attach a buffer of bytes to Connext's discovery meta-data. See Section 6.5.25.

WriterDataLifeCycle

Controls how a DataWriter handles the lifecycle of the instances (keys) that the DataWriter is registered to manage. See Section 6.5.26.

a. Persistence Service is included with Connext Messaging.

Many of the DataWriter QosPolicies also apply to DataReaders (see Section 7.3). For a DataWriter to communicate with a DataReader, their QosPolicies must be compatible. Generally, for the QosPolicies that apply both to the DataWriter and the DataReader, the setting in the DataWriter is considered an “offer” and the setting in the DataReader is a “request.” Compatibility means that what is offered by the DataWriter equals or surpasses what is requested by the DataReader. Each policy’s description includes compatibility restrictions. For more information on compatibility, see QoS Requested vs. Offered Compatibility—the RxO Property (Section 4.2.1).

Some of the policies may be changed after the DataWriter has been created. This allows the application to modify the behavior of the DataWriter while it is in use. To modify the QoS of an already-created DataWriter, use the get_qos() and set_qos() operations on the DataWriter. This is

ageneral pattern for all Entities, described in Section 4.1.7.3.

6.3.15.1Configuring QoS Settings when the DataWriter is Created

As described in Creating DataWriters (Section 6.3.1), there are different ways to create a DataWriter, depending on how you want to specify its QoS (with or without a QoS Profile).

In Figure 6.9 on page 6-19, we saw an example of how to create a DataWriter with default QosPolicies by using the special constant, DDS_DATAWRITER_QOS_DEFAULT, which indicates that the default QoS values for a DataWriter should be used. The default DataWriter QoS values are configured in the Publisher or DomainParticipant; you can change them with set_default_datawriter_qos() or set_default_datawriter_qos_with_profile(). Then any DataWriters created with the

Publisher will use the new default values. As described in Section 4.1.7, this is a general pattern that applies to the construction of all Entities.

To create a DataWriter with non-default QoS without using a QoS Profile, see the example code in Figure 6.16 on page 6-47. It uses the Publisher’s get_default_writer_qos() method to initialize a DDS_DataWriterQos structure. Then, the policies are modified from their default values before the structure is used in the create_datawriter() method.

You can also create a DataWriter and specify its QoS settings via a QoS Profile. To do so, you will call create_datawriter_with_profile(), as seen in Figure 6.17 on page 6-47.

If you want to use a QoS profile, but then make some changes to the QoS before creating the DataWriter, call get_datawriter_qos_from_profile() and create_datawriter() as seen in Figure 6.18 on page 6-48.

For more information, see Creating DataWriters (Section 6.3.1) and Chapter 17: Configuring QoS with XML.

6-46

Figure 6.16 Creating a DataWriter with Modified QosPolicies (not from a profile)

DDS_DataWriterQos writer_qos;1

//initialize writer_qos with default values publisher->get_default_datawriter_qos(writer_qos);

//make QoS changes

writer_qos.history.depth = 5;

// Create the writer with modified qos

DDSDataWriter * writer = publisher->create_datawriter( topic, writer_qos,

NULL, DDS_STATUS_MASK_NONE);

if (writer == NULL) { // ... error

}

// narrow it for your specific data type

FooDataWriter* foo_writer = FooDataWriter::narrow(writer);

1. Note: In C, you must initialize the QoS structures before they are used, see Section 4.2.2.

Figure 6.17 Creating a DataWriter with a QoS Profile

// Create the datawriter DDSDataWriter * writer =

publisher->create_datawriter_with_profile( topic,

“MyWriterLibrary”,

“MyWriterProfile”,

NULL, DDS_STATUS_MASK_NONE);

if (writer == NULL) { // ... error

};

// narrow it for your specific data type

FooDataWriter* foo_writer = FooDataWriter::narrow(writer);

6-47

Figure 6.18 Getting QoS Values from a Profile, Changing QoS Values, Creating a DataWriter with Modified QoS Values

DDS_DataWriterQos writer_qos;1

// Get writer QoS from profile

retcode = factory->get_datawriter_qos_from_profile( writer_qos, “WriterProfileLibrary”, “WriterProfile”);

if (retcode != DDS_RETCODE_OK) { // handle error

}

// Makes QoS changes writer_qos.history.depth = 5;

DDSDataWriter * writer = publisher->create_datawriter( topic, writer_qos,

NULL, DDS_STATUS_MASK_NONE);

if (participant == NULL) { // handle error

}

1. Note: In C, you must initialize the QoS structures before they are used, see Section 4.2.2.

6-48

6.3.15.2Changing QoS Settings After the DataWriter Has Been Created

There are 2 ways to change an existing DataWriter’s QoS after it is has been created—again depending on whether or not you are using a QoS Profile.

To change QoS programmatically (that is, without using a QoS Profile), use get_qos() and set_qos(). See the example code in Figure 6.19. It retrieves the current values by calling the DataWriter’s get_qos() operation. Then it modifies the value and calls set_qos() to apply the new value. Note, however, that some QosPolicies cannot be changed after the DataWriter has been enabled—this restriction is noted in the descriptions of the individual QosPolicies.

You can also change a DataWriter’s (and all other Entities’) QoS by using a QoS Profile and calling set_qos_with_profile(). For an example, see Figure 6.20. For more information, see Chapter 17: Configuring QoS with XML.

Figure 6.19 Changing the QoS of an Existing DataWriter (without a QoS Profile)

DDS_DataWriterQos writer_qos;1

// Get current QoS.

if (datawriter->get_qos(writer_qos) != DDS_RETCODE_OK) { // handle error

}

//Makes QoS changes here writer_qos.history.depth = 5;

//Set the new QoS

if (datawriter->set_qos(writer_qos) != DDS_RETCODE_OK ) { // handle error

}

1. For the C API, you need to use DDS_ParticipantQos_INITIALIZER or DDS_ParticipantQos_initialize(). See Section 4.2.2

Figure 6.20 Changing the QoS of an Existing DataWriter with a QoS Profile

retcode = writer->set_qos_with_profile( “WriterProfileLibrary”,”WriterProfile”);

if (retcode != DDS_RETCODE_OK) { // handle error

}

6-49

6.3.15.3Using a Topic’s QoS to Initialize a DataWriter’s QoS

Several DataWriter QosPolicies can also be found in the QosPolicies for Topics (see Section 5.1.3). The QosPolicies set in the Topic do not directly affect the DataWriters (or DataReaders) that use that Topic. In many ways, some QosPolicies are a Topic-level concept, even though the DDS standard allows you to set different values for those policies for different DataWriters and DataReaders of the same Topic. Thus, the policies in the DDS_TopicQos structure exist as a way to help centralize and annotate the intended or suggested values of those QosPolicies. Connext does not check to see if the actual policies set for a DataWriter is aligned with those set in the Topic to which it is bound.

There are many ways to use the QosPolicies’ values set in the Topic when setting the QosPolicies’ values in a DataWriter. The most straightforward way is to get the values of policies directly from the Topic and use them in the policies for the DataWriter, as shown in Figure 6.21.

Figure 6.21 Copying Selected QoS from a Topic when Creating a DataWriter

DDS_DataWriterQos writer_qos;1

DDS_TopicQos topic_qos;

//topic and publisher already created

//get current QoS for the topic, default QoS for the writer if (topic->get_qos(topic_qos) != DDS_RETCODE_OK) {

//handle error

}

if (publisher->get_default_datawriter_qos(writer_qos) != DDS_RETCODE_OK) { // handle error

}

//Copy specific policies from the topic QoS to the writer QoS writer_qos.deadline = topic_qos.deadline; writer_qos.reliability = topic_qos.reliability;

//Create the DataWriter with the modified QoS

DDSDataWriter* writer = publisher->create_datawriter(topic, writer_qos,NULL, DDS_STATUS_MASK_NONE);

1. Note in C, you must initialize the QoS structures before they are used, see Section 4.2.2.

6-50

You can use the Publisher’s copy_from_topic_qos() operation to copy all of the common policies from the Topic QoS to a DataWriter QoS. This is illustrated in Figure 6.22.

Figure 6.22 Copying all QoS from a Topic when Creating a DataWriter

DDS_DataWriterQos writer_qos;1 DDS_TopicQos topic_qos;

// topic, publisher, writer_listener already created

if (topic->get_qos(topic_qos) != DDS_RETCODE_OK) { // handle error

}

if (publisher->get_default_datawriter_qos(writer_qos) != DDS_RETCODE_OK)

{

// handle error

}

//copy relevant QosPolicies from topic’s qos into writer’s qos publisher->copy_from_topic_qos(writer_qos, topic_qos);

//Optionally, modify policies as desired

writer_qos.deadline.duration.sec = 1; writer_qos.deadline.duration.nanosec = 0;

// Create the DataWriter with the modified QoS DDSDataWriter* writer = publisher->create_datawriter(topic,

writer_qos, writer_listener, DDS_STATUS_MASK_ALL);

1. Note in C, you must initialize the QoS structures before they are used, see Section 4.2.2.

In another design pattern, you may want to start with the default QoS values for a DataWriter and override them with the QoS values of the Topic. Figure 6.23 gives an example of how to do this.

Because this is a common pattern, Connext provides a special macro,

DDS_DATAWRITER_QOS_USE_TOPIC_QOS, that can be used to indicate that the

DataWriter should be created with the set of QoS values that results from modifying the default DataWriter QosPolicies with the QoS values specified by the Topic. Figure 6.24 shows how the macro is used.

6-51

The code fragments shown in Figure 6.23 and Figure 6.24 result in identical QoS settings for the created DataWriter.

Figure 6.23 Combining Default Topic and DataWriter QoS (Option 1)

DDS_DataWriterQos writer_qos;1 DDS_TopicQos topic_qos;

// topic, publisher, writer_listener already created

if (topic->get_qos(topic_qos) != DDS_RETCODE_OK) { // handle error

}

if (publisher->get_default_datawriter_qos(writer_qos) != DDS_RETCODE_OK) { // handle error

}

if (publisher->copy_from_topic_qos(writer_qos, topic_qos) != DDS_RETCODE_OK) {

// handle error

}

// Create the DataWriter with the combined QoS

DDSDataWriter* writer = publisher->create_datawriter(topic, writer_qos, writer_listener,DDS_STATUS_MASK_ALL);

1. Note in C, you must initialize the QoS structures before they are used, see Section 4.2.2.

Figure 6.24 Combining Default Topic and DataWriter QoS (Option 2)

// topic, publisher, writer_listener already created

DDSDataWriter* writer = publisher->create_datawriter (topic, DDS_DATAWRITER_QOS_USE_TOPIC_QOS, writer_listener, DDS_STATUS_MASK_ALL);

For more information on the general use and manipulation of QosPolicies, see Section 4.1.7.

6.3.16Navigating Relationships Among Entities

6.3.16.1Finding Matching Subscriptions

The following DataWriter operations can be used to get information on the DataReaders that are currently associated with the DataWriter (that is, the DataReaders to which Connext will send the data written by the DataWriter).

get_matched_subscriptions()

get_matched_subscription_data()

get_matched_subscription_locators()

get_matched_subscriptions() will return a sequence of handles to matched DataReaders. You can use these handles in the get_matched_subscription_data() method to get information about the DataReader such as the values of its QosPolicies.

get_matched_subscription_locators() retrieves a list of locators for subscriptions currently "associated" with the DataWriter. Matched subscription locators include locators for all those subscriptions in the same domain that have a matching Topic, compatible QoS, and a common partition that the DomainParticipant has not indicated should be "ignored." These are the locators that Connext uses to communicate with matching DataReaders. (See Locator Format (Section 14.2.1.1).)

6-52

You can also get the DATA_WRITER_PROTOCOL_STATUS for matching subscriptions with these operations (see Section 6.3.6.2):

get_matched_subscription_datawriter_protocol_status()

get_matched_subscription_datawriter_protocol_status_by_locator()

Notes:

Status/data for a matched subscription is only kept while the matched subscription is alive. Once a matched subscription is no longer alive, its status is deleted. If you try to get the status/data for a matched subscription that is no longer alive, the 'get status' or ' get data' call will return an error.

DataReaders that have been ignored using the DomainParticipant’s ignore_subscription() operation are not considered to be matched even if the DataReader has the same Topic and compatible QosPolicies. Thus, they will not be included in the list of DataReaders returned by get_matched_subscriptions() or get_matched_subscription_locators(). See Section 16.4.2 for more on ignore_subscription().

The get_matched_subscription_data() operation does not retrieve the following information from built-in-topic data structures: type_code, property, and content_filter_property. This information is available through the on_data_available() callback (if a DataReaderListener is installed on the SubscriptionBuiltinTopicDataDataReader).

6.3.16.2Finding Related Entities

These operations are useful for obtaining a handle to various related entities:

get_publisher()

get_topic()

get_publisher() returns the Publisher that created the DataWriter. get_topic() returns the Topic with which the DataWriter is associated.

6.3.17Asserting Liveliness

The assert_liveliness() operation can be used to manually assert the liveliness of the DataWriter without writing data. This operation is only useful if the kind of LIVELINESS QosPolicy (Section 6.5.13) is MANUAL_BY_PARTICIPANT or MANUAL_BY_TOPIC.

How DataReaders determine if DataWriters are alive is configured using the LIVELINESS QosPolicy (Section 6.5.13). The lease_duration parameter of the LIVELINESS QosPolicy is a contract by the DataWriter to all of its matched DataReaders that it will send a packet within the time value of the lease_duration to state that it is still alive.

There are three ways to assert liveliness. One is to have Connext itself send liveliness packets periodically when the kind of LIVELINESS QosPolicy is set to AUTOMATIC. The other two ways to assert liveliness, used when liveliness is set to MANUAL, are to call write() to send data or to call the assert_liveliness() operation without sending data.

6.4Publisher/Subscriber QosPolicies

This section provides detailed information on the QosPolicies associated with a Publisher. Note that Subscribers have the exact same set of policies. Table 6.2 on page 6-7 provides a quick reference. They are presented here in alphabetical order.

ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension) (Section 6.4.1)

6-53

ENTITYFACTORY QosPolicy (Section 6.4.2)

EXCLUSIVE_AREA QosPolicy (DDS Extension) (Section 6.4.3)

GROUP_DATA QosPolicy (Section 6.4.4)

PARTITION QosPolicy (Section 6.4.5)

PRESENTATION QosPolicy (Section 6.4.6)

6.4.1ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension)

This QosPolicy is used to enable or disable asynchronous publishing and asynchronous batch flushing for the Publisher.

This QosPolicy can be used to reduce amount of time spent in the user thread to send data. You can use it to send large data reliably. Large in this context means that the data cannot be sent as a single packet by a transport. For example, to send data larger than 63K reliably using UDP/IP, you must configure Connext to send the data using asynchronous Publishers.

If so configured, the Publisher will spawn two threads, one for asynchronous publishing and one for asynchronous batch flushing. The asynchronous publisher thread will be shared by all DataWriters (belonging to this Publisher) that have their PUBLISH_MODE QosPolicy (DDS Extension) (Section 6.5.18) kind set to ASYNCHRONOUS. The asynchronous publishing thread will then handle the data transmission chores for those DataWriters. This thread will only be spawned when the first of these DataWriters is enabled.

The asynchronous batch flushing thread will be shared by all DataWriters (belonging to this Publisher) that have batching enabled and max_flush_delay different than DURATION_INFINITE in BATCH QosPolicy (DDS Extension) (Section 6.5.2). This thread will only be spawned when the first of these DataWriters is enabled.

This QosPolicy allows you to adjust the asynchronous publishing and asynchronous batch flushing threads independently.

Batching and asynchronous publication are independent of one another. Flushing a batch on an asynchronous DataWriter makes it available for sending to the DataWriter's FlowControllers (DDS Extension) (Section 6.6). From the point of view of the FlowController, a batch is treated like one large sample.

Connext will sometimes coalesce multiple samples into a single network datagram. For example, samples buffered by a FlowController or sent in response to a negative acknowledgement (NACK) may be coalesced. This behavior is distinct from sample batching. Data samples sent by different asynchronous DataWriters belonging to the same Publisher to the same destination will not be coalesced into a single network packet. Instead, two separate network packets will be sent. Only samples written by the same DataWriter and intended for the same destination will be coalesced.

This QosPolicy includes the members in Table 6.17.

Table 6.17 DDS_AsynchronousPublisherQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

Disables asynchronous publishing. To write

DDS_Boolean

disable_asynchronous_write

asynchronously, this field must be FALSE

 

 

(the default).

 

 

 

DDS_ThreadSettings_t

thread

Settings for the publishing thread. These

settings are OS-dependent.

 

 

 

 

 

6-54

Table 6.17 DDS_AsynchronousPublisherQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

Disables asynchronous batch flushing. To flush

DDS_Boolean

disable_asynchronous_batch

asynchronously, this field must be FALSE (the

 

 

default).

 

 

 

 

 

Settings for the asynchronous batch flushing

DDS_ThreadSettings_t

asynchronous_batch_thread

thread.

 

 

These settings are OS-dependent.

 

 

 

6.4.1.1Properties

This QosPolicy cannot be modified after the Publisher is created.

Since it is only for Publishers, there are no compatibility restrictions for how it is set on the publishing and subscribing sides.

6.4.1.2Related QosPolicies

If disable_asynchronous_write is TRUE (not the default), then any DataWriters created from this Publisher must have their PUBLISH_MODE QosPolicy (DDS Extension) (Section 6.5.18) kind set to SYNCHRONOUS. (Otherwise create_datawriter() will return INCONSISTENT_QOS.)

If disable_asynchronous_batch is TRUE (not the default), then any DataWriters created from this Publisher must have max_flush_delay in BATCH QosPolicy (DDS Extension) (Section 6.5.2) set to DURATION_INFINITE. (Otherwise create_datawriter() will return INCONSISTENT_QOS.)

DataWriters configured to use the MULTI_CHANNEL QosPolicy (DDS Extension) (Section 6.5.14) do not support asynchronous publishing; an error is returned if a multi- channel DataWriter is configured for asynchronous publishing.

6.4.1.3Applicable Entities

Publishers (Section 6.2)

6.4.1.4System Resource Considerations

Two threads can potentially be created.

For asynchronous publishing, system resource usage depends on the activity of the asynchronous thread controlled by the FlowController (see FlowControllers (DDS Extension) (Section 6.6)).

For asynchronous batch flushing, system resource usage depends on the activity of the asynchronous thread controlled by max_flush_delay in BATCH QosPolicy (DDS Extension) (Section 6.5.2).

6.4.2ENTITYFACTORY QosPolicy

This QosPolicy controls whether or not child entities are created in the enabled state.

This QosPolicy applies to the DomainParticipantFactory, DomainParticipants, Publishers, and

Subscribers, which act as ‘factories’ for the creation of subordinate entities. A

DomainParticipantFactory is used to create DomainParticipants. A DomainParticipant is used to create both Publishers and Subscribers. A Publisher is used to create DataWriters, similarly a

Subscriber is used to create DataReaders.

Entities can be created either in an ‘enabled’ or ‘disabled’ state. An enabled entity can actively participate in communication. A disabled entity cannot be discovered or take part in

6-55

communication until it is explicitly enabled. For example, Connext will not send data if the write() operation is called on a disabled DataWriter, nor will Connext deliver data to a disabled DataReader. You can only enable a disabled entity. Once an entity is enabled, you cannot disable it, see Section 4.1.2 about the enable() method.

The ENTITYFACTORY contains only one member, as illustrated in Table 6.18.

Table 6.18 DDS_EntityFactoryQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

DDS_BOOLEAN_TRUE: enable entities when they are

DDS_Boolean

autoenable_created_entities

created

 

 

DDS_BOOLEAN_FALSE: do not enable entities when they

 

 

are created

 

 

 

The ENTITYFACTORY QosPolicy controls whether the entities created from the factory are automatically enabled upon creation or are left disabled. For example, if a Publisher is configured to auto-enable created entities, then all DataWriters created from that Publisher will be automatically enabled.

Note: if an entity is disabled, then all of the child entities it creates are also created in a disabled state, regardless of the setting of this QosPolicy. However, enabling a disabled entity will enable all of its children if this QosPolicy is set to autoenable child entities.

Note: an entity can only be enabled; it cannot be disabled after its been enabled.

See Section 6.4.2.1 for an example of how to set this policy.

There are various reasons why you may want to create entities in the disabled state:

To get around a “chicken and egg”-type issue. Where you need to have an entity in order to modify it, but you don’t want the entity to be used by Connext until it has been modified.

For example, if you create a DomainParticipant in the enabled state, it will immediately start sending packets to other nodes trying to discover if other Connext applications exist. However, you may want to configure the built-in topic reader listener before discovery occurs. To do this, you need to create a DomainParticipant in the disabled state because once enabled, discovery will occur. If you set up the built-in topic reader listener after the DomainParticipant is enabled, you may miss some discovery traffic.

You may want to create entities without having them automatically start to work. This especially pertains to DataReaders. If you create a DataReader in an enabled state and you are using DataReaderListeners, Connext will immediately search for matching DataWriters and callback the listener as soon as data is published. This may not be what you want to happen if your application is still in the middle of initialization when data arrives.

So typically, you would create all entities in a disabled state, and then when all parts of the application have been initialized, one would enable all entities at the same time using the enable() operation on the DomainParticipant, see Section 4.1.2.

6-56

An entity’s existence is not advertised to other participants in the network until the entity is enabled. Instead of sending an individual declaration packet to other applications announcing the existence of the entity, Connext can be more efficient in bundling multiple declarations into a single packet when you enable all entities at the same time.

See Section 4.1.2 for more information about enabled/disabled entities.

6.4.2.1Example

The code in Figure 6.25 illustrates how to use the ENTITYFACTORY QoS.

Figure 6.25 Configuring a Publisher so that New DataWriters are Disabled

DDS_PublisherQos publisher_qos;1

// topic, publisher, writer_listener already created

if (publisher->get_qos(publisher_qos) != DDS_RETCODE_OK) { // handle error

}

publisher_qos.entity_factory.autoenable_created_entities = DDS_BOOLEAN_FALSE;

if (publisher->set_qos(publisher_qos) != DDS_RETCODE_OK) { // handle error

}

//Subsequently created DataWriters are created disabled and

//must be explicitly enabled by the user-code DDSDataWriter* writer = publisher->create_datawriter(topic,

DDS_DATAWRITER_QOS_DEFAULT, writer_listener, DDS_STATUS_MASK_ALL);

... // now do other initialization

//Now explicitly enable the DataWriter, this will allow other

//applications to discover the DataWriter and for this application

//to send data when the DataWriter’s write() method is called writer->enable();

1.Note in C, you must initialize the QoS structures before they are used, see Section 4.2.2.

6.4.2.2Properties

This QosPolicy can be modified at any time.

It can be set differently on the publishing and subscribing sides.

6.4.2.3Related QosPolicies

This QosPolicy does not interact with any other policies.

6.4.2.4Applicable Entities

DomainParticipantFactory (Section 8.2)

DomainParticipants (Section 8.3)

Publishers (Section 6.2)

Subscribers (Section 7.2)

6-57

6.4.2.5System Resource Considerations

This QosPolicy does not significantly impact the use of system resources.

6.4.3EXCLUSIVE_AREA QosPolicy (DDS Extension)

This QosPolicy controls the creation and use of Exclusive Areas. An exclusive area (EA) is a mutex with built-in deadlock protection when multiple EAs are in use. It is used to provide mutual exclusion among different threads of execution. Multiple EAs allow greater concurrency among the internal and user threads when executing Connext code.

EAs allow Connext to be multi-threaded while preventing threads from a classical deadlock scenario for multi-threaded applications. EAs prevent a DomainParticipant's internal threads from deadlocking with each other when executing internal code as well as when executing the code of user-registered listener callbacks.

Within an EA, all calls to the code protected by the EA are single threaded. Each

DomainParticipant, Publisher and Subscriber represents a separate EA. All DataWriters of the same

Publisher and all DataReaders of the same Subscriber share the EA of its parent. This means that the DataWriters of the same Publisher and the DataReaders of the same Subscriber are inherently single threaded.

Within an EA, there are limitations on how code protected by a different EA can be accessed. For example, when data is being processed by user code received in the DataReaderListener of a Subscriber EA, the user code may call the write() function of a DataWriter that is protected by the EA of its Publisher. So you can send data in the function called to process received data. However, you cannot create entities or call functions that are protected by the EA of the DomainParticipant. See Exclusive Areas (EAs) (Section 4.5) for the complete documentation on Exclusive Areas.

With this QoS, you can force a Publisher or Subscriber to share the same EA as its DomainParticipant. Using this capability, the restriction of not being to create entities in a DataReaderListener's on_data_available() callback is lifted. However, the trade-off is that the application has reduced concurrency through the Entities that share an EA.

Note that the restrictions on calling methods in a different EA only exists for user code that is called in registered Listeners by internal DomainParticipant threads. User code may call all Connext functions for any Entities from their own threads at any time.

The EXCLUSIVE_AREA includes a single member, as listed in Table 6.19. For the default value, please refer to the API Reference HTML documentation.

Table 6.19 DDS_ExclusiveAreaQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

DDS_BOOLEAN_FALSE:

DDS_Boolean

use_shared_exclusive_area

subordinates will not use the same EA

DDS_BOOLEAN_TRUE:

 

 

 

 

subordinates will use the same EA

 

 

 

The implications and restrictions of using a private or shared EA are discussed in Section 4.5. The basic trade-off is concurrency versus restrictions on which methods can be called in user, listener, callback functions. To summarize:

Behavior when the Publisher or Subscriber’s use_shared_exclusive_area is set to FALSE:

The creation of the Publisher/Subscriber will create an EA that will be used only by the

Publisher/Subscriber and the DataWriters/DataReaders that belong to them.

Consequences: This setting maximizes concurrency at the expense of creating a mutex for the Publisher or Subscriber. In addition, using a separate EA may restrict certain Connext operations (see Operations Allowed within Listener Callbacks (Section 4.4.5))

6-58

from being called from the callbacks of Listeners attached to those entities and the entities that they create. This limitation results from a built-in deadlock protection mechanism.

Behavior when the Publisher or Subscriber’s use_shared_exclusive_area is set to TRUE:

The creation of the Publisher/Subscriber does not create a new EA. Instead, the Publisher/ Subscriber, along with the DataWriters/DataReaders that they create, will use a common EA shared with the DomainParticipant.

Consequences: By sharing the same EA among multiple entities, you may decrease the amount of concurrency in the application, which can adversely impact performance. However, this setting does use less resources and allows you to call almost any operation on any Entity within a listener callback (see Exclusive Areas (EAs) (Section 4.5) for full details).

6.4.3.1Example

The code in Figure 6.26 illustrates how to change the EXCLUSIVE_AREA policy.

Figure 6.26 Creating a Publisher with a Shared Exclusive Area

DDS_PublisherQos publisher_qos;1

// domain, publisher_listener have been previously created if (participant->get_default_publisher_qos(publisher_qos) !=

DDS_RETCODE_OK) {

// handle error

}

publisher_qos.exclusive_area.use_shared_exclusive_area = DDS_BOOLEAN_TRUE;

DDSPublisher* publisher = participant->create_publisher(publisher_qos, publisher_listener, DDS_STATUS_MASK_ALL);

1.Note in C, you must initialize the QoS structures before they are used, see Section 4.2.2.

6.4.3.2Properties

This QosPolicy cannot be modified after the Entity has been created. It can be set differently on the publishing and subscribing sides.

6.4.3.3Related QosPolicies

This QosPolicy does not interact with any other policies.

6.4.3.4Applicable Entities

Publishers (Section 6.2)

Subscribers (Section 7.2)

6.4.3.5System Resource Considerations

This QosPolicy affects the use of operating-system mutexes. When use_shared_exclusive_area is FALSE, the creation of a Publisher or Subscriber will create an operating-system mutex.

6.4.4GROUP_DATA QosPolicy

This QosPolicy provides an area where your application can store additional information related to the Publisher and Subscriber. This information is passed between applications during

6-59

discovery (see Chapter 14: Discovery) using built-in-topics (see Chapter 16: Built-In Topics). How this information is used will be up to user code. Connext does not do anything with the information stored as GROUP_DATA except to pass it to other applications.

Use cases are often application-to-application identification, authentication, authorization, and encryption purposes. For example, applications can use this QosPolicy to send security certificates to each other for RSA-type security.

The value of the GROUP_DATA QosPolicy is sent to remote applications when they are first discovered, as well as when the Publisher or Subscriber’s set_qos() method is called after changing the value of the GROUP_DATA. User code can set listeners on the built-in DataReaders of the built-in Topics used by Connext to propagate discovery information. Methods in the built- in topic listeners will be called whenever new DomainParticipants, DataReaders, and DataWriters are found. Within the user callback, you will have access to the GROUP_DATA that was set for the associated Publisher or Subscriber.

Currently, GROUP_DATA of the associated Publisher or Subscriber is only propagated with the information that declares a DataWriter or DataReader. Thus, you will need to access the value of GROUP_DATA through DDS_PublicationBuiltinTopicData or DDS_SubscriptionBuiltinTopicData (see Chapter 16: Built-In Topics).

The structure for the GROUP_DATA QosPolicy includes just one field, as seen in Table 6.20. The field is a sequence of octets that translates to a contiguous buffer of bytes whose contents and length is set by the user. The maximum size for the data are set in the DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4).

Table 6.20 DDS_GroupDataQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

DDS_OctetSeq

value

Empty by default

 

 

 

This policy is similar to the USER_DATA QosPolicy (Section 6.5.25) and TOPIC_DATA QosPolicy (Section 5.2.1) that apply to other types of Entities.

6.4.4.1Example

One possible use of GROUP_DATA is to pass some credential or certificate that your subscriber application can use to accept or reject communication with the DataWriters that belong to the Publisher (or vice versa, where the publisher application can validate the permission of DataReaders of a Subscriber to receive its data). The value of the GROUP_DATA of the Publisher is propagated in the ‘group_data’ field of the DDS_PublicationBuiltinTopicData that is sent with the declaration of each DataWriter. Similarly, the value of the GROUP_DATA of the Subscriber is propagated in the ‘group_data’ field of the DDS_SubscriptionBuiltinTopicData that is sent with the declaration of each DataReader.

When Connext discovers a DataWriter/DataReader, the application can be notified of the discovery of the new entity and retrieve information about the DataWriter/DataReader QoS by reading the DCPSPublication or DCPSSubscription built-in topics (see Chapter 16: Built-In Topics). Your application can then examine the GROUP_DATA field in the built-in Topic and decide whether or not the DataWriter/DataReader should be allowed to communicate with local DataReaders/DataWriters. If communication is not allowed, the application can use the

DomainParticipant’s ignore_publication() or ignore_subscription() operation to reject the newly discovered remote entity as one with which the application allows Connext to communicate. See Figure 16.2, “Ignoring Publications,” on page 16-12 for an example of how to do this.

The code in Figure 6.27 illustrates how to change the GROUP_DATA policy.

6.4.4.2Properties

This QosPolicy can be modified at any time.

It can be set differently on the publishing and subscribing sides.

6-60

Figure 6.27 Creating a Publisher with GROUP_DATA

DDS_PublisherQos publisher_qos;1 int i = 0;

//Bytes that will be used for the group data. In this case 8 bytes

//of some information that is meaningful to the user application char myGroupData[GROUP_DATA_SIZE] =

{ 0x34, 0xaa, 0xfe, 0x31, 0x7a, 0xf2, 0x34, 0xaa};

//assume that domainparticipant and publisher_listener

//are already created

if (participant->get_default_publisher_qos(publisher_qos) != DDS_RETCODE_OK) {

// handle error

}

// Must set the size of the sequence first publisher_qos.group_data.value.maximum(GROUP_DATA_SIZE); publisher_qos.group_data.value.length(GROUP_DATA_SIZE);

for (i = 0; i < GROUP_DATA_SIZE; i++) { publisher_qos.group_data.value[i] = myGroupData[i]

}

DDSPublisher* publisher = participant->create_publisher( publisher_qos, publisher_listener, DDS_STATUS_MASK_ALL);

1.Note in C, you must initialize the QoS structures before they are used, see Section 4.2.2.

6.4.4.3Related QosPolicies

TOPIC_DATA QosPolicy (Section 5.2.1)

USER_DATA QosPolicy (Section 6.5.25)

DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4)

6.4.4.4Applicable Entities

Publishers (Section 6.2)

Subscribers (Section 7.2)

6.4.4.5System Resource Considerations

As mentioned earlier, the maximum size of the GROUP_DATA is set in the publisher_group_data_max_length and subscriber_group_data_max_length fields of the DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4). Because Connext will allocate memory based on this value, you should only increase this value if you need to. If your system does not use GROUP_DATA, then you can set this value to zero to save memory. Setting the value of the GROUP_DATA QosPolicy to hold data longer than the value set in the [publisher/subscriber]_group_data_max_length fields will result in failure and an INCONSISTENT_QOS_POLICY return code.

However, should you decide to change the maximum size of GROUP_DATA, you must make certain that all applications in the domain have changed the value of [publisher/ subscriber]_group_data_max_length to be the same. If two applications have different limits on

6-61

the size of GROUP DATA, and one application sets the GROUP_DATA QosPolicy to hold data that is greater than the maximum size set by another application, then the matching DataWriters and DataReaders of the Publisher and Subscriber between the two applications will not connect. This is also true for the TOPIC_DATA (Section 5.2.1) and USER_DATA (Section 6.5.25) QosPolicies.

6.4.5PARTITION QosPolicy

The PARTITION QoS provides another way to control which DataWriters will match—and thus communicate with—which DataReaders. It can be used to prevent DataWriters and DataReaders that would have otherwise matched with the same Topic and compatible QosPolicies from talking to each other. Much in the same way that only applications within the same domain will communicate with each other, only DataWriters and DataReaders that belong to the same partition can talk to each other.

The PARTITION QoS applies to Publishers and Subscribers, therefore the DataWriters and DataReaders belong to the partitions as set on the Publishers and Subscribers that created them. The mechanism implementing the PARTITION QoS is relatively lightweight, and membership in a partition can be dynamically changed. Unlike the creation and destruction of DomainParticipants, there is no spawning and killing of threads or allocation and deallocation of memory when Publishers and Subscribers add or remove themselves from partitions.

The PARTITION QoS consists of a set of partition names that identify the partitions of which the Entity is a member. These names are simply strings, and DataWriters and DataReaders are considered to be in the same partition if they have more than one partition name in common in the PARTITION QoS set on their Publishers or Subscribers.

Conceptually each partition name can be thought of as defining a “visibility plane” within the domain. DataWriters will make their data available on all the visibility planes that correspond to its Publisher’s partition names, and the DataReaders will see the data that is placed on any of the visibility planes that correspond to its Subscriber’s partition names.

Figure 6.28 illustrates the concept of PARTITION QoS. In this figure, all DataWriters and DataReaders belong to the same domain and refer to the same Topic. DataWriter1 is configured to belong to three partitions: partition_A, partition_B, and partition_C. DataWriter2 belongs to partition_C and partition_D.

Figure 6.28 Controlling Visibility of Data with the PARTITION QoS

6-62

Similarly, DataReader1 is configured to belong to partition_A and partition_B, and DataReader2 belongs only to partition_C. Given this topology, the data written by DataWriter1 is visible in partitions A, B, and C. The oval tagged with the number “1” represents one data-sample written by DataWriter1.

Similarly, the data written by DataWriter2 is visible in partitions C and D. The oval tagged with the number “2” represents one data-sample written by DataWriter2.

The result is that the data written by DataWriter1 will be received by both DataReader1 and DataReader2, but the data written by DataWriter2 will only be visible by DataReader2.

Publishers and Subscribers always belong to a partition. By default, Publishers and Subscribers belong to a single partition whose name is the empty string, ““. If you set the PARTITION QoS to be an empty set, Connext will assign the Publisher or Subscriber to the default partition, ““. Thus, for the example above, without using the PARTITION QoS, DataReaders 1 and 2 would have received all data samples written by DataWriters 1 and 2.

6.4.5.1Rules for PARTITION Matching

On the Publisher side, the PARTITION QosPolicy associates a set of strings (partition names) with the Publisher. On the Subscriber side, the application also uses the PARTITION QoS to associate partition names with the Subscriber.

Taking into account the PARTITION QoS, a DataWriter will communicate with a DataReader if and only if the following conditions apply:

1.The DataWriter and DataReader belong to the same domain. That is, their respective DomainParticipants are bound to the same domain ID (see Section 8.3.1).

2.The DataWriter and DataReader have matching Topics. That is, each is associated with a Topic with the same topic_name and data type.

3.The QoS offered by the DataWriter is compatible with the QoS requested by the

DataReader.

4.The application has not used the ignore_participant(), ignore_datareader(), or ignore_datawriter() APIs to prevent the association (see Section 16.4).

5.The Publisher to which the DataWriter belongs and the Subscriber to which the DataReader belongs must have at least one matching partition name.

The last condition reflects the visibility of the data introduced by the PARTITION QoS. Matching partition names is done by string comparison, thus partition names are case sensitive.

NOTE: Failure to match partitions is not considered an incompatible QoS and does not trigger any listeners or change any status conditions.

6.4.5.2Pattern Matching for PARTITION Names

You may also add strings that are regular expressions1 to the PARTITION QosPolicy. A regular expression does not define a set of partitions to which the Publisher or Subscriber belongs, as much as it is used in the partition matching process to see if a remote entity has a partition name that would be matched with the regular expression. That is, the regular expressions in the PARTITION QoS of a Publisher are never matched against those found in the PARTITION QoS of a Subscriber. Regular expressions are always matched against “concrete” partition names. Thus, a concrete partition name may not contain any reserved characters that are used to define regular expressions, for example ‘*’, ‘.’, ‘+’, etc.

If a PARTITION QoS only contains regular expressions, then the Publisher or Subscriber will be assigned automatically to the default partition with the empty string name (““). Thus, do not be fooled into thinking that a PARTITION QoS that only contains the string “*” matches another

1.As defined by the POSIX fnmatch API (1003.2-1992 section B.6).

6-63

PARTITION QoS that only contains the string “*”. Yes, the Publisher will match the Subscriber, but it is because they both belong to the default ““ partition.

DataWriters and DataReaders are considered to have a partition in common if the sets of partitions that their associated Publishers and Subscribers have defined have:

at least one concrete partition name in common

a regular expression in one Entity that matches a concrete partition name in another Entity

The programmatic representation of the PARTITION QoS is shown in Table 6.21. The QosPolicy contains the single string sequence, name. Each element in the sequence can be a concrete name or a regular expression. The Entity will be assigned to the default ““ partition if the sequence is empty.

Table 6.21 DDS_PartitionQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

Empty by default.

DDS_StringSeq

name

There can be up to 64 names, with a maximum of 256 characters

 

 

summed across all names.

 

 

 

You can have one long partition string of 256 chars, or multiple shorter strings that add up to 256 or less characters. For example, you can have one string of 4 chars and one string of 252 chars.

6.4.5.3Example

Since the set of partitions for a Publisher or Subscriber can be dynamically changed, the Partition QosPolicy is useful to control which DataWriters can send data to which DataReaders and vice versa—even if all of the DataWriters and DataReaders are for the same topic. This facility is useful for creating temporary separation groups among entities that would otherwise be connected to and exchange data each other.

Note when using Partitions and Durability: If a Publisher changes partitions after startup, it is possible for a reliable, late-joining DataReader to receive data that was written for both the original and the new partition. For example, suppose a DataWriter with TRANSIENT_LOCAL Durability initially writes samples with Partition A, but later changes to Partition B. In this case, a reliable, late-joining DataReader configured for Partition B will receive whatever samples have been saved for the DataWriter. These may include samples which were written when the DataWriter was using Partition A.

The code in Figure 6.29 illustrates how to change the PARTITION policy.

The ability to dynamically control which DataWriters are matched to which DataReaders (of the same Topic) offered by the PARTITION QoS can be used in many different ways. Using partitions, connectivity can be controlled based on location-based partitioning, access-control groups, purpose, or a combination of these and other application-defined criteria. We will examine some of these options via concrete examples.

Example of location-based partitions. Assume you have a set of Topics in a traffic management system such as “TrafficAlert,” “AccidentReport,” and “CongestionStatus.” You may want to control the visibility of these Topics based on the actual location to which the information applies. You can do this by placing the Publisher in a partition that represents the area to which the information applies. This can be done using a string that includes the city, state, and country, such as “USA/California/Santa Clara.” A Subscriber can then choose whether it wants to see the alerts in a single city, the accidents in a set of states, or the congestion status across the US. Some concrete examples are shown in Table 6.22.

Example of access-control group partitions. Suppose you have an application where access to the information must be restricted based on reader membership to access-control groups. You can map this group-controlled visibility to partitions by naming all the groups (e.g. executives,

6-64

Figure 6.29 Setting Partition Names on a Publisher

DDS_PublisherQos publisher_qos;1

// domain, publisher_listener have been previously created

if (participant->get_default_publisher_qos(publisher_qos) != DDS_RETCODE_OK) {

// handle error

}

// Set the partition QoS publisher_qos.partition.name.maximum(3); publisher_qos.partition.name.length(3); publisher_qos.partition.name[0] = DDS_String_dup(“partition_A”); publisher_qos.partition.name[1] = DDS_String_dup(“partition_B”); publisher_qos.partition.name[2] = DDS_String_dup(“partition_C”);

DDSPublisher* publisher = participant->create_publisher(publisher_qos, publisher_listener, DDS_STATUS_MASK_ALL);

1. Note in C, you must initialize the QoS structures before they are used, see Section 4.2.2.

Table 6.22 Example of Using Location-Based Partitions

Publisher Partitions

Subscriber Partitions

 

Result

 

 

 

 

 

 

Specify a single partition name

Specify multiple partition

Limits the visibility of the data to

using the pattern:

names, one per region of

Subscribers that express interest in

“<country>/<state>/<city>”

interest

 

 

the geographical region.

 

 

 

 

 

“USA/California/Santa Clara”

(Subscriber

participant

is

Send only information for Santa

irrelevant here.)

 

Clara, California.

 

 

 

 

 

 

“USA/California/Santa Clara”

Receive only information for Santa

 

 

 

 

Clara, California.

 

“USA/California/Santa Clara”

Receive information for Santa Clara

(Publisher partition is irrelevant

“USA/California/Sunnyvale”

or Sunnyvale, California.

 

 

 

“USA/California/*”

 

Receive information for California

here.)

“USA/Nevada/*”

 

or Nevada.

 

 

 

 

 

 

 

“USA/California/*”

 

Receive information for California

 

“USA/Nevada/Reno”

 

 

 

and two cities in Nevada.

 

“USA/Nevada/Las Vegas”

 

 

 

 

 

 

 

 

 

payroll, financial, general-staff, consultants, external-people) and assigning the Publisher to the set of partitions that represents which groups should have access to the information. The Subscribers specify the groups to which they belong, and the partition-matching behavior will ensure that the information is only distributed to Subscribers belonging to the appropriate groups. Some concrete examples are shown in Table 6.23.

A slight variation of this pattern could be used to confine the information based on security levels.

Example of purpose-based partitions: Assume an application containing subsystems that can be used for multiple purposes, such as training, simulation, and real use. In some occasions it is convenient to be able to dynamically switch the subsystem from operating in the “simulation world” to the “training world” or to the “real world.” For supervision purposes, it may be convenient to observe multiple worlds, so that you can compare the each one’s results. This can be accomplished by setting a partition name in the Publisher that represents the “world” to

6-65

Table 6.23 Example of Access-Control Group Partitions

Publisher Partitions

Subscriber Partitions

 

Result

 

 

 

 

 

 

 

 

 

 

 

 

Specify

several partition

Specify

multiple

partition

Limits the visibility of the data to Subscribers

names,

one per group

names, one per group to which

that belong to the access-groups specified by

that is allowed access:

the Subscriber belongs.

 

 

the Publisher.

 

 

 

 

 

“payroll”

(Subscriber

participant

is

Makes information available only to

“financial”

irrelevant here.)

 

 

Subscribers that have access to either

 

 

financial or payroll information.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

(Publisher participant is

“executives”

 

 

 

Gain access to information that is intended

 

 

 

for executives or people with access to the

irrelevant here.)

“financial”

 

 

 

 

 

 

 

 

finances.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

which it belongs and a set of partition names in the Subscriber that model the worlds that it can observe.

6.4.5.4Properties

This QosPolicy can be modified at any time.

Strictly speaking, this QosPolicy does not have request-offered semantics, although it is matched between DataWriters and DataReaders, and communication is established only if there is a match between partition names.

6.4.5.5Related QosPolicies

DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4).

6.4.5.6Applicable Entities

Publishers (Section 6.2)

Subscribers (Section 7.2)

6.4.5.7System Resource Considerations

Partition names are propagated along with the declarations of the DataReaders and the DataWriters and can be examined by user code through built-in topics (see Chapter 16: Built-In Topics). Thus the sum-total length of the partition names will impact the bandwidth needed to transmit those declarations, as well as the memory used to store them.

The maximum number of partitions and the maximum number of characters that can be used for the sum-total length of all partition names are configured using the max_partitions and max_partition_cumulative_characters fields of the DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4). Setting more partitions or using longer names than allowed by those limits will result in failure and an INCONSISTENT_QOS_POLICY return code.

However, should you decide to change the maximum number of partitions or maximum cumulative length of partition names, then you must make certain that all applications in the domain have changed the values of max_partitions and max_partition_cumulative_characters to be the same. If two applications have different values for those settings, and one application sets the PARTITION QosPolicy to hold more partitions or longer names than set by another application, then the matching DataWriters and DataReaders of the Publisher and Subscriber between the two applications will not connect. This similar to the restrictions for the GROUP_DATA (Section 6.4.4), USER_DATA (Section 6.5.25), and TOPIC_DATA (Section 5.2.1) QosPolicies.

6-66

6.4.6PRESENTATION QosPolicy

Usually DataReaders will receive data in the order that it was sent by a DataWriter. In addition, data is presented to the DataReader as soon as the application receives the next value expected.

Sometimes, you may want a set of data for the same DataWriter to be presented to the receiving DataReader only after ALL the elements of the set have been received, but not before. You may also want the data to be presented in a different order than it was received. Specifically, for keyed data, you may want Connext to present the data in keyed or instance order.

The Presentation QosPolicy allows you to specify different scopes of presentation: within a DataWriter, across instances of a DataWriter, and even across different DataWriters of a publisher. It also controls whether or not a set of changes within the scope must be delivered at the same time or delivered as soon as each element is received.

There are three components to this QoS, the boolean flag coherent_access, the boolean flag ordered_access, and an enumerated setting for the access_scope. The structure used is shown in Table 6.24.

Table 6.24 DDS_PresentationQosPolicy

Type

Field Name

 

Description

 

 

 

 

 

 

 

 

 

 

 

 

Controls the granularity used when coherent_access and/or

 

 

ordered_access are TRUE.

 

 

 

 

 

 

 

If both coherent_access and ordered_access are FALSE,

 

 

access_scope’s setting has no effect.

 

 

 

 

 

 

• DDS_INSTANCE_PRESENTATION_QOS:

 

 

 

 

 

Queue is ordered/sorted per instance

 

 

 

DDS_Presentation_

 

• DDS_TOPIC_PRESENTATION_QOS:

 

 

 

 

 

Queue is ordered/sorted per topic (across all instances)

 

QosPolicyAccessScope

access_scope

 

 

• DDS_GROUP_PRESENTATION_QOS:

 

 

 

Kind

 

 

 

 

 

 

Queue is ordered/sorted per topic across all instances

 

 

 

 

 

 

belonging to DataWriter (or DataReaders) within the same

 

 

 

Publisher (or Subscriber). Not

supported

for

 

 

 

coherent_access = TRUE.

 

 

 

 

 

 

 

DDS_HIGHEST_OFFERED_PRESENTATION_QOS: Only

 

 

 

applies to Subscribers. With this setting, the Subscriber will

 

 

 

use the access scope specified by each remote Publisher.

 

 

 

 

 

 

Controls whether Connext will preserve the groupings of

 

 

changes made by the publishing application by means of

 

 

begin_coherent_changes() and end_coherent_changes().

 

DDS_Boolean

coherent_access

DDS_BOOLEAN_FALSE: Coherency is not preserved.

 

The value of access_scope is ignored.

 

 

 

 

 

• DDS_BOOLEAN_TRUE:

Changes

made

to instances

 

 

 

within each DataWriter will be available to the DataReader as

 

 

 

a coherent set, based on the value of access_scope. Not

 

 

 

supported for access_scope = GROUP.

 

 

 

 

 

 

 

 

 

Controls whether Connext will preserve the order of changes.

 

 

 

DDS_BOOLEAN_FALSE:

The order of samples is only

DDS_Boolean

ordered_access

 

preserved for each instance, not across instances. The value

 

of access_scope is ignored.

 

 

 

 

 

 

 

DDS_BOOLEAN_TRUE:

The order of samples from a

 

 

 

DataWriter is preserved,

based

on

the

value set

in

 

 

 

access_scope.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

6-67

6.4.6.1Coherent Access

A 'coherent set' is a set of data-sample modifications that must be propagated in such a way that they are interpreted at the receiver's side as a consistent set; that is, the receiver will only be able to access the data after all the modifications in the set are available at the subscribing end.

Coherency enables a publishing application to change the value of several data-instances and have those changes be seen atomically (as a cohesive set) by the readers.

Setting coherent_access to TRUE only behaves as described in the DDS specification when the

DataWriter and DataReader are configured for reliable delivery. Non-reliable DataReaders will never receive samples that belong to a coherent set.

To send a coherent set of data samples, the publishing application uses the Publisher’s begin_coherent_changes() and end_coherent_changes() operations (see Writing Coherent Sets of Data Samples (Section 6.3.10)).

If coherent_access is TRUE, then the access_scope controls the maximum extent of the coherent changes, as follows:

If access_scope is INSTANCE, the use of begin_coherent_changes() and end_coherent_changes() has no effect on how the subscriber can access the data. This is because, with the scope limited to each instance, changes to separate instances are considered independent and thus cannot be grouped by a coherent change.

If access_scope is TOPIC, then coherent changes (indicated by their enclosure within calls to begin_coherent_changes() and end_coherent_changes()) will be made available as such to each remote DataReader independently. That is, changes made to instances within the each individual DataWriter will be available as a coherent set with respect to other changes to instances in that same DataWriter, but will not be grouped with changes made to instances belonging to a different DataWriter.

If access_scope is GROUP, coherent changes made to instances through a DataWriter attached to a common Publisher are made available as a unit to remote subscribers. Coherent access with GROUP access scope is currently not supported.

6.4.6.2Ordered Access

If ordered_access is TRUE, then access_scope controls the scope of the order in which samples are presented to the subscribing application, as follows:

If access_scope is INSTANCE, the relative order of samples sent by a DataWriter is only preserved on an per-instance basis. If two samples refer to the same instance (identified by Topic and a particular value for the key) then the order in which they are stored in the DataReader’s queue is consistent with the order in which the changes occurred. However, if the two samples belong to different instances, the order in which they are presented may or may not match the order in which the changes occurred.

If access_scope is TOPIC, the relative order of samples sent by a DataWriter is preserved for all samples of all instances. The coherent grouping and/or order in which samples appear in the DataReader’s queue is consistent with the grouping/order in which the changes occurred—even if the samples affect different instances.

If access_scope is GROUP, the scope spans all instances belonging to DataWriter entities within the same Publisher—even if they are instances of different topics. Changes made to instances via DataWriter entities attached to the same Publisher are made available to Subscribers on the same order they occurred.

If access_scope is HIGHEST_OFFERED, the Subscriber will use the access scope specified by each remote Publisher.

The data stored in the DataReader is accessed by the DataReader’s read()/take() APIs. The application does not have to access the data samples in the same order as they are stored in the

6-68

queue. How the application actually gets the data from the DataReader is ultimately under the control of the user code, see Using DataReaders to Access Data (Read & Take) (Section 7.4).

6.4.6.3Example

Coherency is useful in cases where the values are inter-related (for example, if there are two data-instances representing the altitude and velocity vector of the same aircraft and both are changed, it may be useful to communicate those values in a way the reader can see both together; otherwise, it may e.g., erroneously interpret that the aircraft is on a collision course).

Ordered access is useful when you need to ensure that samples appear on the DataReader’s queue in the order sent by one or multiple DataWriters within the same Publisher.

To illustrate the effect of the PRESENTATION QosPolicy with TOPIC and INSTANCE access scope, assume the following sequence of samples was written by the DataWriter: {A1, B1, C1, A2, B2, C2}. In this example, A, B, and C represent different instances (i.e., different keys). Assume all of these samples have been propagated to the DataReader’s history queue before your application invokes the read() operation. The data-sample sequence returned depends on how the PRESENTATION QoS is set, as shown in Table 6.25.

Table 6.25 Effect of ordered_access for access_scope INSTANCE and TOPIC

 

Sequence retrieved via “read()”.

PRESENTATION QoS

Order sent was {A1, B1, C1, A2, B2, C2}

 

Order received was {A1, A2, B1, B2, C1, C2}

 

 

 

 

ordered_access = FALSE

{A1, A2, B1, B2, C1, C2}

access_scope = <any>

 

 

 

ordered_access = TRUE

{A1, A2, B1, B2, C1, C2}

access_scope = INSTANCE

 

 

 

ordered_access = TRUE

{A1, B1, C1, A2, B2, C2}

access_scope = TOPIC

 

 

 

To illustrate the effect of a PRESENTATION QosPolicy with GROUP access_scope, assume the following sequence of samples was written by two DataWriters, W1 and W2, within the same Publisher: {(W1,A1), (W2,B1), (W1,C1), (W2,A2), (W1,B2), (W2,C2)}. As in the previous example, A, B, and C represent different instances (i.e., different keys). With access_scope set to INSTANCE or TOPIC, the middleware cannot guarantee that the application will receive the samples in the same order they were published by W1 and W2. With access_scope set to GROUP, the middleware is able to provide the samples in order to the application as long as the read()/take() operations are invoked within a begin_access()/end_access() block (see Section 7.2.5).

Table 6.26 Effect of ordered_access for access_scope GROUP

 

Sequence retrieved via “read()”.

PRESENTATION QoS

Order sent was {(W1,A1), (W2,B1), (W1,C1), (W2,A2),

 

(W1,B2), (W2,C2)}

 

 

 

 

ordered_access = FALSE

The order across DataWriters will not be preserved. Samples

may be delivered in multiple orders. For example:

or

{(W1,A1), (W1,C1), (W1,B2), (W2,B1), (W2,A2), (W2,C2)}

access_scope = TOPIC or INSTANCE

{(W1,A1), (W2,B1), (W1,B2), (W1,C1), (W2,A2), (W2,C2)}

 

 

 

ordered_access = TRUE

Samples are delivered in the same order they were published:

access_scope = GROUP

{(W1,A1), (W2,B1), (W1,C1), (W2,A2), (W1,B2), (W2,C2)}

 

 

6-69

6.4.6.4Properties

This QosPolicy cannot be modified after the Publisher or Subscriber is enabled.

This QoS must be set compatibly between the DataWriter’s Publisher and the DataReader’s Subscriber. The compatible combinations are shown in Table 6.27 and Table 6.28 for ordered_access and Table 6.29 for coherent_access.

Table 6.27 Valid Combinations of ordered_access and access_scope, with Subscriber’s ordered_access = False

{ordered_access/access_scope}

 

 

Subscriber Requests:

 

 

 

 

 

 

 

False/Instance

False/Topic

False/Group

False/Highest

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

False/Instance

 

incompatible

incompatible

 

 

 

 

 

 

 

 

False/Topic

 

incompatible

 

 

 

 

 

 

 

Publisher

False/Group

 

 

 

 

 

 

 

offers:

True/Instance

 

incompatible

incompatible

 

 

 

 

 

 

 

 

True/Topic

 

incompatible

 

 

 

 

 

 

 

 

True/Group

 

 

 

 

 

 

 

 

Table 6.28 Valid Combinations of ordered_access and access_scope, with Subscriber’s ordered_access = True

 

{ordered_access/access_scope}

 

 

 

 

Subscriber Requests:

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

True/Instance

 

True/Topic

 

True/Group

 

True/Highest

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

False/Instance

 

 

incompatible

 

incompatible

 

incompatible

 

incompatible

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

False/Topic

 

 

incompatible

 

incompatible

 

incompatible

 

incompatible

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Publisher

False/Group

 

 

incompatible

 

incompatible

 

incompatible

 

incompatible

 

 

 

 

 

 

 

 

 

 

 

 

 

 

offers:

True/Instance

 

 

 

incompatible

 

incompatible

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

True/Topic

 

 

 

 

incompatible

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

True/Group

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Table 6.29 Valid Combinations of Presentation Coherent Access and Access Scope

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

{coherent_access/access_scope}

 

 

 

 

Subscriber requests:

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

False/Instance

 

False/Topic

 

True/Instance

 

True/Topic

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

False/Instance

 

 

 

incompatible

 

incompatible

 

incompatible

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Publisher

False/Topic

 

 

 

 

incompatible

 

incompatible

 

 

 

 

 

 

 

 

 

 

 

 

 

 

offers:

True/Instance

 

 

 

incompatible

 

 

incompatible

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

True/Topic

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

6.4.6.5Related QosPolicies

The DESTINATION_ORDER QosPolicy (Section 6.5.6) is closely related and also affects the ordering of data samples on a per-instance basis when there are multiple DataWriters.

The DATA_READER_PROTOCOL QosPolicy (DDS Extension) (Section 7.6.1) may be used to configure the sample ordering process in the Subscribers configured with GROUP or

HIGHEST_OFFERED access_scope.

6.4.6.6Applicable Entities

Publishers (Section 6.2)

6-70

Subscribers (Section 7.2)

6.4.6.7System Resource Considerations

The use of this policy does not significantly impact the usage of resources.

6.5DataWriter QosPolicies

This section provides detailed information about the QosPolicies associated with a DataWriter. Table 6.16 on page 6-44 provides a quick reference. They are presented here in alphabetical order.

AVAILABILITY QosPolicy (DDS Extension) (Section 6.5.1)

BATCH QosPolicy (DDS Extension) (Section 6.5.2)

DATA_WRITER_PROTOCOL QosPolicy (DDS Extension) (Section 6.5.3)

DATA_WRITER_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 6.5.4)

DEADLINE QosPolicy (Section 6.5.5)

DESTINATION_ORDER QosPolicy (Section 6.5.6)

DURABILITY QosPolicy (Section 6.5.7)

DURABILITY SERVICE QosPolicy (Section 6.5.8)

ENTITY_NAME QosPolicy (DDS Extension) (Section 6.5.9)

HISTORY QosPolicy (Section 6.5.10)

LATENCYBUDGET QoS Policy (Section 6.5.11)

LIFESPAN QoS Policy (Section 6.5.12)

LIVELINESS QosPolicy (Section 6.5.13)

MULTI_CHANNEL QosPolicy (DDS Extension) (Section 6.5.14)

OWNERSHIP QosPolicy (Section 6.5.15)

OWNERSHIP_STRENGTH QosPolicy (Section 6.5.16)

PROPERTY QosPolicy (DDS Extension) (Section 6.5.17)

PUBLISH_MODE QosPolicy (DDS Extension) (Section 6.5.18)

RELIABILITY QosPolicy (Section 6.5.19)

RESOURCE_LIMITS QosPolicy (Section 6.5.20)

TRANSPORT_PRIORITY QosPolicy (Section 6.5.21)

TRANSPORT_SELECTION QosPolicy (DDS Extension) (Section 6.5.22)

TRANSPORT_UNICAST QosPolicy (DDS Extension) (Section 6.5.23)

TYPESUPPORT QosPolicy (DDS Extension) (Section 6.5.24)

USER_DATA QosPolicy (Section 6.5.25)

WRITER_DATA_LIFECYCLE QoS Policy (Section 6.5.26)

6.5.1AVAILABILITY QosPolicy (DDS Extension)

This QoS policy configures the availability of data and it is used in the context of two features:

Collaborative DataWriters (Section 6.5.1.1)

6-71

Required Subscriptions (Section 6.5.1.2)

It contains the members listed in Table 6.30.

Table 6.30 DDS_AvailabilityQosPolicy

 

Type

 

Field Name

Description

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Enables support for required subscriptions in a

 

DDS_Boolean

enable_required_subscripti

DataWriter.

 

 

 

ons

 

For Collaborative DataWriters: Not applicable.

 

 

 

 

 

 

 

 

 

 

 

For Required Subscriptions: See Table 6.33.

 

 

 

 

 

 

 

 

 

 

 

 

 

Defines how much time to wait before delivering a

 

struct

 

max_data_availability_

sample to the application without having received some

 

 

of the previous samples.

 

DDS_Duration_t

waiting_time

For Collaborative DataWriters: See Table 6.32.

 

 

 

 

 

 

 

 

 

 

 

 

For Required Subscriptions: Not applicable.

 

 

 

 

 

 

 

 

 

 

 

 

 

Defines how much time to wait to discover DataWriters

 

struct

 

max_endpoint_availability_

providing samples for the same data source.

 

DDS_Duration_t

waiting_time

For Collaborative DataWriters: See Table 6.32.

 

 

 

 

 

 

For Required Subscriptions: Not applicable.

 

 

 

 

 

 

 

 

struct

 

required_matched_

A sequence of endpoint groups, described in Table 6.31.

 

 

 

 

DDS_Endpoint-

For Collaborative DataWriters: See Table 6.32.

 

endpoint_groups

 

GroupSeq

 

For Required Subscriptions: See Table 6.33

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Table 6.31 struct DDS_EndpointGroup_t

 

 

 

 

 

 

 

 

Type

 

Field Name

 

Description

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Defines the role name of the endpoint group.

 

char *

 

role_name

If used in the AvailabilityQosPolicy on a DataWriter, it specifies the name that

 

 

 

 

 

identifies a Required Subscription.

 

 

 

 

 

 

 

 

 

 

 

Defines the minimum number of members that satisfies the endpoint group.

 

int

 

quorum_count

If used in the AvailabilityQosPolicy on a DataWriter, it specifies the number of

 

 

 

 

 

DataReaders with a specific role name that must acknowledge a sample before

 

 

 

 

 

the sample is considered to be acknowledged by the Required Subscription.

 

 

 

 

 

 

 

6.5.1.1Availability QoS Policy and Collaborative DataWriters

The Collaborative DataWriters feature allows you to have multiple DataWriters publishing samples from a common logical data source. The DataReaders will combine the samples coming from the DataWriters in order to reconstruct the correct order at the source. The Availability QosPolicy allows you to configure the sample combination (synchronization) process in the

DataReader.

Each sample published in a DDS domain for a given logical data source is uniquely identified by a pair (virtual GUID, virtual sequence number). Samples from the same data source (same virtual GUID) can be published by different DataWriters.

A DataReader will deliver a sample (VGUIDn, VSNm) to the application if one of the following conditions is satisfied:

(GUIDn, SNm-1) has already been delivered to the application.

All the known DataWriters publishing VGUIDn have announced that they do not have (VGUIDn, VSNm-1).

6-72

None of the known DataWriters publishing VGUIDn have announced potential availability of (VGUIDn, VSNm-1) and both timeouts in this QoS policy have expired.

A DataWriter announces potential availability of samples by using virtual heartbeats. The frequency at which virtual heartbeats are sent is controlled by the protocol parameters virtual_heartbeat_period and samples_per_virtual_ heartbeat (see Table 6.36, “DDS_RtpsReliableWriterProtocol_t,” on page 6-81).

Table 6.32 describes the fields of this policy when used for a Collaborative DataWriter.

For further information, see Chapter 11: Collaborative DataWriters.

Table 6.32 Configuring Collaborative DataWriters with DDS_AvailabilityQosPolicy

Field Name

 

Description for Collaborative DataWriters

 

 

 

 

 

 

Defines how much time to wait before delivering a sample to the

 

application without having received some of the previous samples.

 

 

A sample identified by (VGUIDn, VSNm) will be delivered to the

 

application if this timeout expires for the sample and the following two

max_data_availability_

conditions are satisfied:

 

 

waiting_time

None of the known DataWriters publishing VGUIDn have announced

 

 

potential availability of (VGUIDn, VSNm-1).

 

 

 

The DataWriters for all the endpoint groups

specified

in

 

 

required_matched_endpoint_groups have been

discovered

or

 

 

max_endpoint_availability_waiting_time has expired.

 

 

 

 

 

Defines how much time to wait to discover DataWriters providing samples

 

for the same data source.

 

 

 

The set of endpoint groups that are required to provide samples for a data

max_endpoint_availability_

source can be configured using required_matched_endpoint_groups.

 

waiting_time

A non-consecutive sample identified by (GUIDn, SNm) cannot be delivered

 

 

to the application unless the DataWriters for all the endpoint groups in

 

required_matched_endpoint_groups are discovered or this timeout

 

expires.

 

 

 

 

 

Specifies the set of endpoint groups that are expected to provide samples for

 

the same data source.

 

 

 

The quorum count in a group represents the number of DataWriters that

 

must be discovered for that group before the DataReader is allowed to

required_matched_

provide non consecutive samples to the application.

 

 

A DataWriter becomes a member of an endpoint group by configuring the

endpoint_groups

role_name in the DataWriter’s ENTITY_NAME QosPolicy (DDS Extension)

 

 

(Section 6.5.9).

 

 

 

The DataWriters created by RTI Persistence Service have a predefined

 

role_name of ‘PERSISTENCE_SERVICE’. For other DataWriters, the

 

role_name is not set by default.

 

 

 

 

 

 

 

6.5.1.2Availability QoS Policy and Required Subscriptions

In the context of Required Subscriptions, the Availability QosPolicy can be used to configure a set of required subscriptions on a DataWriter.

Required Subscriptions are preconfigured, named subscriptions that may leave and subsequently rejoin the network from time to time, at the same or different physical locations. Any time a required subscription is disconnected, any samples that would have been delivered to it are stored for delivery if and when the subscription rejoins the network.

Table 6.33 describes the fields of this policy when used for a Required Subscription. For further information, see Required Subscriptions (Section 6.3.13).

6-73

Table 6.33 Configuring Required Subscriptions with DDS_AvailabilityQosPolicy

Field Name

Description for Required Subscriptions

 

 

 

 

enable_required_subscriptio

Enables support for Required Subscriptions in a DataWriter.

ns

 

max_data_availability_

 

waiting_time

Not applicable to Required Subscriptions.

 

max_endpoint_availability_

 

waiting_time

 

 

 

 

A sequence of endpoint groups that specify the Required Subscriptions on a

 

DataWriter.

 

Each Required Subscription is specified by a name and a quorum count.

required_matched_

The quorum count represents the number of DataReaders that have to

acknowledge the sample before it can be considered fully acknowledged

endpoint_groups

for that Required Subscription.

 

 

A DataReader is associated with a Required Subscription by configuring the

 

role_name in the DataReader’s ENTITY_NAME QosPolicy (DDS Extension)

 

(Section 6.5.9).

 

 

6.5.1.3Properties

For DataWriters, all the members in this QosPolicy can be changed after the DataWriter is created except for the member enable_required_subscriptions.

For DataReaders, this QosPolicy cannot be changed after the DataReader is created.

There are no compatibility restrictions for how it is set on the publishing and subscribing sides.

6.5.1.4Related QosPolicies

ENTITY_NAME QosPolicy (DDS Extension) (Section 6.5.9)

DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4)

DURABILITY QosPolicy (Section 6.5.7)

6.5.1.5Applicable Entities

DataWriters (Section 6.3)

DataReaders (Section 7.3)

6.5.1.6System Resource Considerations

The resource limits for the endpoint groups in required_matched_endpoint_groups are determined by two values in the DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4):

max_endpoint_groups

max_endpoint_group_cumulative_characters

The maximum number of virtual writers (identified by a virtual GUID) that can be managed by a DataReader is determined by the max_remote_virtual_writers in DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 7.6.2). When the

Subscriber’s access_scope is GROUP, max_remote_virtual_writers determines the maximum

6-74

number of DataWriter groups supported by the Subscriber. Since the Subscriber may contain more than one DataReader, only the setting of the first applies.

6.5.2BATCH QosPolicy (DDS Extension)

This QosPolicy can be used to decrease the amount of communication overhead associated with the transmission and (in the case of reliable communication) acknowledgement of small samples, in order to increase throughput.

It specifies and configures the mechanism that allows Connext to collect multiple user data samples to be sent in a single network packet, to take advantage of the efficiency of sending larger packets and thus increase effective throughput.

This QosPolicy can be used to increase effective throughput dramatically for small data samples. Throughput for small samples (size < 2048 bytes) is typically limited by CPU capacity and not by network bandwidth. Batching many smaller samples to be sent in a single large packet will increase network utilization and thus throughput in terms of samples per second.

It contains the members listed in Table 6.34.

Table 6.34 DDS_BatchQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

DDS_Boolean

enable

Enables/disables batching.

 

 

 

 

 

Sets the maximum cumulative length of all serialized

 

 

samples in a batch.

DDS_Long

max_data_bytes

Before or when this limit is reached, the batch is

automatically flushed.

 

 

 

 

The size does not include the meta-data associated with the

 

 

batch samples.

 

 

 

 

 

Sets the maximum number of samples in a batch.

DDS_Long

max_samples

When this limit is reached, the batch is automatically

 

 

flushed.

 

 

 

 

 

Sets the maximum flush delay.

 

 

When this duration is reached, the batch is automatically

struct DDS_Duration_t

max_flush_delay

flushed.

 

 

The delay is measured from the time the first sample in the

 

 

batch is written by the application.

 

 

 

6-75

Table 6.34 DDS_BatchQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Sets the batch source timestamp resolution.

 

 

 

 

The value of this field determines how the source

 

 

timestamp is associated with the samples in a batch.

 

 

 

A sample written with timestamp 't' inherits the source

 

 

timestamp 't2' associated with the previous sample, unless

 

 

('t' - 't2') is greater than source_timestamp_resolution.

 

 

source_timestamp_

If source_timestamp_resolution is DURATION_INFINITE,

struct DDS_Duration_t

every sample in the batch will share the source timestamp

resolution

associated with the first sample.

 

 

 

 

 

If source_timestamp_resolution is zero, every sample in

 

 

the batch will contain its own source timestamp

 

 

corresponding to the moment when the sample was

 

 

written.

 

 

 

 

 

The performance of the batching process is better when

 

 

source_timestamp_resolution

is

set

to

 

 

DURATION_INFINITE.

 

 

 

 

 

 

 

 

Determines whether or not the write operation is thread-

 

 

safe.

 

 

 

DDS_Boolean

thread_safe_write

If TRUE, multiple threads can call write on the DataWriter

concurrently.

 

 

 

 

 

 

 

 

 

 

A setting of FALSE can be used to increase batching

 

 

throughput for batches with many small samples.

 

 

 

 

 

 

 

If batching is enabled (not the default), samples are not immediately sent when they are written. Instead, they get collected into a "batch." A batch always contains whole number of samples—a sample will never be fragmented into multiple batches.

A batch is sent on the network ("flushed") when one of the following things happens:

User-configurable flushing conditions

A batch size limit (max_data_bytes) is reached.

A number of samples are in the batch (max_samples).

A time-limit (max_flush_delay) is reached, as measured from the time the first sam- ple in the batch is written by the application.

The application explicitly calls a DataWriter's flush() operation.

Non-user configurable flushing conditions:

A coherent set starts or ends.

The number of samples in the batch is equal to max_samples in RESOURCE_LIMITS for unkeyed topics or max_samples_per_instance in RESOURCE_LIMITS for keyed topics.

Additional batching configuration takes place in the Publisher’s ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension) (Section 6.4.1).

The flush() operation is described in Flushing Batches of Data Samples (Section 6.3.9).

6.5.2.1Synchronous and Asynchronous Flushing

Usually, a batch is flushed synchronously:

When a batch reaches its application-defined size limit (max_data_bytes or max_samples) because the application called write(), the batch is flushed immediately in the context of the writing thread.

6-76

When an application manually flushes a batch, the batch is flushed immediately in the context of the calling thread.

When the first sample in a coherent set is written, the batch in progress (without including the sample in the coherent set) is immediately flushed in the context of the writing thread.

When a coherent set ends, the batch in progress is immediately flushed in the context of the calling thread.

When the number of samples in a batch is equal to max_samples in RESOURCE_LIMITS for unkeyed topics or max_samples_per_instance in RESOURCE_LIMITS for keyed topics, the batch is flushed immediately in the context of the writing thread.

However, some behavior is asynchronous:

To flush batches based on a time limit (max_flush_delay), enable asynchronous batch flushing in the ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension) (Section 6.4.1) of the DataWriter's Publisher. This will cause the Publisher to create an additional thread that will be used to flush batches of that Publisher's DataWriters. This behavior is analogous to the way asynchronous publishing works.

You may also use batching alongside asynchronous publication with FlowControllers (DDS Extension) (Section 6.6). These features are independent of one another. Flushing a batch on an asynchronous DataWriter makes it available for sending to the DataWriter's FlowController. From the point of view of the FlowController, a batch is treated like one large sample.

6.5.2.2Batching vs. Coalescing

Even when batching is disabled, Connext will sometimes coalesce multiple samples into a single network datagram. For example, samples buffered by a FlowController or sent in response to a negative acknowledgement (NACK) may be coalesced. This behavior is distinct from sample batching.

Samples that are sent individually (not part of a batch) are always treated as separate samples by Connext. Each sample is accompanied by a complete RTPS header on the network (although samples may share UDP and IP headers) and (in the case of reliable communication) a unique physical sequence number that must be positively or negatively acknowledged.

In contrast, batched samples share an RTPS header and an entire batch is acknowledged — positively or negatively—as a unit, potentially reducing the amount of meta-traffic on the network and the amount of processing per individual sample.

Batching can also improve latency relative to simply coalescing. Consider two use cases:

1.A DataWriter is configured to write asynchronously with a FlowController. Even if the FlowController's rules would allow it to publish a new sample immediately, the send will always happen in the context of the asynchronous publishing thread. This context switch can add latency to the send path.

2.A DataWriter is configured to write synchronously but with batching turned on. When the batch is full, it will be sent on the wire immediately, eliminating a thread context switch from the send path.

6-77

6.5.2.3Batching and ContentFilteredTopics

When batching is enabled, content filtering is always done on the reader side.

6.5.2.4Performance Considerations

The purpose of batching is to increase throughput when writing small samples at a high rate. In such cases, throughput can be increased several-fold, approaching much more closely the physical limitations of the underlying network transport.

However, collecting samples into a batch implies that they are not sent on the network immediately when the application writes them; this can potentially increase latency. However, if the application sends data faster than the network can support, an increased proportion of the network's available bandwidth will be spent on acknowledgements and sample resends. In this case, reducing that overhead by turning on batching could decrease latency while increasing throughput.

As a general rule, to improve batching throughput:

Set thread_safe_write to FALSE when the batch contains a big number of small samples. If you do not use a thread-safe write configuration, asynchronous batch flushing must be disabled.

Set source_timestamp_resolution to DURATION_INFINITE. Note that you set this value, every sample in the batch will share the same source timestamp.

Batching affects how often piggyback heartbeats are sent; see heartbeats_per_max_samples in Table 6.36, “DDS_RtpsReliableWriterProtocol_t,” on page 6-81.

6.5.2.5Maximum Transport Datagram Size

Batches cannot be fragmented. As a result, the maximum batch size (max_data_bytes) must be set no larger than the maximum transport datagram size. For example, a UDP datagram is limited to 64 KB, so any batches sent over UDP must be less than or equal to that size.

6.5.2.6Properties

This QosPolicy cannot be modified after the DataWriter is enabled.

Since it is only for DataWriters, there are no compatibility restrictions for how it is set on the publishing and subscribing sides.

All batching configuration occurs on the publishing side. A subscribing application does not configure anything specific to receive batched samples, and in many cases, it will be oblivious to whether the samples it processes were received individually or as part of a batch.

Consistency rules:

max_samples must be consistent with max_data_bytes: they cannot both be set to LENGTH_UNLIMITED.

If max_flush_delay is not DURATION_INFINITE, disable_asynchronous_batch in the ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension) (Section 6.4.1) must be FALSE.

If thread_safe_write is FALSE, source_timestamp_resolution must be DURATION_INFINITE.

6.5.2.7Related QosPolicies

To flush batches based on a time limit, enable batching in the ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension) (Section 6.4.1) of the

DataWriter's Publisher.

6-78

Be careful when configuring a DataWriter's LIFESPAN QoS Policy (Section 6.5.12) with a duration shorter than the batch flush period (max_flush_delay). If the batch does not fill up before the flush period elapses, the short duration will cause the samples to be lost without being sent.

Do not configure the DataReader’s or DataWriter’s HISTORY QosPolicy (Section 6.5.10) to be shallower than the DataWriter's maximum batch size (max_samples). When the HISTORY QosPolicy is shallower on the DataWriter, some samples may not be sent. When the HISTORY QosPolicy is shallower on the DataReader, samples may be dropped before being provided to the application.

The initial and maximum numbers of batches that a DataWriter will manage is set in the DATA_WRITER_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 6.5.4).

The maximum number of samples that a DataWriter can store is determined by the value max_samples in the RESOURCE_LIMITS QosPolicy (Section 6.5.20) and max_batches in the DATA_WRITER_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 6.5.4). The limit that is reached first is applied.

The amount of resources required for batching depends on the configuration of the RESOURCE_LIMITS QosPolicy (Section 6.5.20) and the DATA_WRITER_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 6.5.4). See Section 6.5.2.9.

6.5.2.8Applicable Entities

DataWriters (Section 6.3)

6.5.2.9System Resource Considerations

Batching requires additional resources to store the meta-data associated with the samples in the batch.

For unkeyed topics, the meta-data will be at least 8 bytes, with a maximum of 20 bytes.

For keyed topics, the meta-data will be at least 8 bytes, with a maximum of 52 bytes.

Other resource considerations are described in Section 6.5.2.7.

6.5.3DATA_WRITER_PROTOCOL QosPolicy (DDS Extension)

Connext uses a standard protocol for packet (user and meta data) exchange between applications. The DataWriterProtocol QosPolicy gives you control over configurable portions of the protocol, including the configuration of the reliable data delivery mechanism of the protocol on a per DataWriter basis.

These configuration parameters control timing and timeouts, and give you the ability to trade off between speed of data loss detection and repair, versus network and CPU bandwidth used to maintain reliability.

It is important to tune the reliability protocol on a per DataWriter basis to meet the requirements of the end-user application so that data can be sent between DataWriters and DataReaders in an efficient and optimal manner in the presence of data loss. You can also use this QosPolicy to

6-79

control how Connext responds to "slow" reliable DataReaders or ones that disconnect or are otherwise lost.

This policy includes the members presented in Table 6.35, “DDS_DataWriterProtocolQosPolicy,” on page 6-80 and Table 6.36, “DDS_RtpsReliableWriterProtocol_t,” on page 6-81. For defaults and valid ranges, please refer to the API Reference HTML documentation.

For details on the reliability protocol used by Connext, see Chapter 10: Reliable Communications. See the RELIABILITY QosPolicy (Section 6.5.19) for more information on per- DataReader/DataWriter reliability configuration. The HISTORY QosPolicy (Section 6.5.10) and RESOURCE_LIMITS QosPolicy (Section 6.5.20) also play important roles in the DDS reliability protocol.

Table 6.35 DDS_DataWriterProtocolQosPolicy

Type

Field Name

 

 

 

Description

 

 

 

 

 

 

 

 

 

 

 

The virtual GUID (Global Unique Identifier) is used to uniquely identify

 

 

the same DataWriter across multiple incarnations. In other words, this

 

 

value allows Connext to remember information about a DataWriter that

 

 

may be deleted and then recreated.

 

 

 

 

 

 

Connext uses the virtual GUID to associate a durable writer history to a

 

 

DataWriter.

 

 

 

 

 

 

 

 

Persistence Servicea uses the virtual GUID to send samples on behalf of the

 

 

original DataWriter.

 

 

 

 

 

DDS_GUID_t

virtual_guid

A DataReader persists its state based on the virtual GUIDs of matching

 

 

remote DataWriters.

 

 

 

 

 

 

 

For more information, see Durability and Persistence Based on Virtual

 

 

GUIDs (Section 12.2).

 

 

 

 

 

 

 

By default, Connext will assign a virtual GUID automatically. If you want

 

 

to restore the state of the durable writer history after a restart, you can

 

 

retrieve the value of the writer's virtual GUID using the DataWriter’s

 

 

get_qos() operation, and set the virtual GUID of the restarted DataWriter to

 

 

the same value.

 

 

 

 

 

 

 

 

 

 

Determines the DataWriter’s RTPS object ID, according to the DDS-RTPS

 

 

Interoperability Wire Protocol.

 

 

 

 

 

 

Only the last 3 bytes are used; the most significant byte is ignored.

 

DDS_Unsigned-

rtps_object_id

The

rtps_host_id,

rtps_app_id,

rtps_instance_id

in

the

Long

WIRE_PROTOCOL QosPolicy (DDS Extension) (Section 8.5.9), together

 

 

 

with the 3 least significant bytes in rtps_object_id, and another byte

 

 

assigned by Connext to identify the entity type, forms the BuiltinTopicKey

 

 

in PublicationBuiltinTopicData.

 

 

 

 

 

 

 

 

 

Controls when a sample is sent after write() is called on a DataWriter. If

DDS_Boolean

push_on_write

TRUE, the sample is sent immediately; if FALSE, the sample is put in a

 

 

queue until an ACK/NACK is received from a reliable DataReader.

 

 

 

 

 

 

 

 

 

 

 

Determines

whether

matching

DataReaders

send

positive

 

 

acknowledgements (ACKs) to the DataWriter.

 

 

 

DDS_Boolean

disable_positive_

When TRUE, the DataWriter will keep samples in its queue for ACK-

acks

disabled readers for a minimum keep duration (see Section 6.5.3.3).

 

 

 

 

 

When strict reliability is not required, setting this to TRUE reduces

 

 

overhead network traffic.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

6-80

Table 6.35 DDS_DataWriterProtocolQosPolicy

Type

Field Name

 

Description

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Controls whether or not the key-hash is propagated on the wire with

 

 

samples.

 

 

 

 

 

This field only applies to keyed writers.

 

 

 

 

 

Connext associates a key-hash (an internal 16-byte representation) with

 

 

each key.

 

 

 

 

 

When FALSE, the key-hash is sent on the wire with every data instance.

 

 

When TRUE, the key-hash is not sent on the wire (so the readers must

DDS_Boolean

disable_inline_

compute the value using the received data).

 

 

 

If the reader is CPU bound, sending the key-hash on the wire may increase

keyhash

 

 

 

performance, because the reader does not have to get the key-hash from

 

 

the data.

 

 

 

 

 

If the writer is CPU bound, sending the key-hash on the wire may

 

 

decrease performance, because it requires more bandwidth (16 more

 

 

bytes per sample).

 

 

 

 

 

 

 

 

 

 

 

 

Note: Setting disable_inline_keyhash to TRUE is not compatible

 

 

 

 

with using RTI Real-Time Connect or RTI Recording Service.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Controls whether or not the serialized key is propagated on the wire with

 

 

dispose notifications.

 

 

 

 

 

This field only applies to keyed writers.

 

 

 

 

serialize_key_

RTI recommends setting this field to TRUE if there are DataReaders with

DDS_Boolean

propagate_dispose_of_unregistered_instances

(in

the

with_dispose

DATA_READER_PROTOCOL QosPolicy (DDS Extension) (Section 7.6.1))

 

 

 

also set to TRUE.

 

 

 

 

 

Important: When this field TRUE, batching will not be compatible with

 

 

RTI Data Distribution Service 4.3e, 4.4b, or 4.4c—the DataReaders will

 

 

receive incorrect data and/or encounter deserialization errors.

 

 

 

 

 

 

 

 

DDS_RtpsReliable

rtps_reliable_

This structure includes the fields in Table 6.36.

 

 

 

WriterProtocol_t

writer

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

a. Persistence Service is included with Connext Messaging. It saves data samples so they can be delivered to subscribing applications that join the system at a later time (see Chapter 26: Introduction to RTI Persistence Service).

Table 6.36 DDS_RtpsReliableWriterProtocol_t

Type

Field Name

 

 

 

 

Description

 

 

 

 

 

 

 

 

 

low_watermark

Queue levels that control when to switch between the regular

DDS_Long

 

and

fast

heartbeat

rates

(heartbeat_period

and

high_watermark

 

fast_heartbeat_period). See Section 6.5.3.1.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

heartbeat_period

Rates at which to sent heartbeats to DataReaders with

 

 

DDS_Duration_t

fast_heartbeat_period

unacknowledged

samples.

See

Section 6.5.3.2

and

 

late_joiner_heartbeat_

Section 10.3.4.1.

 

 

 

 

 

 

period

 

 

 

 

 

 

 

 

 

 

 

 

 

The rate at which a reliable DataWriter will send virtual

DDS_Duration_t

virtual_heartbeat_period

heartbeats. Virtual

heartbeat informs

the reliable DataReader

about the range of samples currently present for each virtual

 

 

 

 

GUID in the reliable writer's queue. See Section 6.5.3.6.

 

 

 

 

DDS_Long

samples_per_virtual_

The number of samples that a reliable DataWriter must publish

heartbeat

before sending a virtual heartbeat. See Section 6.5.3.6.

 

 

 

 

 

 

 

 

 

 

 

 

 

6-81

Table 6.36 DDS_RtpsReliableWriterProtocol_t

Type

Field Name

 

 

Description

 

 

 

 

 

 

 

 

 

 

Maximum number of periodic heartbeats sent without receiving

 

 

an ACK/NACK packet before marking a DataReader ‘inactive.’

 

 

 

When a DataReader has not acknowledged all the samples the

 

 

reliable DataWriter has sent to it, and max_heartbeat_retries

DDS_Long

max_heartbeat_retries

number of periodic heartbeats have been sent without receiving

any ACK/NACK packets in return, the DataReader will be

 

 

 

 

marked as inactive (not alive) and be ignored until it resumes

 

 

sending ACK/NACKs.

 

 

 

 

 

Note that piggyback heartbeats do not count towards this value.

 

 

 

See Section 10.3.4.4.

 

 

 

 

 

 

 

inactivate_nonprogressing_

Allows the DataWriter to treat DataReaders that send successive

DDS_Boolean

non-progressing NACK packets as inactive.

 

 

readers

See Section 10.3.4.5.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

For non-multichannel DataWriters:

 

 

 

 

If batching is disabled:

 

 

 

 

 

 

A piggyback heartbeat will be sent every

 

 

 

 

[max_samples/heartbeats_per_max_samples]

 

 

 

 

number of samples.

 

 

 

 

 

 

heartbeats_per_max_samples must be

 

 

 

 

<= writer_qos.resource_limits.max_samples

 

 

 

If batching is enabled:

 

 

 

 

 

 

A piggyback heartbeat will be sent every

 

 

 

 

[max_batches/heartbeats_per_max_samples]

 

 

 

 

number of samples.

 

 

 

DDS_Long

heartbeats_per_max_

 

heartbeats_per_max_samples must be

 

samples

 

<= writer_qos.resource_limits.max_batches

 

 

 

 

 

 

For multi-channel DataWriters:

 

 

 

 

 

A piggyback heartbeat will be sent on a channel every

 

 

 

 

[max_samples/heartbeats_per_max_samples] number of

 

 

 

samples sent of that channel.

 

 

 

 

 

heartbeats_per_max_samples must be

 

 

 

 

<= writer_qos.resource_limits.max_samples.

 

 

 

See Section 18.6.2 for additional details related to the multi-

 

 

channel DataWriter reliability protocol.

 

 

 

 

If

max_samples

or

max_batches

is

 

 

DDS_LENGTH_UNLIMITED, 100 million is assumed as the

 

 

maximum value in the calculation.

 

 

 

 

 

 

 

 

Minimum delay to respond to an ACK/NACK.

 

 

 

When a reliable DataWriter receives an ACK/NACK from a

DDS_Duration_t

min_nack_response_delay

DataReader, the DataWriter can choose to delay a while before it

sends repair samples or a heartbeat. This set the value of the

 

 

 

 

minimum delay.

 

 

 

 

 

See Section 10.3.4.6.

 

 

 

 

 

 

 

 

 

Maximum delay to respond to a ACK/NACK.

 

 

 

This sets the value of maximum delay between receiving an

 

 

ACK/NACK and sending repair samples or a heartbeat.

 

DDS_Duration_t

max_nack_response_delay

A longer wait can help prevent storms of repair packets if many

DataReaders send NACKs at the same time. However, it delays

 

 

 

 

the repair, and hence increases the latency of the

 

 

communication.

 

 

 

 

 

See Section 10.3.4.6.

 

 

 

 

 

 

 

 

 

 

6-82

Table 6.36 DDS_RtpsReliableWriterProtocol_t

Type

Field Name

Description

 

 

 

 

 

 

 

 

How long consecutive NACKs are suppressed.

 

 

When a reliable DataWriter receives consecutive NACKs within

DDS_Duration_t

nack_suppression_duration

a short duration, this may trigger the DataWriter to send

 

 

redundant repair messages. This value sets the duration during

 

 

which consecutive NACKs are ignored, thus preventing

 

 

redundant repairs from being sent.

 

 

 

 

 

Maximum bytes in a repair package.

DDS_Long

max_bytes_per_nack_

When a reliable DataWriter resends samples, the total package

response

size is limited to this value.

 

 

 

See Section 10.3.4.3.

 

 

 

 

disable_positive_acks_

Minimum duration that a sample will be kept in the DataWriter’s

 

min_sample_keep_

queue for ACK-disabled DataReaders.

DDS_Duration_t

duration

See Section 6.5.3.3 and Section 10.3.4.7.

 

 

disable_positive_acks_

Maximum duration that a sample will be kept in the

 

 

max_sample_keep_

 

DataWriter’s queue for ACK-disabled readers.

 

duration

 

 

 

 

 

 

disable_positive_acks_

Enables automatic dynamic adjustment of the ‘keep duration’ in

DDS_Boolean

enable_adaptive_

response to network congestion.

 

sample_keep_duration

 

 

 

 

 

 

 

When the ‘keep duration’ is dynamically controlled, the

 

 

lengthening of the ‘keep duration’ is controlled by this factor,

 

 

which is expressed as a percentage.

 

disable_positive_acks_

When the adaptive algorithm determines that the keep duration

 

increase_sample_

should be increased, this factor is multiplied with the current

 

keep_duration_factor

keep duration to get the new longer keep duration. For example,

 

 

if the current keep duration is 20 milliseconds, using the default

 

 

factor of 150% would result in a new keep duration of 30

DDS_Long

 

milliseconds.

 

 

 

When the ‘keep duration’ is dynamically controlled, the

 

 

 

 

shortening of the ‘keep duration’ is controlled by this factor,

 

 

which is expressed as a percentage.

 

disable_positive_acks_

When the adaptive algorithm determines that the keep duration

 

decrease_sample_

should be decreased, this factor is multiplied with the current

 

keep_duration_factor

keep duration to get the new shorter keep duration. For

 

 

example, if the current keep duration is 20 milliseconds, using

 

 

the default factor of 95% would result in a new keep duration of

 

 

19 milliseconds.

 

 

 

 

min_send_window_size

Minimum and maximum size for the window of outstanding

DDS_Long

 

samples.

max_send_window_size

 

See Configuring the Send Window Size (Section 6.5.3.4).

 

 

 

 

 

 

 

Scales the current send-window size down by this percentage to

DDS_Long

send_window_decrease_

decrease the effective send-rate in response to received negative

factor

acknowledgement.

 

 

 

See Configuring the Send Window Size (Section 6.5.3.4).

 

 

 

 

 

Controls whether or not periodic heartbeat messages are sent

 

 

over multicast.

 

enable_multicast_periodic_

When enabled, if a reader has a multicast destination, the writer

DDS_Boolean

will send its periodic HEARTBEAT messages to that destination.

 

heartbeat

Otherwise, if not enabled or the reader does not have a multicast

 

 

 

 

destination, the writer will send its periodic HEARTBEATs over

 

 

unicast.

 

 

 

6-83

Table 6.36 DDS_RtpsReliableWriterProtocol_t

Type

Field Name

Description

 

 

 

 

 

 

 

 

Sets the minimum number of requesting readers needed to

DDS_Long

multicast_resend_threshold

trigger a multicast resend.

 

 

See Resending Over Multicast (Section 6.5.3.7).

 

 

 

 

 

Scales the current send-window size up by this percentage to

DDS_Long

send_window_increase_

increase the effective send-rate when a duration has passed

factor

without any received negative acknowledgements.

 

 

 

See Configuring the Send Window Size (Section 6.5.3.4)

 

 

 

 

 

Period in which DataWriter checks for received negative

DDS_Duration

send_window_update_

acknowledgements and conditionally increases the send-

period

window size when none are received.

 

 

 

See Configuring the Send Window Size (Section 6.5.3.4)

 

 

 

6.5.3.1High and Low Watermarks

When the number of unacknowledged samples in the queue of a reliable DataWriter meets or exceeds high_watermark, the RELIABLE_WRITER_CACHE_CHANGED Status (DDS Extension) (Section 6.3.6.7) will be changed appropriately, a listener callback will be triggered, and the DataWriter will start heartbeating its matched DataReaders at fast_heartbeat_rate.

When the number of samples meets or falls below low_watermark, the RELIABLE_WRITER_CACHE_CHANGED Status (DDS Extension) (Section 6.3.6.7) will be changed appropriately, a listener callback will be triggered, and the heartbeat rate will return to the "normal" rate (heartbeat_rate).

Having both high and low watermarks (instead of one) helps prevent rapid flickering between the rates, which could happen if the number of samples hovers near the cut-off point.

Increasing the high and low watermarks will make the DataWriters less aggressive about seeking acknowledgments for sent data, decreasing the size of traffic spikes but slowing performance.

Decreasing the watermarks will make the DataWriters more aggressive, increasing both network utilization and performance.

If batching is used and the DataWriter is not a multi-channel DataWriter, high_watermark and low_watermark refer to batches, not samples. For multi-channel DataWriters, high_watermark and low_watermark always refer to samples (see Section 18.6.2 for additional details related to the multi-channel DataWriter reliability protocol).

6.5.3.2Normal, Fast, and Late-Joiner Heartbeat Periods

The normal heartbeat_period is used until the number of samples in the reliable DataWriter’s queue meets or exceeds high_watermark; then fast_heartbeat_period is used. Once the number of samples meets or drops below low_watermark, heartbeat_period is used again.

fast_heartbeat_period must be <= heartbeat_period

Increasing fast_heartbeat_period increases the speed of discovery, but results in a larger surge of traffic when the DataWriter is waiting for acknowledgments.

Decreasing heartbeat_period decreases the steady state traffic on the wire, but may increase latency by decreasing the speed of repairs for lost packets when the writer does not have very many outstanding unacknowledged samples.

Having two periodic heartbeat rates, and switching between them based on watermarks:

Ensures that all DataReaders receive all their data as quickly as possible (the sooner they receive a heartbeat, the sooner they can send a NACK, and the sooner the DataWriter can send repair samples);

6-84

Helps prevent the DataWriter from overflowing its resource limits (as its queue starts the fill, the DataWriter sends heartbeats faster, prompting the DataReaders to acknowledge sooner, allowing the DataWriter to purge these acknowledged samples from its queue);

Tunes the amount of network traffic. (Heartbeats and NACKs use up network bandwidth like any other traffic; decreasing the heartbeat rates, or increasing the threshold before the fast rate starts, can smooth network traffic—at the expense of discovery performance).

The late_joiner_heartbeat_period is used when a reliable DataReader joins after a reliable DataWriter (with non-volatile Durability) has begun publishing samples. Once the late-joining DataReader has received all cached samples, it will be serviced at the same rate as other reliable

DataReaders.

late_joiner_heartbeat_period must be <= heartbeat_period

6.5.3.3Disabling Positive Acknowledgements

When strict reliable communication is not required, you can configure Connext so that it does not send positive acknowledgements (ACKs). In this case, reliability is maintained solely based on negative acknowledgements (NACKs). The removal of ACK traffic may improve middleware performance. For example, when sending samples over multicast, ACK-storms that previously may have hindered DataWriters and consumed overhead network bandwidth are now precluded.

By default, DataWriters and DataReaders are configured with positive ACKS enabled. To disable ACKs, either:

Configure the DataWriter to disable positive ACKs for all matching DataReaders (by setting disable_positive_acks to TRUE in the DATA_WRITER_PROTOCOL QosPolicy (DDS Extension) (Section 6.5.3)).

Disable ACKs for individual DataReaders (by setting disable_positive_acks to TRUE in the DATA_READER_PROTOCOL QosPolicy (DDS Extension) (Section 7.6.1)).

If ACKs are disabled, instead of the DataWriter holding a sample in its send queue until all of its DataReaders have ACKed it, the DataWriter will hold a sample for a configurable duration. This “keep-duration" starts when a sample is written. When this time elapses, the sample is logically considered as acknowledged by its ACK-disabled readers.

The length of the "keep-duration" can be static or dynamic, depending on how rtps_reliable_writer.disable_positive_acks_enable_adaptive_sample_keep_duration is set.

When the length is static, the "keep-duration" is set to the minimum (rtps_reliable_writer.disable_positive_acks_min_sample_keep_duration).

When the length is dynamic, the "keep-duration" is dynamically adjusted between the minimum and maximum durations (rtps_reliable_writer.disable_positive_acks_min_sample_keep_duration and rtps_reliable_writer.disable_positive_acks_max_sample_keep_duration).

Dynamic adjustment maximizes throughput and reliability in response to current network conditions: when the network is congested, durations are increased to decrease the effective send rate and relieve the congestion; when the network is not congested, durations are decreased to increase the send rate and maximize throughput.

You should configure the minimum "keep-duration" to allow at least enough time for a possible NACK to be received and processed. When a DataWriter has both matching ACK-disabled and ACK-enabled DataReaders, it holds a sample in its queue until all ACK-enabled DataReaders have ACKed it and the "keep-duration" has elapsed.

See

also:

Disabling

Positive

Acknowledgements

(disable_postive_acks_min_sample_keep_duration) (Section 10.3.4.7).

 

6-85

6.5.3.4Configuring the Send Window Size

When a reliable DataWriter writes a sample, it keeps the sample in its queue until it has received acknowledgements from all of its subscribing DataReaders. The number of these outstanding samples is referred to as the DataWriter's "send window." Once the number of outstanding samples has reached the send window size, subsequent writes will block until an outstanding sample is acknowledged.

Configuration of the send window sets a minimum and maximum size, which may be unlimited. The min and max send windows can be the same. When set differently, the send window will dynamically change in response to detected network congestion, as signaled by received negative acknowledgements. When NACKs are received, the DataWriter responds to the slowed reader by decreasing the send window by the send_window_decrease_factor to throttle down its effective send rate. The send window will not be decreased to less than the min_send_window_size. After a period (send_window_update_period) during which no NACKs are received, indicating that the reader is catching up, the DataWriter will increase the send window size to increase the effective send rate by the percentage specified by send_window_increase_factor. The send window will increase to no greater than the max_send_window_size.

6.5.3.5Propagating Serialized Keys with Disposed-Instance Notifications

This section describes the interaction between these two fields:

serialize_key_with_dispose in DATA_WRITER_PROTOCOL QosPolicy (DDS Extension) (Section 6.5.3)

propagate_dispose_of_unregistered_instances in DATA_READER_PROTOCOL QosPolicy (DDS Extension) (Section 7.6.1)

RTI recommends setting serialize_key_with_dispose to TRUE if there are DataReaders with propagate_dispose_of_unregistered_instances also set to TRUE. However, it is permissible to set one to TRUE and the other to FALSE. The following examples will help you understand how these fields work.

See also: Disposing of Data (Section 6.3.14.2).

Example 1

1.DataWriter’s serialize_key_with_dispose = FALSE

2.DataReader’s propagate_dispose_of_unregistered_instances = TRUE

3.DataWriter calls dispose() before writing any samples

4.DataReader calls take() and receives a disposed-instance notification (without a key)

5.DataReader calls get_key_value(), which returns an error because there is no key associated with the disposed-instance notification

Example 2

1.DataWriter’s serialize_key_with_dispose = TRUE

2.DataReader’s propagate_dispose_of_unregistered_instances = FALSE

3.DataWriter calls dispose() before writing any samples

4.DataReader calls take(), which does not return any samples because none were written, and it does not receive any disposed-instance notifications because propagate_dispose_of_unregistered_instances = FALSE

Example 3

1.DataWriter’s serialize_key_with_dispose = TRUE

2.DataReader’s propagate_dispose_of_unregistered_instances = TRUE

6-86

3.DataWriter calls dispose() before writing any samples

4.DataReader calls take() and receives the disposed-instance notification

5.DataReader calls get_key_value() and receives the key for the disposed-instance notification

Example 4

1.DataWriter’s serialize_key_with_dispose = TRUE

2.DataReader’s propagate_dispose_of_unregistered_instances = TRUE

3.DataWriter calls write(), which writes a sample with a key

4.DataWriter calls dispose(), which writes a disposed-instance notification with a key

5.DataReader calls take() and receives a data sample and a disposed-instance notification; both have keys

6.DataReader calls get_key_value() with no errors

6.5.3.6Virtual Heartbeats

Virtual heartbeats announce the availability of samples with the Collaborative DataWriters feature described in Section 7.6.1, where multiple DataWriters publish samples from a common logical data-source (identified by a virtual GUID).

When PRESENTATION QosPolicy (Section 6.4.6) access_scope is set to TOPIC or INSTANCE on the Publisher, the virtual heartbeat contains information about the samples contained in the

DataWriter queue.

When presentation access_scope is set to GROUP on the Publisher, the virtual heartbeat contains information about the samples in the queues of all DataWriters that belong to the Publisher.

6.5.3.7Resending Over Multicast

Given DataReaders with multicast destinations, when a DataReader sends a NACK to request for samples to be resent, the DataWriter can either resend them over unicast or multicast. Though resending over multicast would save bandwidth and processing for the DataWriter, the potential problem is that there could be DataReaders of the multicast group that did not request for any resends, yet they would have to process, and drop, the resent samples.

Thus, to make each multicast resend more efficient, the multicast_resend_threshold is set as the minimum number of DataReaders of the same multicast group that the DataWriter must receive NACKs from within a single response-delay duration. This allows the DataWriter to coalesce near-simultaneous unicast resends into a multicast resend, and it allows a "vote" from DataReaders of a multicast group to exceed a threshold before resending over multicast.

The multicast_resend_threshold must be set to a positive value. Note that a threshold of 1 means that all resends will be sent over multicast. Also, note that a DataWriter with a zero NACK response-delay (i.e., both min_nack_response_delay and min_nackresponse_delay are zero) will resend over multicast only if the threshold is 1.

6.5.3.8Example

For information on how to use the fields in Table 6.36, see Controlling Heartbeats and Retries with DataWriterProtocol QosPolicy (Section 10.3.4).

The following describes a use case for when to change push_on_write to DDS_BOOLEAN_FALSE. Suppose you have a system in which the data packets being sent is very small. However, you want the data to be sent reliably, and the latency between the time that data is sent to the time that data is received is not an issue. However, the total network bandwidth between the DataWriter and DataReader applications is limited.

6-87

If the DataWriter sends a burst of data a a high rate, it is possible that it will overwhelm the limited bandwidth of the network. If you allocate enough space for the DataWriter to store the data burst being sent (see RESOURCE_LIMITS QosPolicy (Section 6.5.20)), then you can use the push_on_write parameter of the DATA_WRITER_PROTOCOL QosPolicy to delay sending the data until the reliable DataReader asks for it.

By setting push_on_write to DDS_BOOLEAN_FALSE, when write() is called on the

DataWriter, no data is actually sent. Instead data is stored in the DataWriter’s send queue. Periodically, Connext will be sending heartbeats informing the DataReader about the data that is available. So every heartbeat period, the DataReader will realize that the DataWriter has new data, and it will send an ACK/NACK, asking for them.

When DataWriter receives the ACK/NACK packet, it will put together a package of data, up to the size set by the parameter max_bytes_per_nack_response, to be sent to the DataReader. This method not only self-throttles the send rate, but also uses network bandwidth more efficiently by eliminating redundant packet headers when combining several small packets into one larger one.

6.5.3.9Properties

This QosPolicy cannot be modified after the DataWriter is created.

Since it is only for DataWriters, there are no compatibility restrictions for how it is set on the publishing and subscribing sides.

When setting the fields in this policy, the following rules apply. If any of these are false, Connext returns DDS_RETCODE_INCONSISTENT_POLICY:

min_nack_response_delay <= max_nack_response_delay

fast_heartbeat_period <= heartbeat_period

late_joiner_heartbeat_period <= heartbeat_period

low_watermark < high_watermark

If batching is disabled or the DataWriter is a multi-channel DataWriter:

heartbeats_per_max_samples <= writer_qos.resource_limits.max_samples

If batching is enabled and the DataWriter is not a multi-channel DataWriter:

heartbeats_per_max_samples <= writer_qos.resource_limits.max_batches

6.5.3.10Related QosPolicies

DATA_READER_PROTOCOL QosPolicy (DDS Extension) (Section 7.6.1)

HISTORY QosPolicy (Section 6.5.10)

RELIABILITY QosPolicy (Section 6.5.19)

6.5.3.11Applicable Entities

DataWriters (Section 6.3)

6-88

6.5.3.12System Resource Considerations

A high max_bytes_per_nack_response may increase the instantaneous network bandwidth required to send a single burst of traffic for resending dropped packets.

6.5.4DATA_WRITER_RESOURCE_LIMITS QosPolicy (DDS Extension)

This QosPolicy defines various settings that configure how DataWriters allocate and use physical memory for internal resources.

It includes the members in Table 6.37. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 6.37 DDS_DataWriterResourceLimitsQosPolicy

Type

Field Name

 

 

 

Description

 

 

 

 

 

 

 

 

DDS_Long

initial_concurrent_

Initial number of threads that are allowed to concurrently

blocking_threads

block on the write() call on the same DataWriter.

 

 

 

 

 

 

 

 

 

 

 

DDS_Long

max_concurrent_

Maximum

number

 

of threads

that

are allowed to

blocking_threads

concurrently block on write() call on the same DataWriter.

 

 

 

 

DDS_Long

max_remote_reader_

Maximum number of remote DataReaders for which this

filters

DataWriter will perform content-based filtering.

 

 

 

 

 

 

DDS_Long

initial_batches

Initial number of batches that a DataWriter will manage if

batching is enabled.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Maximum number of batches that a DataWriter will manage

 

 

if batching is enabled.

 

 

 

 

DDS_Long

max_batches

When batching is enabled, the maximum number of samples

that a DataWriter can store is limited by this value and

 

 

 

 

max_samples in RESOURCE_LIMITS QosPolicy (Section

 

 

6.5.20).

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

DDS_DataWriter

 

Sets the kinds of instances allowed to be replaced when a

ResourceLimits

 

instance_replacement

DataWriter reaches instance resource limits. (see Configuring

InstanceReplaceme

ntKind

 

DataWriter Instance Replacement (Section 6.5.20.2)

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

replace_empty_

Whether to

replace

empty instances

during

instance

DDS_Boolean

replacement.(see

Configuring

DataWriter

Instance

instances

 

Replacement (Section 6.5.20.2)

 

 

 

 

 

 

 

 

 

 

 

 

 

Whether to register automatically instances written with

DDS_Boolean

autoregister_instances

non-NIL handle that are not yet registered, which will

otherwise return an error. This can be especially useful if the

 

 

instance has been replaced.

 

 

 

 

 

 

DDS_Long

initial_virtual_writers

Initial number of virtual writers supported by a DataWriter.

 

 

 

 

 

Maximum number of virtual writers supported by a

 

 

DataWriter.

 

 

 

 

 

 

 

 

Sets the maximum number of unique virtual writers

DDS_Long

max_virtual_writers

supported by a DataWriter, where virtual writers are added

when samples are written with the virtual writer GUID.

 

 

 

 

This field is especially relevant in the configuration of

 

 

Persistence

Servicea

 

DataWriters,

since they

publish

 

 

information on behalf of multiple virtual writers.

 

 

 

 

DDS_Long

max_remote_readers

The maximum number of remote readers supported by a

DataWriter.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

DDS_Long

max_app_ack_remote

The maximum number of application-level acknowledging

_readers

remote readers supported by a DataWriter.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

6-89

a. Persistence Service is included with Connext Messaging. It saves data samples so they can be delivered to subscribing applications that join the system at a later time (see Chapter 26: Introduction to RTI Persistence Service).

DataWriters must allocate internal structures to handle the simultaneous blocking of threads trying to call write() on the same DataWriter, for the storage used to batch small samples, and for content-based filters specified by DataReaders.

Most of these internal structures start at an initial size and by default, will grow as needed by dynamically allocating additional memory. You may set fixed, maximum sizes for these internal structures if you want to bound the amount of memory that a DataWriter can use. By setting the initial size to the maximum size, you will prevent Connext from dynamically allocating any memory after the creation of the DataWriter.

When setting the fields in this policy, the following rule applies. If this is false, Connext returns

DDS_RETCODE_INCONSISTENT_POLICY:

max_concurrent_blocking_threads >= initial_concurrent_blocking_threads

The initial_concurrent_blocking_threads is the used to allocate necessary system resource initially. If necessary, it will be increased automatically up to the max_concurrent_blocking_threads limit.

Every user thread calling write() on a DataWriter may use a semaphore that will block the thread when the DataWriter’s send queue is full. Because user code may set a timeout, each thread must use a different semaphore. See the max_blocking_time parameter of the RELIABILITY QosPolicy (Section 6.5.19). This QoS is offered so that the user application can control the dynamic allocation of system resources by Connext.

If you do not mind if Connext dynamically allocates semaphores when needed, then you can set the max_concurrent_blocking_threads parameter to some large value like MAX_INT. However, if you know exactly how many threads will be calling write() on the same DataWriter, and you do not want Connext to allocate any system resources or memory after initialization, then you should set:

max_concurrent_blocking_threads = initial_concurrent_blocking_threads = NUM

(where NUM is the number of threads that could possibly block concurrently).

Each DataWriter can perform content-based data filtering for up to max_remote_reader_filters number of DataReaders. Setting the value to 0 will disable filtering by the DataWriter, which means that the DataReader will have to filter the data itself. For more information, see ContentFilteredTopics (Section 5.4).

6.5.4.1Example

If there are multiple threads that can write on the same DataWriter, and the write() operation may block (based on reliability_qos.max_blocking_time and HISTORY settings), you may want to set initial_concurrent_blocking_threads to the most likely number of threads that will block on the same DataWriter at the same time, and set max_concurrent_blocking_threads to the maximum number of threads that could potentially block in the worst case.

6.5.4.2Properties

This QosPolicy cannot be modified after the DataWriter is created.

Since it is only for DataWriters, there are no compatibility restrictions for how it is set on the publishing and subscribing sides.

6.5.4.3Related QosPolicies

BATCH QosPolicy (DDS Extension) (Section 6.5.2)

RELIABILITY QosPolicy (Section 6.5.19)

6-90

HISTORY QosPolicy (Section 6.5.10)

6.5.4.4Applicable Entities

DataWriters (Section 6.3)

6.5.4.5System Resource Considerations

Increasing the values in this QosPolicy will cause more memory usage and more system resource usage.

6.5.5DEADLINE QosPolicy

On a DataWriter, this QosPolicy states the maximum period in which the application expects to call write() on the DataWriter, thus publishing a new sample. The application may call write() faster than the rate set by this QosPolicy.

On a DataReader, this QosPolicy states the maximum period in which the application expects to receive new values for the Topic. The application may receive data faster than the rate set by this QosPolicy.

The DEADLINE QosPolicy has a single member, shown in Table 6.38. For the default and valid range, please refer to the API Reference HTML documentation.

Table 6.38 DDS_DeadlineQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

For DataWriters: maximum time between writing a new value of an

DDS_Duration_t

period

instance.

For DataReaders: maximum time between receiving new values for

 

 

 

 

an instance.

 

 

 

You can use this QosPolicy during system integration to ensure that applications have been coded to meet design specifications. You can also use it during run time to detect when systems are performing outside of design specifications. Receiving applications can take appropriate actions to prevent total system failure when data is not received in time. For topics on which data is not expected to be periodic, the deadline period should be set to an infinite value.

For keyed topics, the DEADLINE QoS applies on a per-instance basis. An application must call write() for each known instance of the Topic within the period specified by the DEADLINE on the DataWriter or receive a new value for each known instance within the period specified by the DEADLINE on the DataReader. For a DataWriter, the deadline period begins when the instance is first written or registered. For a DataReader, the deadline period begins when the first sample is received.

Connext will modify the DDS_OFFERED_DEADLINE_MISSED_STATUS and call the associated method in the DataWriterListener (see OFFERED_DEADLINE_MISSED Status (Section 6.3.6.4)) if the application fails to write() a value for an instance within the period set by the DEADLINE QosPolicy of the DataWriter.

Similarly, Connext will modify the DDS_REQUESTED_DEADLINE_-MISSED_STATUS and call the associated method in the DataReaderListener (see REQUESTED_DEADLINE_MISSED Status (Section 7.3.7.5)) if the application fails to receive a value for an instance within the period set by the DEADLINE QosPolicy of the DataReader.

For DataReaders, the DEADLINE QosPolicy and the TIME_BASED_FILTER QosPolicy (Section 7.6.4) may interact such that even though the DataWriter writes samples fast enough to fulfill its commitment to its own DEADLINE QosPolicy, the DataReader may see violations of its DEADLINE QosPolicy. This happens because Connext will drop any packets received within the minimum_separation set by the TIME_BASED_FILTER—packets that could satisfy the

DataReader’s deadline.

6-91

To avoid triggering the DataReader’s deadline even though the matched DataWriter is meeting its own deadline, set your QoS parameters to meet the following relationship:

reader deadline period >= reader minimum_separation + writer deadline period

Although you can set the DEADLINE QosPolicy on Topics, its value can only be used to initialize the DEADLINE QosPolicies of either a DataWriter or DataReader. It does not directly affect the operation of Connext, see Section 5.1.3.

6.5.5.1Example

Suppose you have a time-critical piece of data that should be updated at least once every second. You can set the DEADLINE period to 1 second on both the DataWriter and DataReader. If there is no update within that time, the DataWriter will get an on_offered_deadline_missed Listener callback, and the DataReader will get on_requested_deadline_missed, so that both sides can handle the error situation properly.

Note that in practice, there will be latency and jitter in the time between when data is send and when data is received. Thus even if the DataWriter is sending data at exactly 1 second intervals, the DataReader may not receive the data at exactly 1 second intervals. More likely, it will DataReader will receive the data at 1 second plus a small variable quantity of time. Thus you should accommodate this practical reality in choosing the DEADLINE period as well as the actual update period of the DataWriter or your application may receive false indications of failure.

The DEADLINE QosPolicy also interacts with the OWNERSHIP QosPolicy when OWNERSHIP is set to EXCLUSIVE. If a DataReader fails to receive data from the highest strength DataWriter within its requested DEADLINE, then the DataReaders can fail-over to lower strength DataWriters, see the OWNERSHIP QosPolicy (Section 6.5.15).

6.5.5.2Properties

This QosPolicy can be changed at any time.

The deadlines on the two sides must be compatible.

DataWriter’s DEADLINE period <= the DataReader’s DEADLINE period.

That is, the DataReader cannot expect to receive samples more often than the DataWriter commits to sending them.

If the DataReader and DataWriter have compatible deadlines, Connext monitors this “contract” and informs the application of any violations. If the deadlines are incompatible, both sides are informed and communication does not occur. The ON_OFFERED_INCOMPATIBLE_QOS and the ON_REQUESTED_INCOMPATIBLE_QOS statuses will be modified and the corresponding Listeners called for the DataWriter and DataReader respectively.

6.5.5.3Related QosPolicies

LIVELINESS QosPolicy (Section 6.5.13)

OWNERSHIP QosPolicy (Section 6.5.15)

TIME_BASED_FILTER QosPolicy (Section 7.6.4)

6.5.5.4Applicable Entities

Topics (Section 5.1)

DataWriters (Section 6.3)

DataReaders (Section 7.3)

6-92

6.5.5.5System Resource Considerations

A Connext-internal thread will wake up at least by the DEADLINE period to check to see if the deadline was missed. It may wake up faster if the last sample that was published or sent was close to the last time that the deadline was checked. Therefore a short period will use more CPU to wake and execute the thread checking the deadline.

6.5.6DESTINATION_ORDER QosPolicy

When multiple DataWriters send data for the same topic, the order in which data from different DataWriters are received by the applications of different DataReaders may be different. Thus different DataReaders may not receive the same "last" value when DataWriters stop sending data.

This policy controls how each subscriber resolves the final value of a data instance that is written by multiple DataWriters (which may be associated with different Publishers) running on different nodes.

This QosPolicy can be used to create systems that have the property of "eventual consistency." Thus intermediate states across multiple applications may be inconsistent, but when DataWriters stop sending changes to the same topic, all applications will end up having the same state.

Each data sample includes two timestamps: a source timestamp and a destination timestamp. The source timestamp is recorded by the DataWriter application when the data was written. The destination timestamp is recorded by the DataReader application when the data was received.

This QoS includes the member in Table 6.39.

Table 6.39 DDS_DestinationOrderQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

Can be either:

DDS_Destination-

kind

• DDS_BY_RECEPTION_TIMESTAMP_

DESTINATIONORDER_QOS

OrderQosPolicyKind

 

 

• DDS_BY_SOURCE_TIMESTAMP_

 

 

DESTINATIONORDER_QOS

 

 

 

 

 

Allowed tolerance between source timestamps of

 

 

consecutive samples.

DDS_Duration_t

source_timestamp_tolerance

Only applies when kind (above) is

 

 

DDS_BY_SOURCE_TIMESTAMP_

 

 

DESTINATIONORDER_QOS.

 

 

 

Each DataReader can set this QoS to:

DDS_BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS

Assuming the OWNERSHIP_STRENGTH allows it, the latest received value for the instance should be the one whose value is kept. Data will be delivered by a DataReader in the order in which it was received (which may lead to inconsistent final values).

DDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS

Assuming the OWNERSHIP_STRENGTH allows it, within each instance, the source_timestamp shall be used to determine the most recent information. This is the only setting that, in the case of concurrent same-strength DataWriters updating the same instance, ensures all subscribers will end up with the same final value for the instance.

Data will be delivered by a DataReader in the order in which it was sent. If data arrives on the network with a source timestamp earlier than the source timestamp of the last data delivered, the new data will be dropped. This ordering therefore works best when system clocks are relatively synchronized among writing machines.

6-93

Not all data sent by multiple DataWriters may be delivered to a DataReader and not all DataReaders will see the same data sent by DataWriters. However, all DataReaders will see the same "final" data when DataWriters "stop" sending data.

For a DataWriter with kind

DDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS:

When writing a sample, its timestamp must not be less than the timestamp of the pre- viously written sample. However, if it is less than the timestamp of the previously written sample but the difference is less than this tolerance, the sample will use the previously written sample's timestamp as its timestamp. Otherwise, if the difference is greater than this tolerance, the write will fail.

See also: Special instructions for deleting DataWriters if you are using the ‘Time- stamp’ APIs and BY_SOURCE_TIMESTAMP Destination Order: on page 6-20.

A DataReader with kind

DDS_BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS will accept a sample only if the difference between the sample’s source timestamp and the reception time- stamp is no greater than source_timestamp_tolerance. Otherwise, the sample is rejected.

Although you can set the DESTINATION_ORDER QosPolicy on Topics, its value can only be used to initialize the DESTINATION_ORDER QosPolicies of either a DataWriter or DataReader. It does not directly affect the operation of Connext, see Section 5.1.3.

6.5.6.1Properties

This QosPolicy cannot be modified after the Entity is enabled.

This QoS must be set compatibly between the DataWriter and the DataReader. The compatible combinations are shown in Table 6.40.

Table 6.40 Valid Reader/Writer Combinations of DestinationOrder

Destination Order

 

DataReader requests:

 

 

 

 

BY_SOURCE

BY_RECEPTION

 

 

 

 

 

 

 

 

 

 

 

 

 

DataWriter offers:

BY_SOURCE

 

 

 

 

 

BY_RECEPTION

 

incompatible

 

 

 

 

 

 

 

If this QosPolicy is set incompatibly, the ON_OFFERED_INCOMPATIBLE_QOS and ON_REQUESTED_INCOMPATIBLE_QOS statuses will be modified and the corresponding

Listeners called for the DataWriter and DataReader respectively.

6.5.6.2Related QosPolicies

OWNERSHIP QosPolicy (Section 6.5.15)

HISTORY QosPolicy (Section 6.5.10)

6.5.6.3Applicable Entities

Topics (Section 5.1)

DataWriters (Section 6.3)

DataReaders (Section 7.3)

6-94

6.5.6.4System Resource Considerations

The use of this policy does not significantly impact the use of resources.

6.5.7DURABILITY QosPolicy

Because the publish-subscribe paradigm is connectionless, applications can create publications and subscriptions in any way they choose. As soon as a matching pair of DataWriters and DataReaders exist, then data published by the DataWriter will be delivered to the DataReader. However, a DataWriter may publish data before a DataReader has been created. For example, before you subscribe to a magazine, there have been past issues that were published.

The DURABILITY QosPolicy controls whether or not, and how, published samples are stored by the DataWriter application for DataReaders that are found after the samples were initially written. DataReaders use this QoS to request samples that were published before they were created. The analogy is for a new subscriber to a magazine to ask for issues that were published in the past. These are known as ‘historical’ data-samples. (Reliable DataReaders may wait for these historical samples, see Section 7.3.5.)

This QosPolicy can be used to help ensure that DataReaders get all data that was sent by DataWriters, regardless of when it was sent. This QosPolicy can increase system tolerance to failure conditions.

Exactly how many samples are stored by the DataWriter or requested by the DataReader is controlled using the HISTORY QosPolicy (Section 6.5.10).

For more information, please see Chapter 12: Mechanisms for Achieving Information Durability and Persistence.

The possible settings for this QoS are:

DDS_VOLATILE_DURABILITY_QOS Connext is not required to send and will not deliver any data samples to DataReaders that are discovered after the samples were initially published.

DDS_TRANSIENT_LOCAL_DURABILITY_QOS Connext will store and send previously published samples for delivery to newly discovered DataReaders as long as the DataWriter entity still exists. For this setting to be effective, you must also set the

RELIABILITY QosPolicy (Section 6.5.19) kind to Reliable (not Best Effort). The HISTORY QosPolicy (Section 6.5.10) of the DataReaders/DataWriters used by Persistence Service1 determines exactly how many samples are saved or delivered by Persistence Service.

DDS_TRANSIENT_DURABILITY_QOS Connext will store previously published samples in memory using Persistence Service, which will send the stored data to newly discovered DataReaders. The HISTORY QosPolicy (Section 6.5.10) of the DataReaders/DataWriters used by Persistence Service determines exactly how many samples are saved or delivered

Persistence Service.

DDS_PERSISTENT_DURABILITY_QOS Connext will store previously published samples in permanent storage, like a disk, using Persistence Service, which will send the stored data to newly discovered DataReaders. The HISTORY QosPolicy (Section 6.5.10) determines exactly how many samples are saved or delivered.

This QosPolicy includes the members in Table 6.41. For default settings, please refer to the API Reference HTML documentation.

With this QoS policy alone, there is no way to specify or characterize the intended consumers of the information. With TRANSIENT_LOCAL, TRANSIENT, or PERSISTENT durability a DataWriter can be configured to keep samples around for late-joiners. However, there is no way to know when the information has been consumed by all the intended recipients.

1. Persistence Service is included with Connext Messaging. It saves data samples so they can be delivered to subscribing applications that join the system at a later time (see Chapter 26: Introduction to RTI Persistence Service).

6-95

Table 6.41 DDS_DurabilityQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

DDS_VOLATILE_DURABILITY_QOS:

 

 

Do not save or deliver old samples.

 

 

DDS_TRANSIENT_LOCAL_DURABILITY_QOS:

DDS_Durability

kind

Save and deliver old samples if the DataWriter still exists.

QosPolicyKind

DDS_TRANSIENT_DURABILITY_QOS:

 

 

 

Save and deliver old samples using a memory-based service.

 

 

DDS_PERSISTENCE_DURABILITY_QOS:

 

 

Save and deliver old samples using disk-based service.

 

 

 

 

 

Whether or not a TRANSIENT or PERSISTENT DataReader should

 

 

receive samples directly from a TRANSIENT or PERSISTENT

 

 

DataWriter.

 

 

When TRUE, a TRANSIENT or PERSISTENT DataReader will receive

 

 

samples directly from the original DataWriter. The DataReader may

 

direct_

also receive samples from Persistence Servicea but the duplicates will

DDS_Boolean

be filtered by the middleware.

communication

 

When FALSE, a TRANSIENT or PERSISTENT DataReader will

 

 

receive samples only from the DataWriter created by Persistence

 

 

Service. This ‘relay communication’ pattern provides a way to

 

 

guarantee eventual consistency.

 

 

See RTI Persistence Service (Section 12.5.1).

 

 

This field only applies to DataReaders.

 

 

 

a. Persistence Service is included with Connext Messaging. See Chapter 26: Introduction to RTI Persistence Service.

Information durability can be combined with required subscriptions in order to guarantee that samples are delivered to a set of required subscriptions. For additional details on required subscriptions see Section 6.3.13 and Section 6.5.1.

6.5.7.1Example

Suppose you have a DataWriter that sends data sporadically and its DURABILITY kind is set to VOLATILE. If a new DataReader joins the system, it won’t see any data until the next time that write() is called on the DataWriter. If you want the DataReader to receive any data that is valid, old or new, both sides should set their DURABILITY kind to TRANSIENT_LOCAL. This will ensure that the DataReader gets some of the previous samples immediately after it is enabled.

6.5.7.2Properties

This QosPolicy cannot be modified after the Entity has been created.

The DataWriter and DataReader must use compatible settings for this QosPolicy. To be compatible, the DataWriter and DataReader must use one of the valid combinations shown in Table 6.42.

If this QosPolicy is found to be incompatible, the ON_OFFERED_INCOMPATIBLE_QOS and ON_REQUESTED_INCOMPATIBLE_QOS statuses will be modified and the corresponding

Listeners called for the DataWriter and DataReader respectively.

6.5.7.3Related QosPolicies

HISTORY QosPolicy (Section 6.5.10)

RELIABILITY QosPolicy (Section 6.5.19)

DURABILITY SERVICE QosPolicy (Section 6.5.8)

AVAILABILITY QosPolicy (DDS Extension) (Section 6.5.1)

6-96

Table 6.42 Valid Combinations of Durability ‘kind’

 

 

 

DataReader requests:

 

 

 

 

 

 

 

 

 

VOLATILE

TRANSIENT

TRANSIENT

PERSISTENT

 

 

 

_LOCAL

 

 

 

 

 

 

 

 

 

VOLATILE

incompatible

incompatible

incompatible

 

 

 

 

 

 

DataWriter

TRANSIENT_

incompatible

incompatible

LOCAL

 

 

 

 

offers:

 

 

 

 

 

TRANSIENT

incompatible

 

 

 

 

 

 

 

 

PERSISTENT

 

 

 

 

 

 

6.5.7.4Applicable Entities

Topics (Section 5.1)

DataWriters (Section 6.3)

DataReaders (Section 7.3)

6.5.7.5System Resource Considerations

Using this policy with a setting other than VOLATILE will cause Connext to use CPU and network bandwidth to send old samples to matching, newly discovered DataReaders. The actual amount of resources depends on the total size of data that needs to be sent.

The maximum number of samples that will be kept on the DataWriter’s queue for late-joiners and/or required subscriptions is determined by max_samples in RESOURCE_LIMITS Qos Policy.

System Resource Considerations With Required Subscriptions”

By default, when TRANSIENT_LOCAL durability is used in combination with required subscriptions, a DataWriter configured with KEEP_ALL in the HISTORY QosPolicy (Section 6.5.10) will keep the samples in its cache until they are acknowledged by all the required subscriptions. After the samples are acknowledged by the required subscriptions they will be marked as reclaimable, but they will not be purged from the DataWriter’s queue until the DataWriter needs these resources for new samples. This may lead to a non efficient resource utilization, specially when max_samples is high or even UNLIMITED.

The DataWriter’s behavior can be changed to purge samples after they have been acknowledged by all the active/matching DataReaders and all the required subscriptions configured on the DataWriter. To do so, set the dds.data_writer.history.purge_samples_after_acknowledgment property to 1 (see PROPERTY QosPolicy (DDS Extension) (Section 6.5.17)).

6.5.8DURABILITY SERVICE QosPolicy

This QosPolicy is only used if the DURABILITY QosPolicy (Section 6.5.7) is PERSISTENT or TRANSIENT and you are using Persistence Service, which is included with Connext Messaging. Persistence Service is used to store and possibly forward the data sent by the DataWriter to DataReaders who are created after the data was initially sent.

This QosPolicy configures certain parameters of Persistence Service when it operates on the behalf of the DataWriter, such as how much data to store. Specifically, this QosPolicy configures the HISTORY and RESOURCE_LIMITS used by the fictitious DataReader and DataWriter used by

Persistence Service.

Note however, that Persistence Service itself may be configured to ignore these values and instead use values from its own configuration file.

6-97

For more information, please see:

Chapter 12: Mechanisms for Achieving Information Durability and Persistence

Chapter 26: Introduction to RTI Persistence Service

Chapter 27: Configuring Persistence Service

This QosPolicy includes the members in Table 6.43. For default values, please refer to the API Reference HTML documentation.

Table 6.43 DDS_DurabilityServiceQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

DDS_Duration_t

service_cleanup_delay

How long to keep all information regarding

an instance.

 

 

 

 

 

DDS_HistoryQosPolicyKind

history_kind

Settings to use for the HISTORY QosPolicy

 

 

(Section 6.5.10) when recouping durable

DDS_Long

history_depth

data.

 

 

 

 

 

 

max_samples

Settings to use for the RESOURCE_LIMITS

 

 

DDS_Long

max_instances

QosPolicy (Section 6.5.20) when feeding

 

 

data to a late joiner.

 

max_samples_per_instance

 

 

 

The service_cleanup_delay in this QosPolicy controls when Persistence Service may remove all information regarding a data-instances. Information on a data-instance is maintained until all of the following conditions are met:

1.The instance has been explicitly disposed (instance_state = NOT_ALIVE_DISPOSED).

2.While in the NOT_ALIVE_DISPOSED state, Connext detects that there are no more 'live' DataWriters writing the instance. That is, all existing writers either unregister the instance (call unregister) or lose their liveliness.

3.A time interval longer that DurabilityService QosPolicy’s service_cleanup_delay has elapsed since the time that Connext detected that the previous two conditions were met.

The service_cleanup_delay field is useful in the situation where your application disposes an instance and it crashes before it has a chance to complete additional tasks related to the disposition. Upon restart, your application may ask for initial data to regain its state and the delay introduced by service_cleanup_delay will allow your restarted application to receive the information about the disposed instance and complete any interrupted tasks.

Although you can set the DURABILITY_SERVICE QosPolicy on a Topic, this is only useful as a means to initialize the DURABILITY_SERVICE QosPolicy of a DataWriter. A Topic’s DURABILITY_SERVICE setting does not directly affect the operation of Connext, see Section 5.1.3.

6.5.8.1Properties

This QosPolicy cannot be modified after the Entity has been enabled.

It does not apply to DataReaders, so there is no requirement for setting it compatibly on the sending and receiving sides.

6.5.8.2Related QosPolicies

DURABILITY QosPolicy (Section 6.5.7)

HISTORY QosPolicy (Section 6.5.10)

RESOURCE_LIMITS QosPolicy (Section 6.5.20)

6-98

6.5.8.3Applicable Entities

Topics (Section 5.1)

DataWriters (Section 6.3)

6.5.8.4System Resource Considerations

Since this QosPolicy configures the HISTORY and RESOURCE_LIMITS used by the fictitious DataReader and DataWriter used by Persistence Service, it does have some impact on resource usage.

6.5.9ENTITY_NAME QosPolicy (DDS Extension)

The ENTITY_NAME QosPolicy assigns a name and role name to a DomainParticipant,

DataReader, or DataWriter.

How the name is used is strictly application-dependent.

It is useful to attach names that are meaningful to the user. These names are propagated during discovery so that applications can use these names to identify, in a user-context, the entities that it discovers. Also, Connext Tools such as RTI Analyzer will print these names for entities that it finds so that users can easily determine exactly which application they are browsing with RTI Analyzer.

The role_name identifies the role of the entity. It is used by the Collaborative DataWriter feature (see Availability QoS Policy and Collaborative DataWriters (Section 6.5.1.1)). With Durable Subscriptions, role_name is used to specify to which Durable Subscription the DataReader belongs. (see Availability QoS Policy and Required Subscriptions (Section 6.5.1.2).

This QosPolicy contains the members listed in Table 6.44.

Table 6.44 DDS_EntityNameQoSPolicy

Type

Field Name

Description

 

 

 

 

 

 

char *

name

A null terminated string, up to 255 characters in length.

 

 

 

 

 

A null terminated string, up to 255 characters in length.

 

 

For Collaborative DataWriters, this name is used to specify to which

 

 

endpoint group the DataWriter belongs. See. Availability QoS Policy

char *

role_name

and Collaborative DataWriters (Section 6.5.1.1).

 

 

For Required and Durable Subscriptions this name is used to specify

 

 

to which Subscription the DataReader belongs. See Required

 

 

Subscriptions (Section 6.3.13).

 

 

 

These names will appear in the built-in topic for the entity (see the tables in Built-in DataReaders (Section 16.2)).

Prior to get_qos(), if the name and/or role_name field in assumes the memory to be valid and big enough and may name and/or role_name to NULL before calling get_qos() memory for name.

this QosPolicy is not null, Connext write to it. If that is not desired, set and Connext will allocate adequate

When you call the destructor of entity’s QoS structure (DomainParticipantQos, DataReaderQos, or DataWriterQos) (in C++, C++/CLI, and C#) or <entity>Qos_finalize() (in C), Connext will attempt to free the memory used for name and role_name if it is not NULL. If this behavior is not desired, set name and/or role_name to NULL before you call the destructor of entity’s QoS structure or DomainParticipantQos_finalize().

6-99

6.5.9.1Properties

This QosPolicy cannot be modified after the entity is enabled.

6.5.9.2Related QosPolicies

None

6.5.9.3Applicable Entities

DataReaders (Section 7.3)

DataWriters (Section 6.3)

DomainParticipants (Section 8.3)

6.5.9.4System Resource Considerations

If the value of name in this QosPolicy is not NULL, some memory will be consumed in storing the information in the database, but should not significantly impact the use of resource.

6.5.10HISTORY QosPolicy

This QosPolicy configures the number of samples that Connext will store locally for DataWriters and DataReaders. For keyed Topics, this QosPolicy applies on a per instance basis, so that Connext will attempt to store the configured value of samples for every instance (see Samples, Instances, and Keys (Section 2.2.2) for a discussion of keys and instances).

It includes the members seen in Table 6.45. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 6.45 DDS_HistoryQosPolicy

Type

Field

Description

 

 

Name

 

 

 

 

 

 

 

 

 

 

 

 

DDS_HistoryQos-

 

DDS_KEEP_LAST_HISTORY_QOS: keep the last depth number of

kind

samples per instance.

 

 

PolicyKind

 

DDS_KEEP_ALL_HISTORY_QOS: keep all samples.a

 

 

 

 

 

 

 

 

If kind = DDS_KEEP_LAST_HISTORY_QOS, this is how many samples to

DDS_Long

depth

keep per instance.b

 

 

 

 

if kind = DDS_KEEP_ALL_HISTORY_QOS, this value is ignored.

 

 

 

 

 

 

Specifies how a DataWriter should handle previously written samples for a

 

 

new DataReader.

 

 

 

 

When a new DataReader matches a DataWriter, the DataWriter can be

 

 

configured to perform content-based filtering on previously written

 

 

samples stored in the DataWriter queue for the new DataReader.

 

 

 

May be:

 

 

DDS_RefilterQos-

 

DDS_NONE_REFILTER_QOS Do not

filter

existing

refilter

samples for a new DataReader. The DataReader will do the

PolicyKind

 

filtering.

 

 

 

 

 

 

 

 

DDS_ALL_REFILTER_QOS Filter all existing samples for a

 

 

newly matched DataReader.

 

 

 

 

DDS_ON_DEMAND_REFILTER_QOS

Filter

existing

 

 

samples only when they are requested by the DataReader.

 

 

(An extension to the DDS standard.)

 

 

 

 

 

 

 

a. Connext will store up to the value of the max_samples_per_instance parameter of the RESOURCE_LIMITS QosPol- icy (Section 6.5.20).

6-100

b. depth must be <= max_samples_per_instance parameter of the RESOURCE_LIMITS QosPolicy (Section 6.5.20)

The kind determines whether or not to save a configured number of samples or all samples. It can be set to either of the following:

DDS_KEEP_LAST_HISTORY_QOS Connext attempts to keep the latest values of the data- instance and discard the oldest ones when the limit as set by the depth parameter is reached; new data will overwrite the oldest data in the queue. Thus the queue acts like a circular buffer of length depth.

For a DataWriter: Connext attempts to keep the most recent depth samples of each instance (identified by a unique key) managed by the DataWriter.

For a DataReader: Connext attempts to keep the most recent depth samples received for each instance (identified by a unique key) until the application takes them via the DataReader's take() operation. See Section 7.4.3 for a discussion of the difference between read() and take().

DDS_KEEP_ALL_HISTORY_QOS Connext attempts to keep all of the samples of a Topic.

For a DataWriter: Connext attempts to keep all samples published by the DataWriter.

For a DataReader: Connext attempts to keep all samples received by the DataReader for a Topic (both keyed and non-keyed) until the application takes them via the DataReader's take() operation. See Section 7.4.3 for a discussion of the difference between read() and take().

The value of the depth parameter is ignored.

The above descriptions say “attempts to keep” because the actual number of samples kept is subject to the limitations imposed by the RESOURCE_LIMITS QosPolicy (Section 6.5.20). All of the samples of all instances of a Topic share a single physical queue that is allocated for a DataWriter or DataReader. The size of this queue is configured by the RESOURCE_LIMITS QosPolicy. If there are many difference instances for a Topic, it is possible that the physical queue may run out of space before the number of samples reaches the depth for all instances.

In the KEEP_ALL case, Connext can only keep as many samples for a Topic (independent of instances) as the size of the allocated queue. Connext may or may not allocate more memory when the queue is filled, depending on the settings in the RESOURCE_LIMITS QoSPolicy of the

DataWriter or DataReader.

This QosPolicy interacts with the RELIABILITY QosPolicy (Section 6.5.19) by controlling whether or not Connext guarantees that ALL of the data sent is received or if only the last N data values sent are guaranteed to be received (a reduced level of reliability using the KEEP_LAST setting). However, the physical sizes of the send and receive queues are not controlled by the History QosPolicy. The memory allocation for the queues is controlled by the RESOURCE_LIMITS QosPolicy (Section 6.5.20). Also, the amount of data that is sent to new DataReaders who have configured their DURABILITY QosPolicy (Section 6.5.7) to receive previously published data is controlled by the History QosPolicy.

What happens when the physical queue is filled depends both on the setting for the HISTORY QosPolicy as well as the RELIABILITY QosPolicy.

DDS_KEEP_LAST_HISTORY_QOS

If RELIABILITY is BEST_EFFORT: When the number of samples for an instance in the queue reaches the value of depth, a new sample for the instance will replace the oldest sample for the instance in the queue.

If RELIABILITY is RELIABLE: When the number of samples for an instance in the queue reaches the value of depth, a new sample for the instance will replace the oldest sample for the instance in the queue—even if the sample being overwritten has not been fully acknowledged as being received by all reliable DataReaders. This implies that the discarded sample may be lost by some reliable DataReaders. Thus, when using the KEEP_LAST setting, strict reliability is not guaranteed. See Chapter 10: Reliable Communications for a complete discussion on Connext’s reliable protocol.

6-101

DDS_KEEP_ALL_HISTORY_QOS

If RELIABILITY is BEST_EFFORT: If the number of samples for an instance in the queue reaches the value of the RESOURCE_LIMITS QosPolicy (Section 6.5.20)’s max_samples_per_instance field, a new sample for the instance will replace the oldest sample for the instance in the queue (regardless of instance).

If RELIABILITY is RELIABLE: When the number of samples for an instance in the queue reaches the value of the RESOURCE_LIMITS QosPolicy (Section 6.5.20)’s max_samples_per_instance field, then:

a)for a DataWriter—a new sample for the instance will replace the oldest sample for the instance in the sending queue—only if the sample being overwritten has been fully acknowledged as being received by all reliable DataReaders. If the oldest sample for the instance has not been fully acknowledged, the write() operation trying to enter a new sample for the instance into the sending queue will block (for the max_blocking_time specified in the RELIABLE QosPolicy).

b)for a DataReader—a new sample received by the DataReader will be discarded. Because the DataReader will not acknowledge the discarded sample, the DataWriter is forced to resend the sample. Hopefully, the next time the sample is received, there is space for the instance in the DataReader’s queue to store (and accept, thus acknowl- edge) the sample. A sample will remain in the DataReader’s queue for one of two rea- sons. The more common reason is that the user application has not removed the sample using the DataReader’s take() method. Another reason is that the sample has been received out of order and is not available to be taken or read by the user applica- tion until all older samples have been received.

Although you can set the HISTORY QosPolicy on Topics, its value can only be used to initialize the HISTORY QosPolicies of either a DataWriter or DataReader. It does not directly affect the operation of Connext, see Section 5.1.3.

6.5.10.1Example

To achieve strict reliability, you must (1) set the DataWriter’s and DataReader’s HISTORY QosPolicy to KEEP_ALL, and (2) set the DataWriter’s and DataReader’s RELIABILITY QosPolicy to RELIABLE.

See Chapter 10 for a complete discussion on Connext’s reliable protocol. See Controlling Queue Depth with the History QosPolicy (Section 10.3.3).

6.5.10.2Properties

This QosPolicy cannot be modified after the Entity has been enabled.

There is no requirement that the publishing and subscribing sides use compatible values.

6.5.10.3Related QosPolicies

BATCH QosPolicy (DDS Extension) (Section 6.5.2) Do not configure the DataReader’s depth to be shallower than the DataWriter's maximum batch size (batch_max_data_size). Because batches are acknowledged as a group, a DataReader that cannot process an entire batch will lose the remaining samples in it.

RELIABILITY QosPolicy (Section 6.5.19)

RESOURCE_LIMITS QosPolicy (Section 6.5.20)

6.5.10.4Applicable Entities

Topics (Section 5.1)

DataWriters (Section 6.3)

DataReaders (Section 7.3)

6-102

6.5.10.5System Resource Considerations

While this QosPolicy does not directly affect the system resources used by Connext, the RESOURCE_LIMITS QosPolicy (Section 6.5.20) that must be used in conjunction with the HISTORY QosPolicy (Section 6.5.10) will affect the amount of memory that Connext will allocate for a DataWriter or DataReader.

6.5.11LATENCYBUDGET QoS Policy

This QosPolicy can be used by a DDS implementation to change how it processes and sends data that has low latency requirements. The DDS specification does not mandate whether or how this parameter is used. Connext uses it to prioritize the sending of asynchronously published data; see ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension) (Section 6.4.1).

This QosPolicy also applies to Topics. The Topic’s setting for the policy is ignored unless you explicitly make the DataWriter use it.

It contains the single member listed in Table 6.46.

Table 6.46 DDS_LatencyBudgetQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

Provides a hint as to the maximum acceptable delay from the time

DDS_Duration_t

duration

the data is written to the time it is received by the subscribing

 

 

applications.

 

 

 

6.5.11.1Applicable Entities

Topics (Section 5.1)

DataWriters (Section 6.3)

DataReaders (Section 7.3)

6.5.12LIFESPAN QoS Policy

The purpose of this QoS is to avoid delivering stale data to the application. Each data sample written by a DataWriter has an associated expiration time, beyond which the data should not be delivered to any application. Once the sample expires, the data will be removed from the DataReader caches, as well as from the transient and persistent information caches.

The middleware attaches timestamps to all data sent and received. The expiration time of each sample is computed by adding the duration specified by this QoS to the destination timestamp. To avoid inconsistencies, if you have multiple DataWriters of the same instance, they should all use the same value for this QoS.

When you specify a finite Lifespan for your data, Connext will compare the current time with those timestamps and drop data when your specified Lifespan expires.

The Lifespan QosPolicy can be used to control how much data is stored by Connext. Even if it is configured to store "all" of the data sent or received for a topic (see the HISTORY QosPolicy (Section 6.5.10)), the total amount of data it stores may be limited by the Lifespan QosPolicy.

You may also use the Lifespan QosPolicy to ensure that applications do not receive or act on data, commands or messages that are too old and have "expired.”

It includes the single member listed in Table 6.47. For default and valid range, please refer to the API Reference HTML documentation.

Although you can set the LIFESPAN QosPolicy on Topics, its value can only be used to initialize the LIFESPAN QosPolicies of DataWriters. The Topic’s setting for this QosPolicy does not directly affect the operation of Connext, see Setting Topic QosPolicies (Section 5.1.3).

6-103

Table 6.47 DDS_LifespanQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

DDS_Duration_t

duration

Maximum duration for the data's validity.

 

 

 

6.5.12.1Properties

This QoS policy can be modified after the entity is enabled.

It does not apply to DataReaders, so there is no requirement that the publishing and subscribing sides use compatible values.

6.5.12.2Related QoS Policies

BATCH QosPolicy (DDS Extension) (Section 6.5.2) Be careful when configuring a DataWriter with a Lifespan duration shorter than the batch flush period (batch_flush_delay). If the batch does not fill up before the flush period elapses, the short duration will cause the samples to be lost without being sent.

DURABILITY QosPolicy (Section 6.5.7)

6.5.12.3Applicable Entities

Topics (Section 5.1)

DataWriters (Section 6.3)

6.5.12.4System Resource Considerations

The use of this policy does not significantly impact the use of resources.

6.5.13LIVELINESS QosPolicy

The LIVELINESS QosPolicy specifies how Connext determines whether a DataWriter is “alive.” A DataWriter’s liveliness is used in combination with the OWNERSHIP QosPolicy (Section 6.5.15) to maintain ownership of an instance (note that the DEADLINE QosPolicy (Section 6.5.5) is also used to change ownership when a DataWriter is still alive). That is, for a DataWriter to own an instance, the DataWriter must still be alive as well as honoring its DEADLINE contract.

It includes the members in Table 6.48. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 6.48 DDS_LivelinessQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

DDS_AUTOMATIC_LIVELINESS_QOS:

 

 

Connext will automatically assert liveliness for the DataWriter at least as

 

 

often as the lease_duration.

DDS_Liveliness

 

DDS_MANUAL_BY_PARTICIPANT_LIVELINESS_QOS:

kind

The DataWriter is assumed to be alive if any Entity within the same

QosPolicyKind

 

DomainParticipant has asserted its liveliness.

 

 

 

 

DDS_MANUAL_BY_TOPIC_LIVELINESS_QOS:

 

 

Your application must explicitly assert the liveliness of the DataWriter

 

 

within the lease_duration.

 

 

 

 

 

The timeout by which liveliness must be asserted for the DataWriter or

 

 

the DataWriter will be considered “inactive or not alive.

DDS_Duration_t

lease_duration

Additionally, for DataReaders, the lease_duration also specifies the

 

 

maximum period at which Connext will check to see if the matching

 

 

DataWriter is still alive.

 

 

 

6-104

Setting a DataWriter’s kind of LIVELINESS specifies the mechanism that will be used to assert liveliness for the DataWriter. The DataWriter’s lease_duration then specifies the maximum period at which packets that indicate that the DataWriter is still alive are sent to matching

DataReaders.

The various mechanisms are:

DDS_AUTOMATIC_LIVELINESS_QOS — The DomainParticipant is responsible for automatically sending packets to indicate that the DataWriter is alive; this will be done at least as often as required by the lease_duration. This setting is appropriate when the primary failure mode is that the publishing application itself dies. It does not cover the case in which the application is still alive but in an erroneous state–allowing the DomainParticipant to continue to assert liveliness for the DataWriter but preventing threads from calling write() on the DataWriter.

As long as the internal threads spawned by Connext for a DomainParticipant are running, then the liveliness of the DataWriter will be asserted regardless of the state of the rest of the application.

This setting is certainly the most convenient, if the least accurate, method of asserting liveliness for a DataWriter.

DDS_MANUAL_BY_PARTICIPANT_LIVELINESS_QOS Connext will assume that as long as the user application has asserted the liveliness of at least one DataWriter belonging to the same DomainParticipant or the liveliness of the DomainParticipant itself, then this DataWriter is also alive.

This setting allows the user code to control the assertion of liveliness for an entire group of DataWriters with a single operation on any of the DataWriters or their DomainParticipant. Its a good balance between control and convenience.

DDS_MANUAL_BY_TOPIC_LIVELINESS_QOS — The DataWriter is considered alive only if the user application has explicitly called operations that assert the liveliness for that particular DataWriter.

This setting forces the user application to assert the liveliness for a DataWriter which gives the user application great control over when other applications can consider the DataWriter to be inactive, but at the cost of convenience.

With the MANUAL_BY_[TOPIC,PARTICIPANT] settings, user application code can assert the liveliness of DataWriters either explicitly by calling the assert_liveliness() operation on the DataWriter (as well as the DomainParticipant for the MANUAL_BY_PARTICIPANT setting) or implicitly by calling write() on the DataWriter. If the application does not use either of the methods mentioned at least once every lease_duration, then the subscribing application may assume that the DataWriter is no longer alive. Sending data MANUAL_BY_TOPIC will cause an assert message to be sent between the DataWriter and its matched DataReaders.

Publishing applications will monitor their DataWriters to make sure that they are honoring their LIVELINESS QosPolicy by asserting their liveliness at least at the period set by the lease_duration. If Connext finds that a DataWriter has failed to have its liveliness asserted by its lease_duration, an internal thread will modify the DataWriter’s

DDS_LIVELINESS_LOST_STATUS and trigger its on_liveliness_lost() DataWriterListener callback if a listener exists, see Listeners (Section 4.4).

Setting the DataReader’s kind of LIVELINESS requests a specific mechanism for the publishing application to maintain the liveliness of DataWriters. The subscribing application may want to know that the publishing application is explicitly asserting the liveliness of the matching DataWriter rather than inferring its liveliness through the liveliness of its DomainParticipant or its sibling DataWriters.

The DataReader’s lease_duration specifies the maximum period at which matching DataWriters must have their liveliness asserted. In addition, in the subscribing application Connext uses an internal thread that wakes up at the period set by the DataReader’s lease_duration to see if the DataWriter’s lease_duration has been violated.

6-105

When a matching DataWriter is determined to be dead (inactive), Connext will modify the

DDS_LIVELINESS_CHANGED_STATUS of each matching DataReader and trigger that

DataReader’s on_liveliness_changed() DataReaderListener callback (if a listener exists).

Although you can set the LIVELINESS QosPolicy on Topics, its value can only be used to initialize the LIVELINESS QosPolicies of either a DataWriter or DataReader. It does not directly affect the operation of Connext, see Section 5.1.3.

For more information on Liveliness, see Maintaining DataWriter Liveliness for kinds AUTOMATIC and MANUAL_BY_PARTICIPANT (Section 14.3.1.2).

6.5.13.1Example

You can use LIVELINESS QosPolicy during system integration to ensure that applications have been coded to meet design specifications. You can also use it during run time to detect when systems are performing outside of design specifications. Receiving applications can take appropriate actions in response to disconnected DataWriters.

The LIVELINESS QosPolicy can be used to manage fail-over when the OWNERSHIP QosPolicy (Section 6.5.15) is set to EXCLUSIVE. This implies that the DataReader will only receive data from the highest strength DataWriter that is alive (active). When that DataWriter’s liveliness expires, then Connext will start delivering data from the next highest strength DataWriter that is still alive.

6.5.13.2Properties

This QosPolicy cannot be modified after the Entity has been enabled.

The DataWriter and DataReader must use compatible settings for this QosPolicy. To be compatible, both of the following conditions must be true:

1.The DataWriter and DataReader must use one of the valid combinations shown in Table 6.49.

2.DataWriter’s lease_duration <= DataReader’s lease_duration.

If this QosPolicy is found to be incompatible, the ON_OFFERED_INCOMPATIBLE_QOS and ON_REQUESTED_INCOMPATIBLE_QOS statuses will be modified and the corresponding

Listeners called for the DataWriter and DataReader respectively.

Table 6.49 Valid Combinations of Liveliness ‘kind’

 

 

DataReader requests:

 

 

 

 

 

 

 

 

MANUAL_

MANUAL_BY_

 

AUTO-

 

 

BY_TOPIC

PARTICIPANT

 

MATIC

 

 

 

 

 

 

 

 

 

 

 

 

 

MANUAL_BY_TOPIC

 

DataWriter

 

 

 

 

 

MANUAL_BY_PARTICIPANT

incompatible

 

offers:

 

 

 

 

 

 

 

AUTOMATIC

incompatible

incompatible

 

 

 

 

 

 

 

6.5.13.3Related QosPolicies

DEADLINE QosPolicy (Section 6.5.5)

OWNERSHIP QosPolicy (Section 6.5.15)

OWNERSHIP_STRENGTH QosPolicy (Section 6.5.16)

6-106

6.5.13.4Applicable Entities

Topics (Section 5.1)

DataWriters (Section 6.3)

DataReaders (Section 7.3)

6.5.13.5System Resource Considerations

An internal thread in Connext will wake up periodically to check the liveliness of all the DataWriters. This happens both in the application that contains the DataWriters at the lease_duration set on the DataWriters as well as the applications that contain the DataReaders at the lease_duration set on the DataReaders. Therefore, as lease_duration becomes smaller, more CPU will be used to wake up threads and perform checks. A short lease_duration set on DataWriters may also use more network bandwidth because liveliness packets are being sent at a higher rate—this is especially true when LIVELINESS kind is set to AUTOMATIC.

6.5.14MULTI_CHANNEL QosPolicy (DDS Extension)

This QosPolicy is used to partition the data published by a DataWriter across multiple channels. A channel is defined by a filter expression and a sequence of multicast locators.

By using this QosPolicy, a DataWriter can be configured to send data to different multicast groups based on the content of the data. Using syntax similar to those used in Content-Based Filters, you can associate different multicast addresses with filter expressions that operate on the values of the fields within the data. When your application’s code calls write(), data is sent to any multicast address for which the data passes the filter.

See Chapter 18 for complete documentation on multi-channel DataWriters.

Note: Durable writer history is not supported for multi-channel DataWriters (see Chapter 18); an error is reported if a multi-channel DataWriter tries to configure Durable Writer History.

This QosPolicy includes the members presented in Table 6.50, Table 6.51, and Table 6.52. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 6.50 DDS_MultiChannelQosPolicy

Type

Field

Description

Name

 

 

 

 

 

 

 

 

 

 

A sequence of channel settings used to configure the channels’

DDS_ChannelSettingsSeq

channels

properties. If the length of the sequence is zero, the QosPolicy

 

 

will be ignored. See Table 6.51.

 

 

 

 

 

Name of the filter class used to describe the filter expressions.

 

 

The following values are supported:

char *

filter_name

DDS_SQLFILTER_NAMEa (see Section 5.4.6)

 

 

DDS_STRINGMATCHFILTER_NAMEa (see

 

 

Section 5.4.7)

 

 

 

a. In Java and C#, you can access the names of the built-in filters by using DomainParticipant.SQLFILTER_NAME and DomainParticipant.STRINGMATCHFILTER_NAME.

The format of the filter_expression should correspond to one of the following filter classes:

DDS_SQLFILTER_NAME (see SQL Filter Expression Notation (Section 5.4.6))

6-107

Table 6.51 DDS_ChannelSettings_t

 

Type

Field Name

Description

 

 

 

 

 

 

 

 

 

 

 

A sequence of multicast settings used to configure the

 

 

 

multicast addresses associated with a channel. The

 

DDS_MulticastSettingsSeq

multicast_settings

sequence cannot be empty.

 

The maximum number of multicast locators in a channel

 

 

 

 

 

 

is limited to four. (A locator is defined by a transport

 

 

 

alias, a multicast address and a port.) See Table 6.52.

 

 

 

 

 

 

 

A logical expression used to determine the data that will

 

 

 

be published in the channel.

 

 

 

This string cannot be NULL. An empty string always

 

char *

filter_expression

evaluates to TRUE.

 

 

 

See SQL Filter Expression Notation (Section 5.4.6) and

 

 

 

STRINGMATCH Filter Expression Notation (Section

 

 

 

5.4.7) for expression syntax.

 

 

 

 

 

 

 

A positive integer designating the relative priority of the

 

 

 

channel, used to determine the transmission order of

 

 

 

pending transmissions. Larger numbers have higher

 

 

 

priority.

 

 

 

To use publication priorities, the DataWriter’s

 

 

 

PUBLISH_MODE QosPolicy (DDS Extension) (Section

 

DDS_Long

priority

6.5.18) must be set for asynchronous publishing and the

 

 

 

DataWriter must use a FlowController that is configured

 

 

 

for highest-priority-first (HPF) scheduling.

 

 

 

See Prioritized Samples (Section 6.6.4).

 

 

 

Note: Prioritized samples are not supported when using

 

 

 

the Java, Ada, or .NET APIs. Therefore the priority field

 

 

 

does not exist when using these APIs.

 

 

 

 

Table 6.52 DDS_MulticastSettings

 

 

 

 

 

 

 

Type

Field Name

Description

 

 

 

 

 

 

 

 

 

 

 

A sequence of transport aliases that specifies which

 

DDS_StringSeq

transports

transport should be used to publish multicast messages

 

 

 

for this channel.

 

 

 

 

 

char *

receive_address

A multicast group address on which DataReaders

 

subscribing to this channel will receive data.

 

 

 

 

 

 

 

 

DDS_Long

receive_port

The multicast port on which DataReaders subscribing to

 

this channel will receive data.

 

 

 

 

 

 

 

DDS_STRINGMATCHFILTER_NAME (see STRINGMATCH Filter Expression Notation (Section 5.4.7)

A DataReader can use the ContentFilteredTopic API (see Using a ContentFilteredTopic (Section 5.4.5)) to subscribe to a subset of the channels used by a DataWriter.

6.5.14.1Example

See Chapter 18: Multi-channel DataWriters.

6.5.14.2Properties

This QosPolicy cannot be modified after the DataWriter is created.

It does not apply to DataReaders, so there is no requirement that the publishing and subscribing sides use compatible values.

6-108

6.5.14.3Related Qos Policies

DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4)

6.5.14.4Applicable Entities

DataWriters (Section 6.3)

6.5.14.5System Resource Considerations

The following fields in the DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4) configure the resources associated with the channels stored in the MULTI_CHANNEL QosPolicy:

channel_seq_max_length

channel_filter_expression_max_length

For information about partitioning topic data across multiple channels, please refer to Chapter 18: Multi-channel DataWriters.

6.5.15OWNERSHIP QosPolicy

The OWNERSHIP QosPolicy specifies whether a DataReader receive data for an instance of a

Topic sent by multiple DataWriters.

For non-keyed Topics, there is only one instance of the Topic. This policy includes the single member shown in Table 6.53.

Table 6.53 DDS_OwnershipQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

DDS_OwnershipQosPolicyKind

kind

DDS_SHARED_OWNERSHIP_QOS or

DDS_EXCLUSIVE_OWNERSHIP_QOS

 

 

 

 

 

The kind of OWNERSHIP can be set to one of two values:

SHARED Ownership

When OWNERSHIP is SHARED, and multiple DataWriters for the Topic publishes the value of the same instance, all the updates are delivered to subscribing DataReaders. So in effect, there is no “owner;” no single DataWriter is responsible for updating the value of an instance. The subscribing application will receive modifications from all DataWriters.

EXCLUSIVE Ownership

When OWNERSHIP is EXCLUSIVE, each instance can only be owned by one DataWriter at a time. This means that a single DataWriter is identified as the exclusive owner whose updates are allowed to modify the value of the instance for matching DataWriters. Other DataWriters may submit modifications for the instance, but only those made by the current owner are passed on to the DataReaders. If a non-owner DataWriter modifies an instance, no error or notification is made; the modification is simply ignored. The owner of the instance can change dynamically.

Note for non-keyed Topics, EXCLUSIVE ownership implies that DataReaders will pay attention to only one DataWriter at a time because there is only a single instance. For keyed Topics, DataReaders may actually receive data from multiple DataWriters when different DataWriters own different instances of the Topic.

6-109

This QosPolicy is often used to help users build systems that have redundant elements to safeguard against component or application failures. When systems have active and hot standby components, the Ownership QosPolicy can be used to ensure that data from standby applications are only delivered in the case of the failure of the primary.

The Ownership QosPolicy can also be used to create data channels or topics that are designed to be taken over by external applications for testing or maintenance purposes.

Although you can set the OWNERSHIP QosPolicy on Topics, its value can only be used to initialize the OWNERSHIP QosPolicies of either a DataWriter or DataReader. It does not directly affect the operation of Connext, see Section 5.1.3.

6.5.15.1How Connext Selects which DataWriter is the Exclusive Owner

When OWNERSHIP is EXCLUSIVE, the owner of an instance at any given time is the DataWriter with the highest OWNERSHIP_STRENGTH QosPolicy (Section 6.5.16) that is “alive” as defined by the LIVELINESS QosPolicy (Section 6.5.13)) and has not violated the DEADLINE QosPolicy (Section 6.5.5) of the DataReader. OWNERSHIP_STRENGTH is simply an integer set by the DataWriter.

As mentioned before, if the Topic’s data type is keyed (see Section 2.2.2) then EXCLUSIVE ownership is determined on a per-instance basis. That is, the DataWriter owner of each instance is considered separately. A DataReader can receive values written by a lower strength DataWriter as long as those values are for instances that are not being written by a higher-strength

DataWriter.

If there are multiple DataWriters with the same OWNERSHIP_STRENGTH writing to the same instance, Connext resolves the tie by choosing the DataWriter with the smallest GUID (Globally Unique Identifier, see Section 14.1.1.). This means that different DataReaders (in different applications) of the same Topic will all choose the same DataWriter as the owner when there are multiple DataWriters with the same strength.

The owner of an instance can change when:

A DataWriter with a higher OWNERSHIP_STRENGTH publishes a value for the instance.

The OWNERSHIP_STRENGTH of the owning DataWriter is dynamically changed to be less than the strength of an existing DataWriter of the instance.

The owning DataWriter stops asserting its LIVELINESS (the DataWriter dies).

The owning DataWriter violates the DEADLINE QosPolicy by not updating the value of the instance within the period set by the DEADLINE.

Note however, the change of ownership is not synchronous across different DataReaders in different participants. That is, DataReaders in different applications may not determine that the ownership of an instance has changed at exactly the same time.

6.5.15.2Example

OWNERSHIP is really a property that is shared between DataReaders and DataWriters of a Topic. However, in a system, some Topics will be exclusively owned and others will be shared. System requirements will determine which are which.

An example of a Topic that may be shared is one that is used by applications to publish alarm messages. If the application detects an anomalous condition, it will use a DataWriter to write a Topic “Alarm.” Another application that records alarms into a system log file will have a DataReader that subscribes to “Alarm.” In this example, any number of applications can publish the “Alarm” message. There is no concept that only one application at a time is allowed to publish the “Alarm” message, so in this case, the OWNERSHIP of the DataWriters and DataReaders should be set to SHARED.

6-110

In a different part of the system, EXCLUSIVE OWNERSHIP may be used to implement redundancy in support of fault tolerance. Say, the distributed system controls a traffic system. It monitors traffic and changes the information posted on signs, the operation of metering lights, and the timing of traffic lights. This system must be tolerant to failure of any part of the system including the application that actually issues commands to change the lights at a particular intersection.

One way to implement fault tolerance is to create the system redundantly both in hardware and software. So if a piece of the running system fails, a backup can take over. In systems where failover from the primary to backup system must be seamless and transparent, the actual mechanics of failover must be fast, and the redundant component must immediately pickup where the failed component left off. For the network connections of the component, Connext can provided redundant DataWriter and DataReaders.

In this case, you would not want the DataReaders to receive redundant messages from the redundant DataWriters. Instead you will want the DataReaders to only receive messages from the primary application and only from a backup application when a failure occurs. To continue our example, if we have redundant applications that all try to control the lights at an intersection, we would want the DataReaders on the light to receive messages only from the primary application. To do so, we should configure the DataWriters and DataReaders to have EXCLUSIVE OWNERSHIP and set the OWNERSHIP_STRENGTH differently on different redundant applications to distinguish between primary and backup systems.

6.5.15.3Properties

This QosPolicy cannot be modified after the Entity is enabled.

It must be set to the same kind on both the publishing and subscribing sides. If a DataWriter and DataReader of the same topic are found to have different kinds set for the OWNERSHIP QoS, the

ON_OFFERED_INCOMPATIBLE_QOS and ON_REQUESTED_INCOMPATIBLE_QOS statuses will be modified and the corresponding Listeners called for the DataWriter and DataReader respectively.

6.5.15.4Related QosPolicies

DEADLINE QosPolicy (Section 6.5.5)

LIVELINESS QosPolicy (Section 6.5.13)

OWNERSHIP_STRENGTH QosPolicy (Section 6.5.16)

6.5.15.5Applicable Entities

Topics (Section 5.1)

DataWriters (Section 6.3)

DataReaders (Section 7.3)

6-111

6.5.15.6System Resource Considerations

This QosPolicy does not significantly impact the use of system resources.

6.5.16OWNERSHIP_STRENGTH QosPolicy

The OWNERSHIP_STRENGTH QosPolicy is used to rank DataWriters of the same instance of a Topic, so that Connext can decide which DataWriter will have ownership of the instance when the OWNERSHIP QosPolicy (Section 6.5.15) is set to EXCLUSIVE.

It includes the member in Table 6.54. For the default and valid range, please refer to the API Reference HTML documentation.

Table 6.54 DDS_OwnershipStrengthQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

DDS_Long

value

The strength value used to arbitrate among multiple DataWriters.

 

 

 

This QosPolicy only applies to DataWriters when EXCLUSIVE OWNERSHIP is used. The strength is simply an integer value, and the DataWriter with the largest value is the owner. A deterministic method is used to decide which DataWriter is the owner when there are multiple DataWriters that have equal strengths. See Section 6.5.15.1 for more details.

6.5.16.1Example

Suppose there are two DataWriters sending samples of the same Topic instance, one as the main DataWriter, and the other as a backup. If you want to make sure the DataReader always receive from the main one whenever possible, then set the main DataWriter to use a higher ownership_strength value than the one used by the backup DataWriter.

6.5.16.2Properties

This QosPolicy can be changed at any time.

It does not apply to DataReaders, so there is no requirement that the publishing and subscribing sides use compatible values.

6.5.16.3Related QosPolicies

OWNERSHIP QosPolicy (Section 6.5.15)

6.5.16.4Applicable Entities

DataWriters (Section 6.3)

6.5.16.5System Resource Considerations

The use of this policy does not significantly impact the use of resources.

6.5.17PROPERTY QosPolicy (DDS Extension)

The PROPERTY QosPolicy stores name/value (string) pairs that can be used to configure certain parameters of Connext that are not exposed through formal QoS policies.

It can also be used to store and propagate application-specific name/value pairs that can be retrieved by user code during discovery. This is similar to the USER_DATA QosPolicy, except

6-112

this policy uses (name, value) pairs, and you can select whether or not a particular pair should be propagated (included in the built-in topic).

It includes the member in Table 6.55.

Table 6.55 DDS_PropertyQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

A sequence of: (name, value) pairs and booleans that indicate

DDS_PropertySeq

value

whether the pair should be propagated (included in the entity’s

 

 

built-in topic upon discovery).

 

 

 

The Property QoS stores name/value pairs for an Entity. Both the name and value are strings. Certain configurable parameters for Entities that do not have a formal DDS QoS definition may be configured via this QoS by using a pre-defined name and the desired setting in string form.

You can manipulate the sequence of properties (name, value pairs) with the standard methods available for sequences. You can also use the helper class, DDSPropertyQosPolicyHelper, which provides another way to work with a PropertyQosPolicy object.

The PropertyQosPolicy may be used to configure:

Durable writer history (see Section 12.3.2)

Durable reader state (see Section 12.4.4)

Built-in and extension Transport Plugins (see Section 15.6, Section 25.2, Section 36.2).

Automatic registration of built-in types (see Registering Built-in Types (Section 3.2.1))

Clock Selection (Section 8.6)

In addition, you can add your own name/value pairs to the Property QoS of an Entity. You may also use this QosPolicy to direct Connext to propagate these name/value pairs with the discovery information for the Entity. Applications that discover the Entity can then access the user-specific name/value pairs in the discovery information of the remote Entity. This allows you to add meta-information about an Entity for application-specific use, for example, authentication/authorization certificates (which can also be done using the User or Group Data QoS).

Reasons for using the PropertyQosPolicy include:

Some features can only be configured through the PropertyQosPolicy, not through other QoS or API.s For example, Durable Reader State, Durable Writer History, Built-in Types, Monotonic Clock.

Alternative way to configure built-in transports settings. For example, to use non-default values for the built-in transports without using the PropertyQosPolicy, you would have to create a DomainParticipant disabled, change the built-in transport property settings, then enable the DomainParticipant. Using the PropertyQosPolicy to configure built-in transport settings will save you the work of enabling and disabling the DomainParticipant. Also, transport settings are not a QoS and therefore cannot be configured through an XML file. By configuring built-in transport settings through the PropertyQosPolicy instead, XML files can be used.

Note: When using the Java or .NET APIs, transport configuration must take place through the PropertyQosPolicy (not through the transport property structures).

Alternative way to support multiple instances of built-in transports (without using Transport API).

6-113

Alternative way to dynamically load extension transports (such as RTI Secure WAN Transport1 or RTI TCP Transport2) or user-created transport plugins in C/C++ language bindings. If the extension or user-created transport plugin is installed using the transport API instead, the library that extra transport library/code will need to be linked into your application and may require recompilation.

Allows full pluggable transport configuration for non-C/C++ language bindings (Java, C++/CLI, C#, etc.) The pluggable transport API is not available in those languages. Without using PropertyQosPolicy, you cannot use extension transports (such as RTI Secure WAN Transport) and you cannot create your own custom transport.

The PropertyQosPolicyHelper operations are described in Table 6.56. For more information, see the API Reference HTML documentation.

Table 6.56 PropertyQoSPolicyHelper Operations

Operation

Description

 

 

 

 

get_number_of_properties

Gets the number of properties in the input policy.

 

 

assert_property

Asserts the property identified by name in the input policy. (Either adds it,

or replaces an existing one.)

 

 

 

add_property

Adds a new property to the input policy.

 

 

lookup_property

Searches for a property in the input policy given its name.

 

 

remove_property

Removes a property from the input policy.

 

 

get_properties

Retrieves a list of properties whose names match the input prefix.

 

 

6.5.17.1Properties

This QosPolicy can be changed at any time.

There is no requirement that the publishing and subscribing sides use compatible values.

6.5.17.2Related QosPolicies

DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4)

6.5.17.3Applicable Entities

DataWriters (Section 6.3)

DataReaders (Section 7.3)

DomainParticipants (Section 8.3)

1.RTI Secure WAN Transport is an optional packages available for separate purchase.

2.RTI TCP Transport is included with your Connext distribution but is not a built-in transport and therefore not enabled by default.

6-114

6.5.17.4System Resource Considerations

The DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4) contains several fields for configuring the resources associated with the properties stored in this QosPolicy.

6.5.18PUBLISH_MODE QosPolicy (DDS Extension)

This QosPolicy determines the DataWriter’s publishing mode, either asynchronous or synchronous.

The publishing mode controls whether data is written synchronously—in the context of the user thread when calling write(), or asynchronously—in the context of a separate thread internal to

Connext.

Note: Asynchronous DataWriters do not perform sender-side filtering. Any filtering, such as time-based or content-based filtering, takes place on the DataReader side.

Each Publisher spawns a single asynchronous publishing thread (set in its ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension) (Section 6.4.1)) to serve all its asynchronous DataWriters.

When data is written asynchronously, a FlowController (Section 6.6), identified by flow_controller_name, can be used to shape the network traffic. The FlowController's properties determine when the asynchronous publishing thread is allowed to send data and how much.

The fastest way for Connext to send data is for the user thread to execute the middleware code that actually sends the data itself. However, there are times when user applications may need or want an internal middleware thread to send the data instead. For instance, for sending large data reliably, an asynchronous thread must be used (see ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension) (Section 6.4.1)).

This QosPolicy can select a FlowController to prioritize or shape the data flow sent by a DataWriter to DataReaders. Shaping a data flow usually means limiting the maximum data rates with which the middleware will send data for a DataWriter. The FlowController will buffer data sent faster than the maximum rate by the DataWriter, and then only send the excess data when the user send rate drops below the maximum rate.

This QosPolicy includes the members in Table 6.57. For the defaults, please refer to the API Reference HTML documentation.

Table 6.57 DDS_PublishModeQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

DDS_PublishMode

 

Either:

kind

DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS

QosPolicyKind

 

DDS_SYNCHRONOUS_PUBLISH_MODE_QOS

 

 

 

 

 

6-115

Table 6.57 DDS_PublishModeQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

Name of the associated flow controller.

 

 

There are three built-in FlowControllers:

 

flow_controller_

DDS_DEFAULT_FLOW_CONTROLLER_NAME

char*

DDS_FIXED_RATE_FLOW_CONTROLLER_NAME

name

 

DDS_ON_DEMAND_FLOW_CONTROLLER_NAME

 

 

 

 

You may also create your own FlowControllers.

 

 

See FlowControllers (DDS Extension) (Section 6.6).

 

 

 

 

 

A positive integer designating the relative priority of the

 

 

DataWriter, used to determine the transmission order of pending

 

 

writes.

 

 

To use publication priorities, this QosPolicy’s kind must be

 

 

DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS and the

DDS_Long

priority

DataWriter must use a FlowController with a highest-priority

 

 

first (HPF) scheduling_policy.

 

 

See Prioritized Samples (Section 6.6.4).

 

 

Note: Prioritized samples are not supported when using the Java,

 

 

Ada, or .NET APIs. Therefore the priority field does not exist

 

 

when using these APIs.

 

 

 

The maximum number of samples that will be coalesced depends on

NDDS_Transport_Property_t::gather_send_buffer_count_max (each sample requires at least 2- 4 gather-send buffers). Performance can be improved by increasing

NDDS_Transport_Property_t::gather_send_buffer_count_max. Note that the maximum value is operating system dependent.

Connext queues samples until they can be sent by the asynchronous publishing thread (as determined by the corresponding FlowController).

The number of samples that will be queued is determined by the HISTORY QosPolicy (Section 6.5.10): when using KEEP_LAST, the most recent depth samples are kept in the queue.

Once unsent samples are removed from the queue, they are no longer available to the asynchronous publishing thread and will therefore never be sent.

Unless flow_controller_name points to one of the built-in FlowControllers, finalizing the DataWriterQos will also free the string pointed to by flow_controller_name. Therefore, you should use DDS_String_dup() before passing the string to flow_controller_name, or reset flow_controller_name to NULL before the destructing /finalizing the QoS.

Advantages of Asynchronous Publishing:

Asynchronous publishing may increase latency, but offers the following advantages:

The write() call does not make any network calls and is therefore faster and more deterministic. This becomes important when the user thread is executing time-critical code.

When data is written in bursts or when sending large data types as multiple fragments, a flow controller can throttle the send rate of the asynchronous publishing thread to avoid flooding the network.

Asynchronously written samples for the same destination will be coalesced into a single network packet which reduces bandwidth consumption.

6-116

6.5.18.1Properties

This QosPolicy cannot be modified after the Publisher is created.

Since it is only for DataWriters, there are no compatibility restrictions for how it is set on the publishing and subscribing sides.

6.5.18.2Related QosPolicies

ASYNCHRONOUS_PUBLISHER QosPolicy (DDS Extension) (Section 6.4.1)

HISTORY QosPolicy (Section 6.5.10)

6.5.18.3Applicable Entities

DataWriters (Section 6.3)

6.5.18.4System Resource Considerations

See Configuring Resource Limits for Asynchronous DataWriters (Section 6.5.20.1).

System resource usage depends on the settings in the corresponding FlowController (see Section 6.6).

6.5.19RELIABILITY QosPolicy

This RELIABILITY QosPolicy determines whether or not data published by a DataWriter will be reliably delivered by Connext to matching DataReaders. The reliability protocol used by Connext is discussed in Chapter 10: Reliable Communications.

The reliability of a connection between a DataWriter and DataReader is entirely user configurable. It can be done on a per DataWriter/DataReader connection. A connection may be configured to be "best effort" which means that Connext will not use any resources to monitor or guarantee that the data sent by a DataWriter is received by a DataReader.

For some use cases, such as the periodic update of sensor values to a GUI displaying the value to a person, "best effort" delivery is often good enough. It is certainly the fastest, most efficient, and least resource-intensive (CPU and network bandwidth) method of getting the newest/latest value for a topic from DataWriters to DataReaders. But there is no guarantee that the data sent will be received. It may be lost due to a variety of factors, including data loss by the physical transport such as wireless RF or even Ethernet. Packets received out of order are dropped and a SAMPLE_LOST Status (Section 7.3.7.7) is generated.

However, there are data streams (topics) in which you want an absolute guarantee that all data sent by a DataWriter is received reliably by DataReaders. This means that Connext must check whether or not data was received, and repair any data that was lost by resending a copy of the data as many times as it takes for the DataReader to receive the data.

Connext uses a reliability protocol configured and tuned by these QoS policies:

HISTORY QosPolicy (Section 6.5.10),

DATA_WRITER_PROTOCOL QosPolicy (DDS Extension) (Section 6.5.3),

DATA_READER_PROTOCOL QosPolicy (DDS Extension) (Section 7.6.1),

RESOURCE_LIMITS QosPolicy (Section 6.5.20)

The Reliability QoS policy is simply a switch to turn on the reliability protocol for a DataWriter/ DataReader connection. The level of reliability provided by Connext is determined by the configuration of the aforementioned QoS policies.

You can configure Connext to deliver ALL data in the order they were sent (also known as absolute or strict reliability). Or, as a trade-off for less memory, CPU, and network usage, you

6-117

can choose a reduced level of reliability where only the last N values are guaranteed to be delivered reliably to DataReaders (where N is user-configurable). With the reduced level of reliability, there are no guarantees that the data sent before the last N are received. Only the last N data packets are monitored and repaired if necessary.

It includes the members in Table 6.58. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 6.58 DDS_ReliabilityQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

Can be either:

 

 

• DDS_BEST_EFFORT_RELIABILITY_QOS:

 

 

Data samples are sent once and missed

DDS_ReliabilityQosPolicyKind

kind

samples are acceptable.

 

 

• DDS_RELIABLE_RELIABILITY_QOS:

 

 

Connext will make sure that data sent is

 

 

received and missed samples are resent.

 

 

 

 

 

How long a DataWriter can block on a write()

DDS_Duration_t

max_blocking_time

when the send queue is full due to

 

 

unacknowledged messages. (Has no meaning for

 

 

DataReaders.)

 

 

 

 

 

Kind of reliable acknowledgment.

 

 

Only applies when kind is RELIABLE.

 

 

Sets the kind of acknowledgments supported by a

 

 

DataWriter and sent by DataReader.

 

 

Possible values:

DDS_ReliabilityQosPolicy-

acknowledgment_

• DDS_PROTOCOL_

AcknowledgmentModeKind

kind

ACKNOWLEDGMENT_MODE

 

 

• DDS_APPLICATION_AUTO_

 

 

ACKNOWLEDGMENT_MODE

 

 

• DDS_APPLICATION_EXPLICIT_

 

 

ACKNOWLEDGMENT_MODE

 

 

See Application Acknowledgment Kinds

 

 

(Section 6.3.12.1)

 

 

 

The kind of RELIABILITY can be either:

BEST_EFFORT Connext will send data samples only once to DataReaders. No effort or resources are spent to track whether or not sent samples are received. Minimal resources are used. This is the most deterministic method of sending data since there is no indeterministic delay that can be introduced by buffering or resending data. Data samples may be lost. This setting is good for periodic data.

RELIABLE Connext will send samples reliably to DataReaders–buffering sent data until they have been acknowledged as being received by DataReaders and resending any samples that may have been lost during transport. Additional resources configured by the HISTORY and RESOURCE_LIMITS QosPolicies may be used. Extra packets will be sent on the network to query (heartbeat) and acknowledge the receipt of samples by the DataReader. This setting is a good choice when guaranteed data delivery is required; for example, sending events or commands.

To send large data reliably, you will also need to set the PUBLISH_MODE QosPolicy (DDS Extension) (Section 6.5.18) kind to DDS_ASYNCHRONOUS_PUBLISH_MODE_QOS. Large in this context means that the data cannot be sent as a single packet by a transport (for example, data larger than 63K when using UDP/IP).

6-118

While a DataWriter sends data reliably, the HISTORY QosPolicy (Section 6.5.10) and RESOURCE_LIMITS QosPolicy (Section 6.5.20) determine how many samples can be stored while waiting for acknowledgements from DataReaders. A sample that is sent reliably is entered in the DataWriter’s send queue awaiting acknowledgement from DataReaders. How many samples that the DataWriter is allowed to store in the send queue for a data-instance depends on the kind of the HISTORY QoS as well as the max_samples_per_instance and max_samples parameter of the RESOURCE_LIMITS QoS.

If the HISTORY kind is KEEP_LAST, then the DataWriter is allowed to have the HISTORY depth number of samples per instance of the Topic in the send queue. Should the number of unacknowledge samples in the send queue for a data-instance reach the HISTORY depth, then the next sample written by the DataWriter for the instance will overwrite the oldest sample for the instance in the queue. This implies that an unacknowledged sample may be overwritten and thus lost. So even if the RELIABILITY kind is RELIABLE, if the HISTORY kind is KEEP_LAST, it is possible that some data sent by the DataWriter will not be delivered to the DataReader. What is guaranteed is that if the DataWriter stops writing, the last N samples that the DataWriter wrote will be delivered reliably; where n is the value of the HISTORY depth.

However, if the HISTORY kind is KEEP_ALL, then when the send queue is filled with acknowledged samples (either due to the number of unacknowledged samples for an instance reaching the RESOURCE_LIMITS max_samples_per_instance value or the total number of unacknowledged samples have reached the size of the send queue as specified by RESOURCE_LIMITS max_samples), the next write() operation on the DataWriter will block until either a sample in the queue has been fully acknowledged by DataReaders and thus can be overwritten or a timeout of RELIABILITY max_blocking_period has been reached.

If there is still no space in the queue when max_blocking_time is reached, the write() call will return a failure with the error code DDS_RETCODE_TIMEOUT.

Thus for strict reliability—a guarantee that all data samples sent by a DataWriter are received by DataReaders—you must use a RELIABILITY kind of RELIABLE and a HISTORY kind of

KEEP_ALL for both the DataWriter and the DataReader.

Although you can set the RELIABILITY QosPolicy on Topics, its value can only be used to initialize the RELIABILITY QosPolicies of either a DataWriter or DataReader. It does not directly affect the operation of Connext, see Section 5.1.3.

6.5.19.1Example

This QosPolicy is used to achieve reliable communications, which is discussed in Chapter 10: Reliable Communications and Section 10.3.1.

6.5.19.2Properties

This QosPolicy cannot be modified after the Entity has been enabled.

The DataWriter and DataReader must use compatible settings for this QosPolicy. To be compatible, the DataWriter and DataReader must use one of the valid combinations for the Reliability kind (see Table 6.59), and one of the valid combinations for the acknowledgment_kind (see Table 6.60):

Table 6.59 Valid Combinations of Reliability ‘kind’

 

 

DataReader requests:

 

 

 

 

 

 

BEST_EFFORT

RELIABLE

 

 

 

 

 

 

 

 

DataWriter offers:

BEST_EFFORT

incompatible

 

 

 

RELIABLE

 

 

 

 

 

6-119

Table 6.60 Valid Combinations of Reliability ‘acknowledgment_kind’

 

 

 

DataReader requests:

 

 

 

 

 

 

 

 

 

 

PROTOCOL

 

APPLICATION_

 

APPLICATION_

 

 

 

AUTO

 

EXPLICIT

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

PROTOCOL

 

incompatible

 

incompatible

DataWriter

 

 

 

 

 

 

APPLICATION_AUTO

 

 

offers:

 

 

 

 

 

 

APPLICATION_EXPLICIT

 

 

 

 

 

 

 

 

 

 

 

 

If this QosPolicy is found to be incompatible, statuses ON_OFFERED_INCOMPATIBLE_QOS and ON_REQUESTED_INCOMPATIBLE_QOS will be modified and the corresponding

Listeners called for the DataWriter and DataReader, respectively.

There are no compatibility issues regarding the value of max_blocking_wait, since it does not apply to DataReaders.

6.5.19.3Related QosPolicies

HISTORY QosPolicy (Section 6.5.10)

PUBLISH_MODE QosPolicy (DDS Extension) (Section 6.5.18)

RESOURCE_LIMITS QosPolicy (Section 6.5.20)

6.5.19.4Applicable Entities

Topics (Section 5.1)

DataWriters (Section 6.3)

DataReaders (Section 7.3)

6.5.19.5System Resource Considerations

Setting the kind to RELIABLE will cause Connext to use up more resources to monitor and maintain a reliable connection between a DataWriter and all of its reliable DataReaders. This includes the use of extra CPU and network bandwidth to send and process heartbeat, ACK/ NACK, and repair packets (see Chapter 10: Reliable Communications).

Setting max_blocking_time to a non-zero number may block the sending thread when the RELIABILITY kind is RELIABLE.

6.5.20RESOURCE_LIMITS QosPolicy

For the reliability protocol (and the DURABILITY QosPolicy (Section 6.5.7)), this QosPolicy determines the actual maximum queue size when the HISTORY QosPolicy (Section 6.5.10) is set to KEEP_ALL.

In general, this QosPolicy is used to limit the amount of system memory that Connext can allocate. For embedded real-time systems and safety-critical systems, pre-determination of maximum memory usage is often required. In addition, dynamic memory allocation could introduce non-deterministic latencies in time-critical paths.

This QosPolicy can be set such that an entity does not dynamically allocate any more memory after its initialization phase.

It includes the members in Table 6.61. For defaults and valid ranges, please refer to the API Reference HTML documentation.

One of the most important fields is max_samples, which sets the size and causes memory to be allocated for the send or receive queues. For information on how this policy affects reliability, see Tuning Queue Sizes and Other Resource Limits (Section 10.3.2).

6-120

Table 6.61 DDS_ResourceLimitsQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

 

 

 

 

 

DDS_Long

max_samples

Maximum number of live samples that Connext

can

store for a

DataWriter/DataReader. This is a physical limit.

 

 

 

 

 

 

 

 

 

 

 

 

 

Maximum number of instances that can be managed by a DataWriter/

 

 

DataReader.

 

 

 

DDS_Long

max_instances

For DataReaders, max_instances must be <= max_total_instances in the

DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension)

 

 

 

 

(Section 7.6.2).

 

 

 

 

 

See also: Example (Section 6.5.20.3).

 

 

 

 

 

 

 

 

Maximum number of samples of any one instance that Connext will

 

 

store for a DataWriter/DataReader.

 

 

 

DDS_Long

max_samples_

For keyed types and DataReaders, this value only applies to samples

per_instance

with an instance state of DDS_ALIVE_INSTANCE_STATE.

 

 

 

 

 

If a keyed Topic is not used, then max_samples_per_instance must

 

 

equal max_samples.

 

 

 

 

 

 

 

 

 

DDS_Long

initial_samples

Initial number of samples that Connext will store

for

a

DataWriter/

DataReader. (DDS extension)

 

 

 

 

 

 

 

 

 

 

 

 

 

 

DDS_Long

initial_instances

Initial number of instances that can be managed

by

a

DataWriter/

DataReader. (DDS extension)

 

 

 

 

 

 

 

 

 

 

 

DDS_Long

instance_hash_

Number of hash buckets, which are used by Connext to facilitate

buckets

instance lookup. (DDS extension).

 

 

 

 

 

 

 

 

 

 

 

 

 

When a DataWriter or DataReader is created, the initial_instances and initial_samples parameters determine the amount of memory first allocated for the those Entities. As the application executes, if more space is needed in the send/receive queues to store samples or as more instances are created, then Connext will automatically allocate memory until the limits of max_instances and max_samples are reached.

You may set initial_instances = max_instances and initial_samples = max_samples if you do not want Connext to dynamically allocate memory after initialization.

For keyed Topics, the max_samples_per_instance field in this policy represents maximum number of samples with the same key that are allowed to be stored by a DataWriter or DataReader. This is a logical limit. The hard physical limit is determined by max_samples. However, because the theoretical number of instances may be quite large (as set by max_instances), you may not want Connext to allocate the total memory needed to hold the maximum number of samples per instance for all possible instances (max_samples_per_instance * max_instances) because during normal operations, the application will never have to hold that much data for the Entity.

So it is possible that an Entity will hit the physical limit max_samples before it hits the max_samples_per_instance limit for a particular instance. However, Connext must be able to store max_samples_per_instance for at least one instance. Therefore, max_samples_per_instance must be <= max_samples.

Important: If a keyed data type is not used, then there is only a single instance of the Topic, so max_samples_per_instance must equal max_samples.

Once a physical or logical limit is hit, then how Connext deals with new data samples being sent or received for a DataWriter or DataReader is described in the HISTORY QosPolicy (Section 6.5.10) setting of DDS_KEEP_ALL_HISTORY_QOS. It is closely tied to whether or not a reliable connection is being maintained.

Although you can set the RESOURCE_LIMITS QosPolicy on Topics, its value can only be used to initialize the RESOURCE_LIMITS QosPolicies of either a DataWriter or DataReader. It does not directly affect the operation of Connext, see Section 5.1.3.

6-121

6.5.20.1Configuring Resource Limits for Asynchronous DataWriters

When using an asynchronous Publisher, if a call to write() is blocked due to a resource limit, the block will last until the timeout period expires, which will prevent others from freeing the resource. To avoid this situation, make sure that the DomainParticipant’s outstanding_asynchronous_sample_allocation in the DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4) is always greater than the sum of all asynchronous DataWritersmax_samples.

6.5.20.2Configuring DataWriter Instance Replacement

When the max_instances limit is reached, a DataWriter will try to make space for a new instance by replacing an existing instance according to the instance replacement kind set in instance_replacement. For the sake of instance replacement, an instance is considered to be unregistered, disposed, or alive. The oldest instance of the specified kind, if such an instance exists, would be replaced with the new instance. Also, all samples of a replaced instance must already have been acknowledged, such that removing the instance would not deprive any existing reader from receiving them.

Since an unregistered instance is one that a DataWriter will not update any further, unregistered instances are replaced before any other instance kinds. This applies for all instance_replacement kinds; for example, the ALIVE_THEN_DISPOSED kind would first replace unregistered, then alive, and then disposed instances. The rest of the kinds specify one or two kinds (e.g DISPOSED and ALIVE_OR_DISPOSED). For the single kind, if no unregistered instances are replaceable, and no instances of the specified kind are replaceable, then the instance replacement will fail. For the others specifying multiple kinds, it either specifies to look for one kind first and then another kind (e.g. ALIVE_THEN_DISPOSED), meaning if the first kind is found then that instance will be replaced, or it will replace either of the kinds specified (e.g. ALIVE_OR_DISPOSED), whichever is older as determined by the time of instance registering, writing, or disposing.

If an acknowledged instance of the specified kind is found, the DataWriter will reclaim its resources for the new instance. It will also invoke the DataWriterListener’s on_instance_replaced() callback (if installed) and notify the user with the handle of the replaced instance, which can then be used to retrieve the instance key from within the callback. If no replaceable instances are found, the new instance will fail to be registered; the DataWriter may block, if the instance registration was done in the context of a write, or it may return with an out- of-resources return code.

In addition, replace_empty_instances (in the DATA_WRITER_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 6.5.4)) configures whether instances with no samples are eligible to be replaced. If this is set, then a DataWriter will first try to replace empty instances, even before replacing unregistered instances.

6.5.20.3Example

If you want to be able to store max_samples_per_instance for every instance, then you should set

max_samples >= max_instances * max_samples_per_instance

But if you want to save memory and you do not expect that the running application will ever reach the case where it will see max_instances of instances, then you may use a smaller value for max_samples to save memory.

In any case, there is a lower limit for max_samples:

max_samples >= max_samples_per_instance

If the HISTORY QosPolicy (Section 6.5.10)’s kind is set to KEEP_LAST, then you should set:

max_samples_per_instance = HISTORY.depth

6-122

6.5.20.4Properties

This QosPolicy cannot be modified after the Entity is enabled.

There are no requirements that the publishing and subscribing sides use compatible values.

6.5.20.5Related QosPolicies

HISTORY QosPolicy (Section 6.5.10)

RELIABILITY QosPolicy (Section 6.5.19)

For DataReaders, max_instances must be <= max_total_instances in the DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 7.6.2)

6.5.20.6Applicable Entities

Topics (Section 5.1)

DataWriters (Section 6.3)

DataReaders (Section 7.3)

6.5.20.7System Resource Considerations

Larger initial_* numbers will increase the initial system memory usage. Larger max_* numbers will increase the worst-case system memory usage.

Increasing instance_hash_buckets speeds up instance-lookup time but also increases memory usage.

6.5.21TRANSPORT_PRIORITY QosPolicy

The TRANSPORT_PRIORITY QosPolicy is optional and only partially supported on certain OSs and transports by RTI. However, its intention is to allow you to specify on a per-DataWriter basis that the data sent by a DataWriter is of a different priority.

DDS does not specify how a DDS implementation shall treat data of different priorities. It is often difficult or impossible for DDS implementations to treat data of higher priority differently than data of lower priority, especially when data is being sent (delivered to a physical transport) directly by the thread that called DataWriter’s write() operation. Also, many physical network transports themselves do not have an end-user controllable level of data packet priority.

In Connext, for the UDPv4 built-in transport, the value set in the TRANSPORT_PRIORITY QosPolicy is used in a setsockopt call to set the TOS (type of service) bits of the IPv4 header for datagrams sent by a DataWriter. It is platform dependent on how and whether or not the setsockopt has an effect. On some platforms such as Windows and Linux, external permissions must be given to the user application in order to set the TOS bits.

It is incorrect to assume that using the TRANSPORT_PRIORITY QosPolicy will have any effect at all on the end-to-end delivery of data from a DataWriter to a DataReader. All network elements such as switches and routers must have the capability and be enabled to actually use the TOS bits to treat higher-priority packets differently. Thus the ability to use the TRANSPORT_PRIORITY QosPolicy must be designed and configured at a system level; just turning it on in an application may have no effect at all.

It includes the member in Table 6.62. For the default and valid range, please refer to the API Reference HTML documentation.

Table 6.62 DDS_TransportPriorityQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

DDS_Long

value

Hint as to how to set the priority.

 

 

 

6-123

Connext will propagate the value set on a per-DataWriter basis to the transport when the DataWriter publishes data. It is up to the implementation of the transport to do something with the value, if anything.

Although you can set the TRANSPORT_PRIORITY QosPolicy on Topics, its value can only be used to initialize the TRANSPORT_PRIORITY QosPolicies of a DataWriter. It does not directly affect the operation of Connext, see Section 5.1.3.

6.5.21.1Example

Should Connext be configured with a transport that can use and will honor the concept of a prioritized message, then you would be able to create a DataWriter of a Topic whose data samples, when published, will be sent at a higher priority than other DataWriters that use the same transport.

6.5.21.2Properties

This QosPolicy may be modified after the entity is created.

It does not apply to DataReaders, so there is no requirement that the publishing and subscribing sides use compatible values.

6.5.21.3Related QosPolicies

This QosPolicy does not interact with any other policies.

6.5.21.4Applicable Entities

Topics (Section 5.1)

DataWriters (Section 6.3)

6.5.21.5System Resource Considerations

The use of this policy does not significantly impact the use of resources. However, if a transport is implemented to use the value set by this policy, then there may be transport-specific issues regarding the resources that the transport implementation itself uses.

6.5.22TRANSPORT_SELECTION QosPolicy (DDS Extension)

The TRANSPORT_SELECTION QosPolicy allows you to select the transports that have been installed with the DomainParticipant to be used by the DataWriter or DataReader.

An application may be simultaneously connected to many different physical transports, e.g., Ethernet, Infiniband, shared memory, VME backplane, and wireless. By default, the middleware will use up to 4 transports to deliver data from a DataWriter to a DataReader.

This QosPolicy can be used to both limit and control which of the application’s available transports may be used by a DataWriter to send data or by a DataReader to receive data.

It includes the member in Table 6.63. For more information, please refer to the API Reference HTML documentation.

Table 6.63 DDS_TransportSelectionQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

DDS_StringSeq

enabled_transports

A sequence of aliases for the transports that may be used by the

DataWriter or DataReader.

 

 

 

 

 

Connext allows user to configure the transports that it uses to send and receive messages. A number of built-in transports, such as UDPv4 and shared memory, are available as well as

6-124

custom ones that the user may implement and install. Each transport will be installed in the

DomainParticipant with one or more aliases.

To enable a DataWriter or DataReader to use a particular transport, add the alias to the enabled_transports sequence of this QosPolicy. An empty sequence is a special case, and indicates that all transports installed in the DomainParticipant can be used by the DataWriter or

DataReader.

For more information on configuring and installing transports, please see the API Reference HTML documentation (from the Modules page, select “Connext API Reference, Pluggable Transports”).

6.5.22.1Example

Suppose a DomainParticipant has both UDPv4 and shared memory transports installed. If you want a particular DataWriter to publish its data only over shared memory, then you should use this QosPolicy to specify that restriction.

6.5.22.2Properties

This QosPolicy cannot be modified after the Entity is created. It can be set differently for the DataWriter and the DataReader.

6.5.22.3Related QosPolicies

TRANSPORT_UNICAST QosPolicy (DDS Extension) (Section 6.5.23)

TRANSPORT_MULTICAST QosPolicy (DDS Extension) (Section 7.6.5)

TRANSPORT_BUILTIN QosPolicy (DDS Extension) (Section 8.5.7)

6.5.22.4Applicable Entities

DataWriters (Section 6.3)

DataReaders (Section 7.3)

6.5.22.5System Resource Considerations

By restricting DataWriters from sending or DataReaders from receiving over certain transports, you may decrease the load on those transports.

6.5.23TRANSPORT_UNICAST QosPolicy (DDS Extension)

The TRANSPORT_UNICAST QosPolicy allows you to specify unicast network addresses to be used by DomainParticipant, DataWriters and DataReaders for receiving messages.

Connext may send data to a variety of Entities, not just DataReaders. DomainParticipants receive messages to support the discovery process discussed in Chapter 14. DataWriters may receive ACK/NACK messages to support the reliable protocol discussed in Chapter 10: Reliable Communications.

During discovery, each Entity announces to remote applications a list of (up to 4) unicast addresses to which the remote application should use send data (either user data packets or reliable protocol meta-data such as ACK/NACK and Heartbeats).

By default, the list of addresses is populated automatically with values obtained from the enabled transport plugins allowed to be used by the Entity (see the TRANSPORT_BUILTIN QosPolicy (DDS Extension) (Section 8.5.7) and TRANSPORT_SELECTION QosPolicy (DDS Extension) (Section 6.5.22)). Also, the associated ports are automatically determined (see Inbound Ports for User Traffic (Section 14.5.2)).

6-125

Use TRANSPORT_UNICAST QosPolicy to manually set the receive address list for an Entity. You may optionally set a port to use a non-default receive port as well. Only the first 4 addresses will be used. Connext will create a receive thread for every unique port number that it encounters (on a per transport basis).

The QosPolicy structure includes the members in Table 6.64. For more information and default values, please refer to the API Reference HTML documentation.

Table 6.64 DDS_TransportUnicastQosPolicy

 

Type

Field Name

Description

 

 

 

 

 

 

 

 

 

DDS_TransportUnicast

 

A sequence of up to 4 unicast settings that should be used by

 

SettingsSeq

value

 

remote entities to address messages to be sent to this Entity.

 

(see Table 6.65)

 

 

 

 

 

 

 

 

Table 6.65 DDS_TransportUnicastSettings_t

 

 

 

 

 

 

Type

Field Name

Description

 

 

 

 

 

 

 

 

 

DDS_StringSeq

transports

A sequence of transport aliases that specifies which transports

 

should be used to receive unicast messages for this Entity.

 

 

 

 

 

 

 

 

 

 

The port that should be used in the addressing of unicast

 

DDS_Long

receive_port

messages destined for this Entity. A value of 0 will cause

 

Connext to use a default port number based on domain and

 

 

 

 

 

 

participant ids. See Ports Used for Discovery (Section 14.5).

 

 

 

 

A message sent to a unicast address will be received by a single node on the network (as opposed to a multicast address where a single message may be received by multiple nodes). This policy sets the unicast addresses and ports that remote entities should use when sending messages to the Entity on which the TRANSPORT_UNICAST QosPolicy is set.

Up to four “return” unicast addresses may be configured for an Entity. Instead of specifying addresses directly, you use the transports field of the DDS_TransportUnicastSetting_t to select the transports (using their aliases) on which remote entities should send messages destined for this Entity. The addresses of the selected transports will be the “return” addresses. See the API Reference HTML documentation about configuring transports and aliases (from the Modules page, select “API Reference, Pluggable Transports”).

Note, a single transport may have more than one unicast address. For example, if a node has multiple network interface cards (NICs), then the UDPv4 transport will have an address for each NIC. When using the TRANSPORT_UNICAST QosPolicy to set the return addresses, a single value for the DDS_TransportUnicastSettingsSeq may provide more than the four return addresses that Connext currently uses.

Whether or not you are able to configure the network interfaces that are allowed to be used by a transport is up to the implementation the transport. For the built-in UDPv4 transport, you may restrict an instance of the transport to use a subset of the available network interfaces. See the API Reference HTML documentation for the built-in UDPv4 transport for more information.

For a DomainParticipant, this QoS policy sets the default list of addresses used by other applications to send user data for local DataReaders.

For a reliable DataWriter, if set, the other applications will use the specified list of addresses to send reliable protocol packets (ACKS/NACKS) on the behalf of reliable DataReaders. Otherwise, if not set, the other applications will use the addresses set by the DomainParticipant.

For a DataReader, if set, then other applications will use the specified list of addresses to send user data (and reliable protocol packets for reliable DataReaders). Otherwise, if not set, the other applications will use the addresses set by the DomainParticipant.

For a DataReader, if the port number specified by this QoS is the same as a port number specified by a TRANSPORT_MULTICAST QoS, then the transport may choose to process data received

6-126

both via multicast and unicast with a single thread. Whether or not a transport must use different threads to process data received via multicast or unicast for the same port number depends on the implementation of the transport.

To use this QosPolicy, you also need to specify a port number. A port number of 0 will cause Connext to automatically use a default value. As explained in Ports Used for Discovery (Section 14.5), the default port number for unicast addresses is based on the domain and participant IDs. Should you choose to use a different port number, then for every unique port number used by Entities in your application, depending on the transport, Connext may create a thread to process messages received for that port on that transport. See Chapter 19: Connext Threading Model for more about threads.

Threads are created on a per-transport basis, so if this QosPolicy specifies multiple transports for a receive_port, then a thread may be created for each transport for that unique port. Some transports may be able to share a single thread for different ports, others can not. Different Entities can share the same port number, and thus, the same thread will process all of the data for all of the Entities sharing the same port number for a transport.

Note: If a DataWriter is using the MULTI_CHANNEL QosPolicy (DDS Extension) (Section 6.5.14), the unicast addresses specified in the TRANSPORT_UNICAST QosPolicy are ignored by that DataWriter. The DataWriter will not publish samples on those locators.

6.5.23.1Example

You may use this QosPolicy to restrict an Entity from receiving data through a particular transport. For example, on a multi-NIC (network interface card) system, you may install different transports for different NICs. Then you can balance the network load between network cards by using different values for the TRANSPORT_UNICAST QosPolicy for different DataReaders. Thus some DataReaders will receive their data from one NIC and other DataReaders will receive their data from another.

6.5.23.2Properties

This QosPolicy cannot be modified after the Entity is created.

It can be set differently for the DomainParticipant, the DataWriter and the DataReader.

6.5.23.3Related QosPolicies

MULTI_CHANNEL QosPolicy (DDS Extension) (Section 6.5.14)

TRANSPORT_SELECTION QosPolicy (DDS Extension) (Section 6.5.22)

TRANSPORT_MULTICAST QosPolicy (DDS Extension) (Section 7.6.5)

TRANSPORT_BUILTIN QosPolicy (DDS Extension) (Section 8.5.7)

6.5.23.4Applicable Entities

DomainParticipants (Section 8.3)

DataWriters (Section 6.3)

DataReaders (Section 7.3)

6.5.23.5System Resource Considerations

Because this QosPolicy changes the transports on which messages are received for different Entities, the bandwidth used on the different transports may be affected.

Depending on the implementation of a transport, Connext may need to create threads to receive and process data on a unique-port-number basis. Some transports can share the same thread to process data received for different ports; others like UDPv4 must have different threads for different ports. In addition, if the same port is used for both unicast and multicast, the transport

6-127

implementation will determine whether or not the same thread can be used to process both unicast and multicast data. For UDPv4, only one thread is needed per port–independent of whether the data was received via unicast or multicast data. See Receive Threads (Section 19.3) for more information.

6.5.24TYPESUPPORT QosPolicy (DDS Extension)

This policy can be used to modify the rtiddsgen-generated code so that the de/serialization routines act differently depending on the information passed in via the object pointer.

RTI generally recommends that users treat generated source files as compiler outputs (analogous to object files) and that users not modify them. RTI cannot support user changes to generated source files. Furthermore, such changes would make upgrading to newer versions of Connext more difficult, as this generated code is considered to be a part of the middleware implementation and consequently does change from version to version. This QoS policy should be considered a back door, only to be used after careful design consideration, testing, and consultation with your RTI representative.

It includes the members in Table 6.66.

Table 6.66 DDS_TypeSupportQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

void *

plugin_data

Value to pass into the type plug-in's serialization/deserialization function.

 

 

 

6.5.24.1Properties

This QoS policy may be modified after the DataWriter or DataReader is enabled. It can be set differently for the DataWriter and DataReader.

6.5.24.2Related QoS Policies

None.

6.5.24.3Applicable Entities

DataWriters (Section 6.3)

DataReaders (Section 7.3)

DomainParticipants (Section 8.3)

6.5.24.4System Resource Considerations

None.

6.5.25USER_DATA QosPolicy

This QosPolicy provides an area where your application can store additional information related to a DomainParticipant, DataWriter, or DataReader. This information is passed between applications during discovery (see Chapter 14: Discovery) using built-in-topics (see Chapter 16: Built-In Topics). How this information is used will be up to user code. Connext does not do anything with the information stored as USER_DATA except to pass it to other applications.

Use cases are usually for application-to-application identification, authentication, authorization, and encryption purposes. For example, applications can use Group or User Data to send security certificates to each other for RSA-type security.

The value of the USER_DATA QosPolicy is sent to remote applications when they are first discovered, as well as when the DomainParticipant, DataWriter or DataReader’s set_qos() methods are called after changing the value of the USER_DATA. User code can set listeners on

6-128

the built-in DataReaders of the built-in Topics used by Connext to propagate discovery information. Methods in the built-in topic listeners will be called whenever new DomainParticipants, DataReaders, and DataWriters are found. Within the user callback, you will have access to the USER_DATA that was set for the associated Entity.

Currently, USER_DATA of the associated Entity is only propagated with the information that declares a DomainParticipant, DataWriter or DataReader. Thus, you will need to access the value of USER_DATA through DDS_ParticipantBuiltinTopicData, DDS_PublicationBuiltinTopicData or DDS_SubscriptionBuiltinTopicData (see Chapter 16: Built-In Topics).

The structure for the USER_DATA QosPolicy includes just one field, as seen in Table 6.67. The field is a sequence of octets that translates to a contiguous buffer of bytes whose contents and length is set by the user. The maximum size for the data are set in the DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4).

Table 6.67 DDS_UserDataQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

DDS_OctetSeq

value

Default: empty

 

 

 

This policy is similar to the GROUP_DATA QosPolicy (Section 6.4.4) and TOPIC_DATA QosPolicy (Section 5.2.1) that apply to other types of Entities.

6.5.25.1Example

One possible use of USER_DATA is to pass some credential or certificate that your subscriber application can use to accept or reject communication with the DataWriters (or vice versa, where the publisher application can validate the permission of DataReaders to receive its data). Using the same method, an application (DomainParticipant) can accept or reject all connections from another application. The value of the USER_DATA of the DomainParticipant is propagated in the ‘user_data’ field of the DDS_ParticipantBuiltinTopicData that is sent with the declaration of each DomainParticipant. Similarly, the value of the USER_DATA of the DataWriter is propagated in the ‘user_data’ field of the DDS_PublicationBuiltinTopicData that is sent with the declaration of each DataWriter, and the value of the USER_DATA of the DataReader is propagated in the ‘user_data’ field of the DDS_SubscriptionBuiltinTopicData that is sent with the declaration of each DataReader.

When Connext discovers a DomainParticipant/DataWriter/DataReader, the application can be notified of the discovery of the new entity and retrieve information about the Entity’s QoS by reading the DCPSParticipant, DCPSPublication or DCPSSubscription built-in topics (see Chapter 16: Built-In Topics). The user application can then examine the USER_DATA field in the built-in Topic and decide whether or not the remote Entity should be allowed to communicate with the local Entity. If communication is not allowed, the application can use the

DomainParticipant’s ignore_participant(), ignore_publication() or ignore_subscription() operation to reject the newly discovered remote entity as one with which the application allows Connext to communicate. See Figure 16.2 for an example of how to do this.

6.5.25.2Properties

This QosPolicy can be modified at any time. A change in the QosPolicy will cause Connext to send packets containing the new USER_DATA to all of the other applications in the domain.

It can be set differently on the publishing and subscribing sides.

6.5.25.3Related QosPolicies

TOPIC_DATA QosPolicy (Section 5.2.1)

GROUP_DATA QosPolicy (Section 6.4.4)

6-129

DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4)

6.5.25.4Applicable Entities

DataWriters (Section 6.3)

DataReaders (Section 7.3)

DomainParticipants (Section 8.3)

6.5.25.5System Resource Considerations

As mentioned earlier, the maximum size of the USER_DATA is set in the participant_user_data_max_length, writer_user_data_max_length, and reader_user_data_max_length fields of the DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4). Because Connext will allocated memory based on this value, you should only increase this value if you need to. If your system does not use USER_DATA, then you can set this value to 0 to save memory. Setting the value of the USER_DATA QosPolicy to hold data longer than the value set in the

[participant,writer,reader]_user_data_max_length field will result in failure and an INCONSISTENT_QOS_POLICY return code.

However, should you decide to change the maximum size of USER_DATA, you must make certain that all applications in the domain have changed the value of

[participant,writer,reader]_user_data_max_length to be the same. If two applications have different limits on the size of USER_DATA, and one application sets the USER_DATA QosPolicy to hold data that is greater than the maximum size set by another application, then the DataWriters and DataReaders between the two applications will not connect. The DomainParticipants may also reject connections from each other entirely. This is also true for the GROUP_DATA (Section 6.4.4) and TOPIC_DATA (Section 5.2.1) QosPolicies.

6.5.26WRITER_DATA_LIFECYCLE QoS Policy

This QoS policy controls how a DataWriter handles the lifecycle of the instances (keys) that the DataWriter is registered to manage. This QoS policy includes the members in Table 6.68.

Table 6.68 DDS_WriterDataLifecycleQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

autodispose_unregistered_

RTI_TRUE (default): instance is disposed when

DDS_Boolean

unregistered.

 

instances

RTI_FALSE: instance is not disposed when unregistered.

 

 

 

 

 

 

 

Determines how long the DataWriter will maintain

 

 

information regarding an instance that has been

struct

autopurge_unregistered_in

unregistered.

DDS_Duration_t

stance_delay

After this time elapses, the DataWriter will purge all

 

 

internal information regarding the instance, including

 

 

historical samples.

 

 

 

You may use the DataWriter’s unregister() operation to indicate that the DataWriter no longer wants to send data for a Topic. This QoS controls whether or not Connext automatically also calls dispose() on the behalf of the DataWriter for the data.

The behavior controlled by this QoS applies on a per instance (key) basis for keyed Topics, so that when a DataWriter unregisters an instance, Connext can automatically also dispose that instance. This is the default behavior.

In many cases where the ownership of a Topic is EXCLUSIVE (see the OWNERSHIP QosPolicy (Section 6.5.15)), DataWriters may want to relinquish ownership of a particular instance of the

6-130

Topic to allow other DataWriters to send updates for the value of that instance. In that case, you may only want a DataWriter to unregister an instance without disposing the instance. Disposing an instance implies that the DataWriter no longer owns that instance, but it is a stronger statement to say that instance no longer exists.

User applications may be coded to trigger on the disposal of instances, thus the ability to unregister without disposing may be useful to properly maintain the semantic of disposal.

When a DataWriter unregisters an instance, it means that this particular DataWriter has no more information/data on this instance. When an instance is disposed, it means that the instance is "dead"—there will no more information/data from any DataWriter on this instance.

Setting autopurge_unregistered_instances to TRUE provides the same behavior as explicitly calling one of the dispose() operations (Section 6.3.14.2) on the instance before calling unregister() (Section 6.3.14.1), provided that autodispose_unregistered_instances is set to TRUE (the default).

When you delete a DataWriter (Section 6.3.1), all of the instances managed by the DataWriter are automatically unregistered. Therefore, this QoS policy determines whether or not instances are disposed when the DataWriter is deleted by calling one of these operations:

Publisher’s delete_datawriter() (see Section 6.3.1)

Publisher’s delete_contained_entities() (see Section 6.2.3.1)

DomainParticipant’s delete_contained_entities() (see Section 8.3.3)

When autopurge_unregistered_instances is TRUE, the middleware will clean up all the resources associated with an unregistered instance (most notably, the sample history of non- volatile DataWriters) when all the instance’s samples have been acknowledged by all its live DataReaders, including the sample that indicates the unregistration. By default, autopurge_unregistered_instance_delay is disabled (the delay is INFINITE). If the delay is set to zero, the DataWriter will clean up as soon as all the samples are acknowledged after the call to unregister(). A non-zero value for the delay can be useful in two ways:

1.To keep the historical samples for late-joiners for a period of time.

2.In the context of discovery, if the applications temporarily lose the connection before the unregistration (which represents the remote entity destruction), to provide the samples that indicate the dispose and unregister actions once the connection is reestablished.

This delay can also be set for discovery data through these fields in the DISCOVERY_CONFIG QosPolicy (DDS Extension) (Section 8.5.3):

publication_writer_data_lifecycle.autopurge_unregistered_instances_delay

subscription_writer_data_lifecycle.autopurge_unregistered_instances_delay

6.5.26.1Properties

It does not apply to DataReaders, so there is no requirement that the publishing and subscribing sides use compatible values.

This QoS policy may be modified after the DataWriter is enabled.

6.5.26.2Related QoS Policies

None.

6.5.26.3Applicable Entities

DataWriters (Section 6.3)

6-131

6.5.26.4System Resource Considerations

None.

6.6FlowControllers (DDS Extension)

Note: This section does not apply when using the separate add-on product, Ada 2005 Language Support, which does not support FlowControllers.

A FlowController is the object responsible for shaping the network traffic by determining when attached asynchronous DataWriters are allowed to write data.

You can use one of the built-in FlowControllers (and optionally modify their properties), create a custom FlowController by using the DomainParticipant’s create_flowcontroller() operation (see Section 6.6.6), or create a custom FlowController by using the DomainParticipant's PROPERTY QosPolicy (DDS Extension) (Section 6.5.17); see Creating and Configuring Custom FlowControllers with Property QoS (Section 6.6.5).

To use a FlowController, you provide its name in the DataWriter’s PUBLISH_MODE QosPolicy (DDS Extension) (Section 6.5.18).

DDS_DEFAULT_FLOW_CONTROLLER_NAME

By default, flow control is disabled. That is, the built-in DDS_DEFAULT_FLOW_CONTROLLER_NAME flow controller does not apply any flow control. Instead, it allows data to be sent asynchronously as soon as it is written by the DataWriter.

DDS_FIXED_RATE_FLOW_CONTROLLER_NAME

The FIXED_RATE flow controller shapes the network traffic by allowing data to be sent only once every second. Any accumulated samples destined for the same destination are coalesced into as few network packets as possible.

DDS_ON_DEMAND_FLOW_CONTROLLER_NAME

The ON_DEMAND flow controller allows data to be sent only when you call the FlowController’s trigger_flow() operation. With each trigger, all accumulated data since the previous trigger is sent (across all Publishers or DataWriters). In other words, the network traffic shape is fully controlled by the user. Any accumulated samples destined for the same destination are coalesced into as few network packets as possible.

This external trigger source is ideal for users who want to implement some form of closed-loop flow control or who want to only put data on the wire every so many samples (e.g., with the number of samples based on NDDS_Transport_Property_t’s gather_send_buffer_count_max).

The default property settings for the built-in FlowControllers are described in the API Reference HTML documentation.

Samples written by an asynchronous DataWriter are not sent in the context of the write() call. Instead, Connext puts the samples in a queue for future processing. The FlowController associated with each asynchronous DataWriter determines when the samples are actually sent.

Each FlowController maintains a separate FIFO queue for each unique destination (remote application). Samples written by asynchronous DataWriters associated with the FlowController are placed in the queues that correspond to the intended destinations of the sample.

When tokens become available, a FlowController must decide which queue(s) to grant tokens first. This is determined by the FlowController's scheduling_policy property (see Table 6.69). Once a queue has been granted tokens, it is serviced by the asynchronous publishing thread.

6-132

The queued up samples will be coalesced and sent to the corresponding destination. The number of samples sent depends on the data size and the number of tokens granted.

Table 6.69 lists the properties for a FlowController.

Table 6.69 DDS_FlowControllerProperty_t

Type

Field Name

Description

 

 

 

 

 

 

DDS_FlowControllerSchedulingPolicy

scheduling_

Round robin, earliest deadline first, or

policy

highest priority first. See Section 6.6.1.

 

 

 

 

DDS_FlowControllerTokenBucketProperty_t

token_bucket

See Section 6.6.3.

 

 

 

Table 6.70 lists the operations available for a FlowController.

Table 6.70 FlowController Operations

Operation

Description

Reference

 

 

 

 

 

 

get_property

Get and Set the FlowController properties.

Section 6.6.8

 

set_property

 

 

 

 

 

trigger_flow

Provides an external trigger to the FlowController.

Section 6.6.9

 

 

 

get_name

Returns the name of the FlowController.

Section 6.6.10

 

 

get_participant

Returns the DomainParticipant to which the FlowController belongs.

 

 

 

 

6.6.1Flow Controller Scheduling Policies

Round Robin (DDS_RR_FLOW_CONTROLLER_SCHED_POLICY) Perform flow control in a round-robin (RR) fashion.

Whenever tokens become available, the FlowController distributes the tokens uniformly across all of its (non-empty) destination queues. No destinations are prioritized. Instead, all destinations are treated equally and are serviced in a round-robin fashion.

Earliest Deadline First (DDS_EDF_FLOW_CONTROLLER_SCHED_POLICY) Perform flow control in an earliest-deadline-first (EDF) fashion.

A sample's deadline is determined by the time it was written plus the latency budget of the DataWriter at the time of the write call (as specified in the DDS_LatencyBudgetQosPolicy). The relative priority of a flow controller's destination queue is determined by the earliest deadline across all samples it contains.

When tokens become available, the FlowController distributes tokens to the destination queues in order of their priority. In other words, the queue containing the sample with the earliest deadline is serviced first. The number of tokens granted equals the number of tokens required to send the first sample in the queue. Note that the priority of a queue may change as samples are sent (i.e., removed from the queue). If a sample must be sent to multiple destinations or two samples have an equal deadline value, the corresponding destination queues are serviced in a round-robin fashion.

With the default duration of 0 in the LatencyBudgetQosPolicy, using an EDF_FLOW_CONTROLLER_SCHED_POLICY FlowController preserves the order in which you call write() across the DataWriters associated with the FlowController.

Since the LatencyBudgetQosPolicy is mutable, a sample written second may contain an earlier deadline than the sample written first if the DDS_LatencyBudgetQosPolicy’s duration is sufficiently decreased in between writing the two samples. In that case, if the first sample is not yet written (still in queue waiting for its turn), it inherits the priority corresponding to the (earlier) deadline from the second sample.

6-133

In other words, the priority of a destination queue is always determined by the earliest deadline among all samples contained in the queue. This priority inheritance approach is required in order to both honor the updated duration and to adhere to the DataWriter in- order data delivery guarantee.

Highest Priority First (DDS_HPF_FLOW_CONTROLLER_SCHED_POLICY) Perform flow control in an highest-priority-first (HPF) fashion.

Note: Prioritized samples are not supported when using the Java, Ada, or .NET APIs. Therefore the Highest Priority First scheduling policy is not supported when using these APIs.

The next destination queue to service is determined by the publication priority of the DataWriter, the channel of a multi-channel DataWriter, or individual sample.

The relative priority of a flow controller's destination queue is determined by the highest publication priority of all the samples it contains.

When tokens become available, the FlowController distributes tokens to the destination queues in order of their publication priority. The queue containing the sample with the highest publication priority is serviced first. The number of tokens granted equals the number of tokens required to send the first sample in the queue. Note that a queue’s priority may change as samples are sent (i.e., as they are removed from the queue). If a sample must be sent to multiple destinations or two samples have the same publication priority, the corresponding destination queues are serviced in a round-robin fashion.

This priority inheritance approach is required to both honor the designated publication priority and adhere to the DataWriter’s in-order data delivery guarantee.

See also: Prioritized Samples (Section 6.6.4).

6.6.2Managing Fast DataWriters When Using a FlowController

If a DataWriter is writing samples faster than its attached FlowController can throttle, Connext may drop samples on the writer’s side. This happens because the samples may be removed from the queue before the asynchronous publisher’s thread has a chance to send them. To work around this problem, either:

Use reliable communication to block the write() call and thereby throttle your application.

Do not allow the queue to fill up in the first place.

The queue should be sized large enough to handle expected write bursts, so that no samples are dropped. Then in steady state, the FlowController will smooth out these bursts and the queue will ideally have only one entry.

6.6.3Token Bucket Properties

FlowControllers use a token-bucket approach for open-loop network flow control. The flow control characteristics are determined by the token bucket properties. The properties are listed in Table 6.71; see the API Reference HTML documentation for their defaults and valid ranges.

Table 6.71 DDS_FlowControllerTokenBucketProperty_t

Type

Field Name

Description

 

 

 

 

 

 

DDS_Long

max_tokens

Maximum number of tokens than can accumulate in the

token bucket. See Section 6.6.3.1.

 

 

 

 

 

DDS_Long

tokens_added_per_period

The number of tokens added to the token bucket per

 

 

specified period. See Section 6.6.3.2.

6-134

Table 6.71 DDS_FlowControllerTokenBucketProperty_t

Type

Field Name

Description

 

 

 

 

 

 

DDS_Long

tokens_leaked_per_period

The number of tokens removed from the token bucket per

specified period. See Section 6.6.3.3.

 

 

 

DDS_Duration_t

period

Period for adding tokens to and removing tokens from

the bucket. See Section 6.6.3.4.

 

 

 

 

 

DDS_Long

bytes_per_token

Maximum number of bytes allowed to send for each

token available. See Section 6.6.3.5.

 

 

 

 

 

Asynchronously published samples are queued up and transmitted based on the token bucket flow control scheme. The token bucket contains tokens, each of which represents a number of bytes. Samples can be sent only when there are sufficient tokens in the bucket. As samples are sent, tokens are consumed. The number of tokens consumed is proportional to the size of the data being sent. Tokens are replenished on a periodic basis.

The rate at which tokens become available and other token bucket properties determine the network traffic flow.

Note that if the same sample must be sent to multiple destinations, separate tokens are required for each destination. Only when multiple samples are destined to the same destination will they be coalesced and sent using the same token(s). In other words, each token can only contribute to a single network packet.

6.6.3.1max_tokens

The maximum number of tokens in the bucket will never exceed this value. Any excess tokens are discarded. This property value, combined with bytes_per_token, determines the maximum allowable data burst.

Use DDS_LENGTH_UNLIMITED to allow accumulation of an unlimited amount of tokens (and therefore potentially an unlimited burst size).

6.6.3.2tokens_added_per_period

A FlowController transmits data only when tokens are available. Tokens are periodically replenished. This field determines the number of tokens added to the token bucket with each periodic replenishment.

Available tokens are distributed to associated DataWriters based on the scheduling_policy. Use DDS_LENGTH_UNLIMITED to add the maximum number of tokens allowed by max_tokens.

6.6.3.3tokens_leaked_per_period

When tokens are replenished and there are sufficient tokens to send all samples in the queue, this property determines whether any or all of the leftover tokens remain in the bucket.

Use DDS_LENGTH_UNLIMITED to remove all excess tokens from the token bucket once all samples have been sent. In other words, no token accumulation is allowed. When new samples are written after tokens were purged, the earliest point in time at which they can be sent is at the next periodic replenishment.

6.6.3.4period

This field determines the period by which tokens are added or removed from the token bucket.

The special value DDS_DURATION_INFINITE can be used to create an on-demand FlowController, for which tokens are no longer replenished periodically. Instead, tokens must be added explicitly by calling the FlowController’s trigger_flow() operation. This external trigger adds tokens_added_per_period tokens each time it is called (subject to the other property settings).

6-135

Note: Once period is set to DDS_DURATION_INFINITE, it can no longer be reverted to a finite period.

6.6.3.5bytes_per_token

This field determines the number of bytes that can actually be transmitted based on the number of tokens.

Tokens are always consumed in whole by each DataWriter. That is, in cases where bytes_per_token is greater than the sample size, multiple samples may be sent to the same destination using a single token (regardless of the scheduling_policy).

Where fragmentation is required, the fragment size will be either (a) bytes_per_token or (b) the minimum of the largest message sizes across all transports installed with the DataWriter, whichever is less.

Use DDS_LENGTH_UNLIMITED to indicate that an unlimited number of bytes can be transmitted per token. In other words, a single token allows the recipient DataWriter to transmit all its queued samples to a single destination. A separate token is required to send to each additional destination.

6.6.4Prioritized Samples

Note: This feature is not supported when using the Java, Ada, or .NET APIs.

The Prioritized Samples feature allows you to prioritize traffic that is in competition for transmission resources. The granularity of this prioritization may be by DataWriter, by instance, or by individual sample.

Prioritized Samples can improve latency in the following cases:

Low-Availability Links

With low-availability communication, unsent samples may accumulate while the link is unavailable. When the link is restored, a large number of samples may be waiting for transmission. High priority samples will be sent first.

Low-Bandwidth Links

With low-bandwidth communication, a temporary backlog may occur or the link may become congested with large samples. High-priority samples will be sent at the first available gap, between the fragments of a large low-priority sample.

Prioritized Topics

With limited bandwidth communication, some topics may be deemed to be of higher priority than others on an ongoing basis, and samples written to some topics should be given precedence over others on transmission.

High Priority Events

Due to external rules or content analysis (e.g., perimeter violation or identification as a threat), the priority of samples is dynamically determined, and the priority assigned a given sample will reflect the urgency of its delivery.

To configure a DataWriter to use prioritized samples:

Create a FlowController with the scheduling_policy property set to

DDS_HPF_FLOW_CONTROLLER_SCHED_POLICY.

Create a DataWriter with the PUBLISH_MODE QosPolicy (DDS Extension) (Section 6.5.18) kind set to ASYNCHRONOUS and flow_controller_name set to the name of the FlowController.

A single FlowController may perform traffic shaping for multiple DataWriters and multiple DataWriter channels. The FlowController’s configuration determines how often publication

6-136

resources are scheduled, how much data may be sent per period, and other transmission characteristics that determine the ultimate performance of prioritized samples.

When working with prioritized samples, you should use these operations, which allow you to specify priority:

write_w_params() (see Writing Data (Section 6.3.8))

unregister_instance_w_params() (see Registering and Unregistering Instances (Section 6.3.14.1))

dispose_w_params() (see Disposing of Data (Section 6.3.14.2))

If you use write(), unregister(), or dispose() instead of the _w_params() versions, the affected sample is assigned priority 0 (undefined priority). If you are using a multi-channel DataWriter with a priority filter, and you have no channel for priority 0, the sample will be discarded.

6.6.4.1Designating Priorities

For DataWriters and DataWriter channels, valid publication priority values are:

DDS_PUBLICATION_PRIORITY_UNDEFINED

DDS_PUBLICATION_PRIORITY_AUTOMATIC

Positive integers excluding zero

For individual samples, valid publication priority values are 0 and positive integers.

There are three ways to set the publication priority of a DataWriter or DataWriter channel:

1.For a DataWriter, publication priority is set in the priority field of its PUBLISH_MODE QosPolicy (DDS Extension) (Section 6.5.18). For a multi-channel DataWriter (see MULTI_CHANNEL QosPolicy (DDS Extension) (Section 6.5.14)), this value will be the default publication priority for any member channel that has not been assigned a specific value.

2.For a channel of a Multi-channel DataWriter, publication priority can be set in the DataWriter’s MULTI_CHANNEL QosPolicy (DDS Extension) (Section 6.5.14) in channels[].priority.

3.If a DataWriter or a channel of a Multi-channel DataWriter is configured for publication priority inheritance (DDS_PUBLICATION_PRIORITY_AUTOMATIC), its publication priority is the highest priority among all the samples currently in the publication queue. When using publication priority inheritance, the publication priorities of individual samples are set by calling the write_w_params() operation, which takes a priority parameter.

The effective publication priority is determined from the interaction of the DataWriter, channel, and sample publication priorities, as shown in Table 6.72.

6.6.4.2Priority-Based Filtering

The configuration methods explained above are sufficient to create multiple DataWriters, each with its own assigned priority, all using the same FlowController configured for publication priority-based scheduling. Such a configuration is sufficient to assign different priorities to individual topics, but it does not allow different publication priorities to be assigned to published data within a Topic.

To assign different priorities to data within a DataWriter, you will need to use a Multi-channel DataWriter and configure the channels with different priorities. Configuring the publication priorities of DataWriter channels is explained above. To associate different priorities of data with different publication channels, configure the channel[].filter_expression in the DataWriter’s MULTI_CHANNEL QosPolicy (DDS Extension) (Section 6.5.14). The filtering criteria that is available for evaluation by each channel is determined by the filter type, which is configured

6-137

Table 6.72 Effective Publication Priority of

 

 

 

Priority Setting Combinations

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Designated

Writer Priority

 

Undefined

Don’t care

AUTOMATIC

Don’t care

positive

 

 

 

 

 

 

integer > 0

 

 

 

 

 

 

 

 

 

 

 

 

Designated

 

Channel Priority

 

Undefined

AUTOMATIC

Undefined

positive

Undefined

 

 

 

 

 

integer > 0

 

 

 

 

 

 

 

 

 

 

 

Designated

Designated

 

 

Sample Priority

 

Don’t care

positive

positive

Don’t care

Don’t care

 

 

 

integer > 0

integer > 0

 

 

 

 

 

 

 

 

 

Effective Priority

 

Lowest

Sample

Sample

Channel

Writer

 

Priority

Prioritya

Prioritya

Priority

Priority

a. Highest sample priority among all samples currently in the publication queue.

with the DataWriter’s filter_name (also in the MULTI_CHANNEL QosPolicy (DDS Extension) (Section 6.5.14)).

For example, using the built-in SQL-based content filter allows channel membership to be determined based on the content of each sample.

If you do not want to embed priority criteria within each sample, you can use a built-in filter named DDS_PRIFILTER_NAME that uses the publication priority that is provided when you call write_w_params() (see Writing Data (Section 6.3.8)). The filter’s expression syntax is:

@priority OP VAL

where OP can be < , <= , > , >= , = , or <> (standard relational operators), and VAL is a positive integer.

The filter supports multiple expressions, combined with the conjunctions AND and OR. You can use parentheses to disambiguate combinations of AND and OR in the same expression. For example:

@priority = 2 OR (@priority > 6 AND @priority < 10)

6.6.5Creating and Configuring Custom FlowControllers with Property QoS

You can create and configure FlowControllers using the PROPERTY QosPolicy (DDS Extension) (Section 6.5.17). The properties must have a prefix of “dds.flow_controller.token_bucket”, followed by the name of the FlowController being created or configured. For example, if you want to create/configure a FlowController named MyFC, all the properties for MyFC should have the prefix “dds.flow_controller.token_bucket.MyFC“.

Table 6.73 lists the properties that can be set for FlowControllers in the DomainParticipant's PROPERTY QosPolicy (DDS Extension) (Section 6.5.17). A FlowController with the name "dds.flow_controller.token_bucket.<your flow controllername>" will be implicitly created when at least one property using that prefix is specified. Then, to link a DataWriter to your FlowController, use "dds.flow_controller.token_bucket.<your flow controllername>" in the

DataWriter's publish_mode.flow_controller_name.

6.6.5.1Example

The following example shows how to set FlowController properties.

Note: Some lines in this example, such as dds.flow_controller.token_bucket.MyFlowController.scheduling_policy, are too long to fit on the page as one line; however in your XML file, they each need to be on a single line.

<participant_qos>

6-138

Table 6.73 FlowController Properties

Property Name

 

prefix with

Property Value Description

‘dds.flow_controller.token_bucket.

 

<your flow controller name>

 

 

 

 

 

 

Specifies the scheduling policy to be used. (See Flow

 

Controller Scheduling Policies (Section 6.6.1)) May be:

scheduling_policy

DDS_RR_FLOW_CONTROLLER_SCHED_POLICY

 

DDS_EDF_FLOW_CONTROLLER_SCHED_POLICY

 

DDS_HPF_FLOW_CONTROLLER_SCHED_POLICY

 

 

 

Maximum number of tokens than can accumulate in the token

token_bucket.max_tokens

bucket.

 

Use -1 for unlimited.

 

 

 

Number of tokens added to the token bucket per specified

token_bucket.tokens_added_per_period

period.

 

Use -1 for unlimited.

 

 

 

Number of tokens removed from the token bucket per

token_bucket.tokens_leaked_per_period

specified period.

 

Use -1 for unlimited.

 

 

token_bucket.period.sec

Period for adding tokens to and removing tokens from the

bucket in seconds.

 

 

 

token_bucket.period.nanosec

Period for adding tokens to and removing tokens from the

bucket in nanoseconds.

 

 

 

token_bucket.bytes_per_token

Maximum number of bytes allowed to send for each token

available.

 

 

 

<property>

<value>

<element>

<name> dds.flow_controller.token_bucket.MyFlowController. scheduling_policy

</name> <value>DDS_RR_FLOW_CONTROLLER_SCHED_POLICY</value>

</element>

<element>

<name> dds.flow_controller.token_bucket.MyFlowController. token_bucket.period.sec

</name>

<value>100</value>

</element>

<element>

<name> dds.flow_controller.token_bucket.MyFlowController. token_bucket.period.nanosec

</name>

<value>0</value>

</element>

<element>

<name> dds.flow_controller.token_bucket.MyFlowController. token_bucket.tokens_added_per_period

</name>

<value>2</value>

</element>

<element>

6-139

<name> dds.flow_controller.token_bucket.MyFlowController. token_bucket.tokens_leaked_per_period

</name>

<value>2</value>

</element>

<element>

<name> dds.flow_controller.token_bucket.MyFlowController. token_bucket.bytes_per_token

</name>

<value>1024</value>

</element>

</value>

</property> </participant_qos>

<datawriter_qos> <publish_mode>

<flow_controller_name> dds.flow_controller.token_bucket.MyFlowController

</flow_controller_name> <kind>ASYNCHRONOUS_PUBLISH_MODE_QOS</kind>

</publish_mode> </datawriter_qos>

6.6.6Creating and Deleting FlowControllers

If you do not want to use one of the three built-in FlowControllers described in FlowControllers (DDS Extension) (Section 6.6), you can create your own with the DomainParticipant’s create_flowcontroller() operation:

DDSFlowController* create_flowcontroller (const char * name,

const DDS_FlowControllerProperty_t & property)

To associate a FlowController with a DataWriter, you set the FlowController’s name in the PUBLISH_MODE QosPolicy (DDS Extension) (Section 6.5.18) (flow_controller_name).

A single FlowController may service multiple DataWriters, even if they belong to a different Publisher. The FlowController’s property structure determines how the FlowController shapes the network traffic.

name name of the FlowController to create. A DataWriter is associated with a DDSFlowCon- troller by name. Limited to 255 characters.

property Properties to be used for creating the FlowController. The special value DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT can be used to indicate that the FlowController should be created with the default DDS_FlowControllerProperty_t set in the DomainParticipant.

Note: If you use DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT, it is not safe to cre- ate the flow controller while another thread may be simultaneously calling set_default_flowcontroller_property() or looking for that flow controller with lookup_flowcontroller().

To delete an existing FlowController, use the DomainParticipant’s delete_flowcontroller() operation:

DDS_ReturnCode_t delete_flowcontroller (DDSFlowController * fc)

6-140

The FlowController must belong this the DomainParticipant and not have any attached DataWriters or the delete call will return an error (PRECONDITION_NOT_MET).

6.6.7Getting/Setting Default FlowController Properties

To get the default DDS_FlowControllerProperty_t values, use this operation on the

DomainParticipant:

DDS_ReturnCode_t get_default_flowcontroller_property (DDS_FlowControllerProperty_t & property)

The retrieved property will match the set of values specified on the last successful call to the

DomainParticipant’s set_default_flowcontroller_property(), or if the call was never made, the default values listed in DDS_FlowControllerProperty_t.

To change the default DDS_FlowControllerProperty_t values used when a new FlowController is created, use this operation on the DomainParticipant:

DDS_ReturnCode_t set_default_flowcontroller_property

(const DDS_FlowControllerProperty_t & property)

The special value DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT may be passed for the property to indicate that the default property should be reset to the default values the factory would use if set_default_flowcontroller_property() had never been called.

Note: It is not safe to set the default FlowController properties while another thread may be simultaneously calling get_default_flowcontroller_property(), set_default_flowcontroller_property(), or create_flowcontroller() with DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT as the qos parameter. It is also not safe to get the default FlowController properties while another thread may be simultaneously calling get_default_flowcontroller_property().

6.6.8Getting/Setting Properties for a Specific FlowController

To get the properties of a FlowController, use the FlowController’s get_property() operation:

DDS_ReturnCode_t DDSFlowController::get_property

(struct DDS_FlowControllerProperty_t & property)

To change the properties of a FlowController, use the FlowController’s set_property() operation:

DDS_ReturnCode_t DDSFlowController::set_property

(const struct DDS_FlowControllerProperty_t & property)

Once a FlowController has been instantiated, only its token_bucket property can be changed. The scheduling_policy is immutable. A new token.period only takes effect at the next scheduled token distribution time (as determined by its previous value).

The special value DDS_FLOW_CONTROLLER_PROPERTY_DEFAULT can be used to match the current default properties set in the DomainParticipant.

6-141

6.6.9Adding an External Trigger

Typically, a FlowController uses an internal trigger to periodically replenish its tokens. The period by which this trigger is called is determined by the period property setting.

The trigger_flow() function provides an additional, external trigger to the FlowController. This trigger adds tokens_added_per_period tokens each time it is called (subject to the other property settings of the FlowController).

DDS_ReturnCode_t trigger_flow ()

An on-demand FlowController can be created with a DDS_DURATION_INFINITE as period, in which case the only trigger source is external (i.e. the FlowController is solely triggered by the user on demand).

trigger_flow() can be called on both a strict on-demand FlowController and a hybrid FlowController (internally and externally triggered).

6.6.10Other FlowController Operations

If you have the FlowController object and need its name, call the FlowController’s get_name() operation:

const char* DDSFlowController::get_name( )

Conversely, if you have the name of the FlowController and need the FlowController object, call the DomainPartipant’s lookup_flowcontroller() operation:

DDSFlowController* lookup_flowcontroller (const char * name)

To get a FlowController’s DomainParticipant, call the FlowController’s get_participant() operation:

DDSDomainParticipant* get_participant ( )

Note: It is not safe to lookup a FlowController description while another thread is creating that FlowController

6-142

Chapter 7 Receiving Data

This chapter discusses how to create, configure, and use Subscribers and DataReaders to receive data. It describes how these objects interact, as well as the types of operations that are available for them.

This chapter includes the following sections:

Preview: Steps to Receiving Data (Section 7.1)

Subscribers (Section 7.2)

DataReaders (Section 7.3)

Using DataReaders to Access Data (Read & Take) (Section 7.4)

Subscriber QosPolicies (Section 7.5)

DataReader QosPolicies (Section 7.6)

The goal of this chapter is to help you become familiar with the Entities you need for receiving data. For up-to-date details such as formal parameters and return codes on any mentioned operations, please see the Connext API Reference HTML documentation.

7.1Preview: Steps to Receiving Data

There are three ways to receive data:

Your application can explicitly check for new data by calling a DataReader’s read() or take() method. This method is also known as polling for data.

Your application can be notified asynchronously whenever new data samples arrive— this is done with a Listener on either the Subscriber or the DataReader. Connext will invoke the Listener’s callback routine when there is new data. Within the callback routine, user code can access the data by calling read() or take() on the DataReader. This method is the way for your application to receive data with the least amount of latency.

Your application can wait for new data by using Conditions and a WaitSet, then calling wait(). Connext will block your application’s thread until the criteria (such as the arrival of samples, or a specific status) set in the Condition becomes true. Then your application resumes and can access the data with read() or take().

The DataReader’s read() operation gives your application a copy of the data and leaves the data in the DataReader’s receive queue. The DataReader’s take() operation removes data from the receive queue before giving it to your application.

7-1

See Section 7.4 for details on using DataReaders to access received data.

See Section 4.6 for details on using Conditions and WaitSets.

To prepare to receive data, create and configure the required Entities:

1.Create a DomainParticipant.

2.Register user data types1 with the DomainParticipant. For example, the ‘FooDataType’.

3.Use the DomainParticipant to create a Topic with the registered data type.

4.Optionally2, use the DomainParticipant to create a Subscriber.

5.Use the Subscriber or DomainParticipant to create a DataReader for the Topic.

6.Use a type-safe method to cast the generic DataReader created by the Subscriber to a type- specific DataReader. For example, ‘FooDataReader’.

Now use one of the following mechanisms to receive data.

To receive data samples by polling for new data:

Using a FooDataReader, use the read() or take() operations to access the data samples that have been received and stored for the DataReader. These operations can be invoked at any time, even if the receive queue is empty.

To receive data samples asynchronously:

Install a Listener on the DataReader or Subscriber that will be called back by an internal Connext thread when new data samples arrive for the DataReader.

1.Create a DDSDataReaderListener for the FooDataReader or a DDSSubscriberListener for

Subscriber. In C++, C++/CLI, C# and Java, you must derive your own Listener class from those base classes. In C, you must create the individual functions and store them in a structure.

If you created a DDSDataReaderListener with the on_data_available() callback enabled: on_data_available() will be called when new data arrives for that

DataReader.

If you created a DDSSubscriberListener with the on_data_on_readers() callback enabled: on_data_on_readers() will be called when data arrives for any DataReader created by the Subscriber.

2.Install the Listener on either the FooDataReader or Subscriber.

For the DataReader, the Listener should be installed to handle changes in the

DATA_AVAILABLE status.

For the Subscriber, the Listener should be installed to handle changes in the

DATA_ON_READERS status.

3.Only 1 Listener will be called back when new data arrives for a DataReader.

Connext will call the Subscriber’s Listener if it is installed. Otherwise, the DataReader’s Listener is called if it is installed. That is, the on_data_on_readers() operation takes precedence over the on_data_available() operation.

If neither Listeners are installed or neither Listeners are enabled to handle their respective statuses, then Connext will not call any user functions when new data arrives for the DataReader.

1.Type registration is not required for built-in types (see Section 3.2.1).

2.You are not required to explicitly create a Subscriber; instead, you can use the 'implicit Subscriber' created from the DomainParticipant. See Creating Subscribers Explicitly vs. Implicitly (Section 7.2.1).

7-2

4.In the on_data_available() method of the DDSDataReaderListener, invoke read() or take() on the FooDataReader to access the data.

If the on_data_on_readers() method of the DDSSubscriberListener is called, the code can invoke read() or take() directly on the Subscriber’s DataReaders that have received new data. Alternatively, the code can invoke the Subscriber’s notify_datareaders() operation. This will in turn call the on_data_available() methods of the DataReaderListeners (if installed and enabled) for each of the DataReaders that have received new data samples.

To wait (block) until data samples arrive:

1.Use the DataReader to create a ReadCondition that describes the samples for which you want to wait. For example, you can specify that you want to wait for never-before-seen samples from DataReaders that are still considered to be ‘alive.’

Alternatively, you can create a StatusCondition that specifies you want to wait for the ON_DATA_AVAILABLE status.

2.Create a WaitSet.

3.Attach the ReadCondition or StatusCondition to the WaitSet.

4.Call the WaitSet’s wait() operation, specifying how long you are willing to wait for the desired samples. When wait() returns, it will indicate that it timed out, or that the attached Condition become true (and therefore the desired samples are available).

5.Using a FooDataReader, use the read() or take() operations to access the data samples that have been received and stored for the DataReader.

7.2Subscribers

An application that intends to subscribe to information needs the following Entities:

DomainParticipant, Topic, Subscriber, and DataReader. All Entities have a corresponding specialized Listener and a set of QosPolicies. The Listener is how Connext notifies your application of status changes relevant to the Entity. The QosPolicies allow your application to configure the behavior and resources of the Entity.

The DomainParticipant defines the domain on which the information will be available.

The Topic defines the name of the data to be subscribed, as well as the type (format) of the data itself.

The DataReader is the Entity used by the application to subscribe to updated values of the data. The DataReader is bound at creation time to a Topic, thus specifying the named and typed data stream to which it is subscribed. The application uses the DataWriter’s read() or take() operation to access data samples received for the Topic.

The Subscriber manages the activities of several DataReader entities. The application receives data using a DataReader that belongs to a Subscriber. However, the Subscriber will determine when the data received from applications is actually available for access through the DataReader. Depending on the settings of various QosPolicies of the Subscriber and DataReader, data may be buffered until data samples for associated DataReaders are also received. By default, the data is available to the application as soon as it is received.

For more information, see Creating Subscribers Explicitly vs. Implicitly (Section 7.2.1).

The UML diagram in Figure 7.1 shows how these Entities are related as well as the methods defined for each Entity.

7-3

Subscribers are used to perform the operations listed in Table 7.1. For details such as formal parameters and return codes, please see the API Reference HTML documentation. Otherwise, you can find more information about the operations by looking in the section listed under the Reference column.

Figure 7.1 Subscription Module

Note: Some operations cannot be used within a listener callback, see Restricted Operations in Listener Callbacks (Section 4.5.1).

7-4

Table 7.1 Subscriber Operations

Working

Operation

Description

Reference

with ...

 

 

 

 

 

 

 

 

begin_access

Indicates that the application is about to access the

Section 7.2.5

 

 

data samples in the DataReaders of the Subscriber.

 

 

create_datareader

Creates a DataReader.

 

 

 

 

Section 7.3.1

 

create_datareader_

Creates a DataReader with QoS from a specified QoS

 

with_profile

profile.

 

 

 

 

 

 

copy_from_topic_qos

Copies relevant QosPolicies from a Topic into a

Section 7.2.4.5

 

 

DataReaderQoS structure.

 

 

delete_contained_

Deletes all the DataReaders that were created by the

 

 

Subscriber. Also deletes the corresponding

Section 7.2.3.1

 

entities

 

ReadConditions created by the contained DataReaders.

 

 

 

 

 

 

 

 

 

delete_datareader

Deletes a specific DataReader.

Section 7.3.3

 

 

 

 

 

end_access

Indicates that the application is done accessing the

Section 7.2.5

 

 

data samples in the DataReaders of the Subscriber.

 

DataReaders

get_all_datareaders

Retrieves all the DataReaders created from this

Section 7.3.2

 

 

Subscriber.

 

 

 

Returns a list of DataReaders that contain samples

 

 

get_datareaders

with the specified sample_states, view_states and

Section 7.2.7

 

 

instance_states.

 

 

 

 

 

 

get_default_datareader

Copies the Subscriber’s default DataReaderQos

Section 7.2.4

 

_qos

values into a DataReaderQos structure.

 

 

get_status_changes

Gets all status changes.

Section 4.1.4

 

 

 

 

 

lookup_datareader

Retrieves a DataReader previously created for a

Section 7.2.8

 

 

specific Topic.

 

 

 

Invokes the on_data_available() operation for

 

 

notify_datareaders

attached Listeners of DataReaders that have new data

Section 7.2.6

 

 

samples.

 

 

 

 

 

 

set_default_datareader_

Sets or changes the Subscriber’s default

Section 7.2.4

 

qos

DataReaderQoS values.

 

 

get_default_library

Gets the Subscriber’s default QoS profile library.

 

 

 

 

 

 

get_default_profile

Gets the Subscriber’s default QoS profile.

 

 

 

 

 

Libraries

get_default_profile_

Gets the library that contains the Subscriber’s default

Section 7.2.4.3

and Profiles

library

QoS profile.

 

 

set_default_library

Sets the default library for a Subscriber.

 

 

 

 

 

 

set_default_profile

Sets the default profile for a Subscriber.

 

 

 

 

 

Participants

get_participant

Gets the Subscriber’s DomainParticipant.

Section 7.2.8

 

 

 

 

 

enable

Enables the Subscriber.

Section 4.1.2

 

 

 

 

 

get_listener

Gets the currently installed Listener.

Section 7.2.6

 

 

 

 

 

get_qos

Gets the Subscriber’s current QosPolicy settings. This

Section 7.2.4.2

 

 

is most often used in preparation for calling set_qos.

 

 

 

Sets the Subscriber’s Listener. If you created the

 

Subscribers

set_listener

Subscriber without a Listener, you can use this

Section 7.2.6

 

 

operation to add one later.

 

 

 

Sets the Subscriber’s QoS. You can use this operation

 

 

set_qos

to change the values for the Subscriber’s QosPolicies.

Section 7.2.4.2

 

Note, however, that not all QosPolicies can be

 

 

changed after the Subscriber has been created.

 

 

 

 

 

 

set_qos_with_profile

Sets the Subscriber’s QoS based on a QoS profile.

Section 7.2.4.2

 

 

 

 

7-5

7.2.1Creating Subscribers Explicitly vs. Implicitly

To receive data, your application must have a Subscriber. However, you are not required to explicitly create a Subscriber. If you do not create one, the middleware will implicitly create a Subscriber the first time you create a DataReader using the DomainParticipant’s operations. It will be created with default QoS (DDS_SUBCRIBER_QOS_DEFAULT) and no Listener. The 'implicit Subscriber' can be accessed using the DomainParticipant’s get_implicit_subscriber() operation (see Section 8.3.9).You can use this ‘implicit Subscriber’ just like any other Subscriber (it has the same operations, QosPolicies, etc.). So you can change the mutable QoS and set a Listener if desired.

A Subscriber (implicit or explicit) gets its own default QoS and the default QoS for its child DataReaders from the DomainParticipant. These default QoS are set when the Subscriber is created. (This is true for Publishers and DataWriters, too.)

DataReaders are created by calling create_datareader() or create_datareader_with_profile()— these operations exist for DomainParticipants and Subscribers. If you use the DomainParticipant to create a DataReader, it will belong to the implicit Subscriber. If you use a Subscriber to create a

DataReader, it will belong to that Subscriber.

The middleware will use the same implicit Subscriber for all DataReaders that are created using the DomainParticipant’s operations.

Having the middleware implicitly create a Subscriber allows you to skip the step of creating a Subscriber. However, having all your DataReaders belong to the same Subscriber can reduce the concurrency of the system because all the read operations will be serialized.

7.2.2Creating Subscribers

Before you can explicitly create a Subscriber, you need a DomainParticipant (Section 8.3). To create a Subscriber, use the DomainParticipant’s create_subscriber() or create_subscriber_with_profile() operation:

DDSSubscriber* create_subscriber(const DDS_SubscriberQos &qos, DDSSubscriberListener *listener, DDS_StatusMask mask)

DDSSubscriber* create_subscriber_with_profile (

const char * library_name, const char * profile_name,

DDSSubscriberListener * listener, DDS_StatusMask mask )

A QoS profile is way to use QoS settings from an XML file or string. With this approach, you can change QoS settings without recompiling the application. For details, see Chapter 17: Configuring QoS with XML.

qos If you want the default QoS settings (described in the API Reference HTML documentation), use DDS_SUBSCRIBER_QOS_DEFAULT for this parameter (see Figure 7.2). If you want to customize any of the QosPolicies, supply a QoS structure (see Figure 7.3). The QoS structure for a Subscriber is described in Section 7.5.

Note: If you use DDS_SUBSCRIBER_QOS_DEFAULT, it is not safe to create the Subscriber while another thread may be simultaneously calling set_default_subscriber_qos().

listener Listeners are callback routines. Connext uses them to notify your application when specific events (new data samples arrive and status changes) occur with respect to the Subscriber or the DataReaders created by the Subscriber. The listener parameter may be set to NULL if you do not want to install a Listener. If you use NULL, the Listener of the DomainParticipant to which the Subscriber belongs will be used instead (if it is set). For more information on SubscriberListeners, see Section 7.2.6.

7-6

mask This bit-mask indicates which status changes will cause the Subscriber’s Listener to be invoked. The bits set in the mask must have corresponding callbacks implemented in the Listener. If you use NULL for the Listener, use DDS_STATUS_MASK_NONE for this parameter. If the Listener implements all callbacks, use DDS_STATUS_MASK_ALL. For information on Status, see Listeners (Section 4.4).

library_name A QoS Library is a named set of QoS profiles. See QoS Libraries (Section 17.10).

profile_name A QoS profile groups a set of related QoS, usually one per entity. See QoS Profiles (Section 17.9).

Figure 7.2 Creating a Subscriber with Default QosPolicies

// create the subscriber DDSSubscriber* subscriber =

participant->create_subscriber(DDS_SUBSCRIBER_QOS_DEFAULT, NULL, DDS_STATUS_MASK_NONE);

if (subscriber == NULL) { // handle error

}

For more examples, see Configuring QoS Settings when the Subscriber is Created (Section 7.2.4.1).

After you create a Subscriber, the next step is to use the Subscriber to create a DataReader for each Topic, see Section 7.3.1. For a list of operations you can perform with a Subscriber, see Table 7.1.

7.2.3Deleting Subscribers

This section applies to both implicitly and explicitly created Subscribers. To delete a Subscriber:

1.You must first delete all DataReaders that were created with the Subscriber. Use the Subscriber’s delete_datareader() operation (Section 7.3.1) to delete them one at a time, or use the delete_contained_entities() operation (Section 7.2.3.1) to delete them all at the same time.

DDS_ReturnCode_t delete_datareader (DDSDataReader *a_datareader)

2. Delete the Subscriber by using the DomainParticipant’s delete_subscriber() operation ().

Note: A Subscriber cannot be deleted within a listener callback, see Restricted Operations in Listener Callbacks (Section 4.5.1).

7.2.3.1Deleting Contained DataReaders

The Subscriber’s delete_contained_entities() operation deletes all the DataReaders that were created by the Subscriber. It also deletes the ReadConditions created by each contained DataReader.

DDS_ReturnCode_t DDSSubscriber::delete_contained_entities ()

After this operation returns successfully, the application may delete the Subscriber (see Section 7.2.3).

The operation will return PRECONDITION_NOT_MET if any of the contained entities cannot be deleted. This will occur, for example, if a contained DataReader cannot be deleted because the application has called read() but has not called the corresponding return_loan() operation to return the loaned samples.

7-7

7.2.4Setting Subscriber QosPolicies

A Subscriber’s QosPolicies control its behavior. Think of the policies as the configuration and behavior ‘properties’ for the Subscriber. The DDS_SubscriberQos structure has the following format:

struct DDS_SubscriberQos { DDS_PresentationQosPolicy presentation; DDS_PartitionQosPolicy partition; DDS_GroupDataQosPolicy group_data; DDS_EntityFactoryQosPolicy entity_factory; DDS_ExclusiveAreaQosPolicy exclusive_area;

};

Note: set_qos() cannot always be used by a Listener, see Restricted Operations in Listener Callbacks (Section 4.5.1).

Table 7.2 summarizes the meaning of each policy. Subscribers have the same set of QosPolicies as Publishers; they are described in detail in Publisher/Subscriber QosPolicies (Section 6.4). For information on why you would want to change a particular QosPolicy, see the referenced section. For defaults and valid ranges, please refer to the API Reference HTML documentation for each policy.

Table 7.2 Subscriber QosPolicies

QosPolicy

Description

 

 

 

 

ENTITYFACTORY QosPolicy

Whether or not new entities created from this entity

(Section 6.4.2)

will start out as ‘enabled.’

 

 

EXCLUSIVE_AREA QosPolicy (DDS Extension)

Whether or not the entity uses a multi-thread safe

(Section 6.4.3)

region with deadlock protection.

 

 

GROUP_DATA QosPolicy

A place to pass group-level information among

(Section 6.4.4)

applications. Usage is application-dependent.

 

 

PARTITION QosPolicy

Set of strings that introduces a logical partition among

(Section 6.4.5)

Topics visible by Publisher/Subscriber.

 

 

PRESENTATION QosPolicy

The order in which instance changes are presented to

(Section 6.4.6)

the Subscriber. By default, no order is used.

 

 

7.2.4.1Configuring QoS Settings when the Subscriber is Created

As described in Creating Subscribers (Section 7.2.2), there are different ways to create a

Subscriber, depending on how you want to specify its QoS (with or without a QoS Profile).

In Figure 7.2 on page 7-7 we saw an example of how to explicitly create a Subscriber with default QosPolicies. It used the special constant, DDS_SUBSCRIBER_QOS_DEFAULT, which indicates that the default QoS values for a Subscriber should be used. The default Subscriber QosPolicies are configured in the DomainParticipant; you can change them with the DomainParticipant’s set_default_subscriber_qos() or set_default_subscriber_qos_with_profile() operation (see Section 8.3.6.4).

To create a Subscriber with non-default QoS settings, without using a QoS profile, see Figure 7.3 on page 7-9. It uses the DomainParticipant’s get_default_subscriber_qos() method to initialize a DDS_SubscriberQos structure. Then the policies are modified from their default values before the QoS structure is passed to create_subscriber().

You can also create a Subscriber and specify its QoS settings via a QoS Profile. To do so, call create_subscriber_with_profile(), as seen in Figure 7.4 on page 7-9.

If you want to use a QoS profile, but then make some changes to the QoS before creating the Subscriber, call get_subscriber_qos_from_profile(), modify the QoS and use the modified QoS structure when calling create_subscriber(), as seen in Figure 7.5 on page 7- 10.

7-8

For more information, see Creating Subscribers (Section 7.2.2) and Chapter 17: Configuring QoS with XML.

Figure 7.3 Creating a Subscriber with Non-default QosPolicies (not from a profile)

DDS_SubscriberQos subscriber_qos;1

// get defaults

if (participant->get_default_subscriber_qos(subscriber_qos) != DDS_RETCODE_OK){

// handle error

}

//make QoS changes here. for example, this changes the ENTITY_FACTORY QoS subscriber_qos.entity_factory.autoenable_created_entities=DDS_BOOLEAN_FALSE;

//create the subscriber

DDSSubscriber * subscriber = participant->create_subscriber(subscriber_qos, NULL, DDS_STATUS_MASK_NONE);

if (subscriber == NULL) { // handle error

}

1. For the C API, you need to use DDS_SubscriberQos_INITIALIZER or DDS_SubscriberQos_initialize(). See Special QosPolicy Handling Considerations for C (Section 4.2.2)

Figure 7.4 Creating a Subscriber with a QoS Profile

// create the subscriber with QoS profile DDSSubscriber * subscriber =

participant->create_subscriber_with_profile(

“MySubscriberLibary”,

“MySubscriberProfile”, NULL, DDS_STATUS_MASK_NONE);

if (subscriber == NULL) { // handle error

}

7.2.4.2Changing QoS Settings After Subscriber Has Been Created

There are 2 ways to change an existing Subscriber’s QoS after it is has been created—again depending on whether or not you are using a QoS Profile.

To change an existing Subscriber’s QoS programmatically (that is, without using a QoS profile), get_qos() and set_qos(). See the example code in Figure 7.6 on page 7-10. It retrieves the current values by calling the Subscriber’s get_qos() operation. Then it modify the value and call set_qos() to apply the new value. Note, however, that some QosPolicies cannot be changed after the Subscriber has been enabled—this restriction is noted in the descriptions of the individual QosPolicies.

7-9

Figure 7.5 Getting QoS Values from a Profile, Changing QoS Values, Creating a Subscriber with Modified QoS Values

DDS_SubscriberQos subscriber_qos;1

// Get subscriber QoS from profile

retcode = factory->get_subscriber_qos_from_profile(subscriber_qos, “SubscriberLibrary”, “SubscriberProfile”);

if (retcode != DDS_RETCODE_OK) { // handle error

}

//Makes QoS changes here

//for example, this changes the ENTITY_FACTORY QoS subscriber_qos.entity_factory.autoenable_created_entities =

DDS_BOOLEAN_TRUE;

// create the subscriber with modified QoS

DDSPublisher* subscriber = participant->create_subscriber( “Example Foo”, type_name, subscriber_qos,

NULL, DDS_STATUS_MASK_NONE);

if (subscriber == NULL) { // handle error

}

1.For the C API, you need to use DDS_SubscriberQos_INITIALIZER or

DDS_SubscriberQos_initialize(). See Special QosPolicy Handling Considerations for C (Section 4.2.2)

You can also change a Subscriber’s (and all other Entities’) QoS by using a QoS Profile and calling set_qos_with_profile(). For an example, see Figure 7.7 on page 7-11. For more information, see Chapter 17: Configuring QoS with XML.

Figure 7.6 Changing the Qos of an Existing Subscriber

DDS_SubscriberQos subscriber_qos;1

// Get current QoS. subscriber points to an existing DDSSubscriber. if (subscriber->get_qos(subscriber_qos) != DDS_RETCODE_OK) {

// handle error

}

//make changes

//New entity_factory autoenable_created_entities will be true subscriber_qos.entity_factory.autoenable_created_entities =

DDS_BOOLEAN_TRUE;

// Set the new QoS

if (subscriber->set_qos(subscriber_qos) != DDS_RETCODE_OK ) { // handle error

}

1.For the C API, you need to use DDS_SubscriberQos_INITIALIZER or DDS_SubscriberQos_Initialize(). See Special QosPolicy Handling Considerations for C (Section 4.2.2)

7-10

Figure 7.7 Changing the QoS of an Existing Subscriber with a QoS Profile

retcode = subscriber->set_qos_with_profile( “SubscriberProfileLibrary”,”SubscriberProfile”);

if (retcode != DDS_RETCODE_OK) { // handle error

}

7.2.4.3Getting and Settings the Subscriber’s Default QoS Profile and Library

You can retrieve the default QoS profile used to create Subscribers with the get_default_profile() operation. You can also get the default library for Subscribers, as well as the library that contains the Subscriber’s default profile (these are not necessarily the same library); these operations are called get_default_library() and get_default_library_profile(), respectively. These operations are for informational purposes only (that is, you do not need to use them as a precursor to setting a library or profile.) For more information, see Chapter 17: Configuring QoS with XML.

virtual const char * get_default_library ()

const char * get_default_profile ()

const char * get_default_profile_library ()

There are also operations for setting the Subscriber’s default library and profile:

DDS_ReturnCode_t set_default_library (const char * library_name)

DDS_ReturnCode_t set_default_profile (const char * library_name, const char * profile_name)

These operations only affect which library/profile will be used as the default the next time a default Subscriber library/profile is needed during a call to one of this Subscriber’s operations.

When calling a Subscriber operation that requires a profile_name parameter, you can use NULL to refer to the default profile. (This same information applies to setting a default library.)

If the default library/profile is not set, the Subscriber inherits the default from the

DomainParticipant.

set_default_profile() does not set the default QoS for DataReaders created by the Subscriber; for this functionality, use the Subscriber’s set_default_datareader_qos_with_profile(), see

Section 7.2.4.4 (you may pass in NULL after having called the Subscriber’s set_default_profile()).

set_default_profile() does not set the default QoS for newly created Subscribers; for this functionality, use the DomainParticipant’s set_default_subscriber_qos_with_profile() operation, see Section 8.3.6.4.

7.2.4.4Getting and Setting Default QoS for DataReaders

These operations set the default QoS that will be used for new DataReaders if create_datareader() is called with DDS_DATAREADER_QOS_DEFAULT as the ‘qos’ parameter:

DDS_ReturnCode_t set_default_datareader_qos (

const DDS_DataReaderQos &qos)

DDS_ReturnCode_t set_default_datareader_qos_with_profile ( const char *library_name, const char *profile_name)

The above operations may potentially allocate memory, depending on the sequences contained in some QoS policies.

7-11

To get the default QoS that will be used for creating DataReaders if create_datareader() is called with DDS_DATAREADER_QOS_DEFAULT as the ‘qos’ parameter:

DDS_ReturnCode_t get_default_datareader_qos (DDS_DataReaderQos & qos)

The above operation gets the QoS settings that were specified on set_default_datareader_qos() or set_default_datareader_qos_with_ never made, the default values listed in DDS_DataReaderQos.

the last successful call to profile(), or if the call was

Note: It is not safe to set the default DataReader QoS values while another thread may be simultaneously calling get_default_datareader_qos(), set_default_datareader_qos() or create_datareader() with DDS_DATAREADER_QOS_DEFAULT as the qos parameter. It is also not safe to get the default DataReader QoS values while another thread may be simultaneously calling set_default_datareader_qos(),

7.2.4.5Subscriber QoS-Related Operations

Copying a Topic’s QoS into a DataReader’s QoS This method is provided as a convenience for setting the values in a DataReaderQos structure before using that structure to create a DataReader. As explained in Section 5.1.3, most of the policies in a TopicQos structure do not apply directly to the Topic itself, but to the associated DataWriters and DataReaders of that Topic. The TopicQos serves as a single container where the values of QosPolicies that must be set compatibly across matching DataWriters and DataReaders can be stored.

Thus instead of setting the values of the individual QosPolicies that make up a DataReaderQos structure every time you need to create a DataReader for a Topic, you can use the Subscriber’s copy_from_topic_qos() operation to “import” the Topic’s QosPolicies into a DataReaderQos structure. This operation copies the relevant policies in the TopicQos to the corresponding policies in the DataReaderQos.

This copy operation will often be used in combination with the Subscriber’s get_default_datareader_qos() and the Topic’s get_qos() operations. The Topic’s QoS values are merged on top of the Subscriber’s default DataReader QosPolicies with the result used to create a new DataReader, or to set the QoS of an existing one (see Section 7.3.8).

Copying a Subscriber’s QoS In the C API users should use the DDS_SubscriberQos_copy() operation rather than using structure assignment when copying between two QoS structures. The copy() operation will perform a deep copy so that policies that allocate heap memory such as sequences are copied correctly. In C++, C++/CLI, C# and Java, a copy constructor is provided to take care of sequences automatically.

Clearing QoS-Related Memory Some QosPolicies contain sequences that allocate memory dynamically as they grow or shrink. The C API’s DDS_SubscriberQos_finalize() operation frees the memory used by sequences but otherwise leaves the QoS unchanged. C users should call finalize() on all DDS_SubscriberQos objects before they are freed, or for QoS structures allocated on the stack, before they go out of scope. In C++, C++/CLI, C# and Java, the memory used by sequences is freed in the destructor.

7.2.5Beginning and Ending Group-Ordered Access

The Subscriber’s begin_access() operation indicates that the application is about to access the data samples in any of the DataReaders attached to the Subscriber.

If the Subscriber’s access_scope (in the PRESENTATION QosPolicy (Section 6.4.6)) is GROUP or HIGHEST_OFFERED and ordered_access (also in the PRESENTATION QosPolicy (Section 6.4.6)) is TRUE, the application is required to use this operation to access the samples in order across DataWriters of the same group (Publisher with access_scope GROUP).

7-12

In the above case, begin_access() must be called prior to calling any of the sample-accessing operations: get_datareaders() on the Subscriber, and read(), take(), read_w_condition(), and take_w_condition() on any DataReader.

Once the application has finished accessing the data samples, it must call end_access().

The application is not required to call begin_access() and end_access() to access the samples in order if the Publisher’s access_scope is something other than GROUP. In this case, calling begin_access() and end_access() is not considered an error and has no effect.

Calls to begin_access() and end_access() may be nested and must be balanced. That is, end_access() close a previous call to begin_access().

7.2.6Setting Up SubscriberListeners

Like all Entities, Subscribers may optionally have Listeners. Listeners are user-defined objects that implement a DDS-defined interface (i.e. a pre-defined set of callback functions). Listeners provide the means for Connext to notify applications of any changes in Statuses (events) that may be relevant to it. By writing the callback functions in the Listener and installing the Listener into the Subscriber, applications can be notified to handle the events of interest. For more general information on Listeners and Statuses, see Section 4.4.

Note: Some operations cannot be used within a listener callback, see Restricted Operations in Listener Callbacks (Section 4.5.1).

As illustrated in Figure 7.1, the SubscriberListener interface extends the DataReaderListener interface. In other words, the SubscriberListener interface contains all the functions in the DataReaderListener interface. In addition, a SubscriberListener has 1 additional function: on_data_on_readers().

corresponding to the Subscriber’s DATA_ON_READERS status. This is the only status that is specific to a Subscriber. This status is closely tied to the DATA_AVAILABLE status (Section 7.3.7.1) of DataReaders.

The Subscriber’s DATA_ON_READERS status is set whenever the DATA_AVAILABLE status is set for any of the DataReaders created by the Subscriber. This implies that one of its DataReaders has received new data samples. When the DATA_ON_READERS status is set, the SubscriberListener’s on_data_on_readers() method will be invoked.

The DATA_ON_READERS status of a Subscriber takes precedence over the DATA_AVAILABLE status of any of its DataReaders. Thus, when data arrives for a DataReader, the on_data_on_readers() operation of the SubscriberListener will be called instead of the on_data_available() operation of the DataReaderListener—assuming that the Subscriber has a Listener installed that is enabled to handle changes in the DATA_ON_READERS status. (Note however, that in the SubscriberListener’s on_data_on_readers() operation, you may choose to call notify_datareaders(), which in turn may cause the DataReaderListener’s on_data_available() operation to be called.)

All of the other methods of a SubscriberListener will be called back for changes in the Statuses of Subscriber’s DataReaders only if the DataReader is not set up to handle the statuses itself.

If you want a Subscriber to handle status events for its DataReaders, you can set up a SubscriberListener during the Subscriber’s creation or use the set_listener() method after the Subscriber is created. The last parameter is a bit-mask with which you should set which Status events that the SubscriberListener will handle. For example,

DDS_StatusMask mask = DDS_REQUESTED_DEADLINE_MISSED_STATUS | DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS;

subscriber = participant->create_subscriber(DDS_SUBSCRIBER_QOS_DEFAULT,

listener, mask);

7-13

or

DDS_StatusMask mask = DDS_REQUESTED_DEADLINE_MISSED_STATUS |

DDS_REQUESTED_INCOMPATIBLE_QOS_STATUS;

subscriber->set_listener(listener, mask);

As previously mentioned, the callbacks in the SubscriberListener act as ‘default’ callbacks for all the DataReaders contained within. When Connext wants to notify a DataReader of a relevant Status change (for example, SUBSCRIPTION_MATCHED), it first checks to see if the DataReader has the corresponding DataReaderListener callback enabled (such as the on_subscription_matched() operation). If so, Connext dispatches the event to the DataReaderListener callback. Otherwise, Connext dispatches the event to the corresponding

SubscriberListener callback.

NOTE, the reverse is true for the DATA_ON_READERS/DATA_AVAILABLE status. When DATA_AVAILABLE changes for any DataReaders of a Subscriber, Connext first checks to see if the SubscriberListener has DATA_ON_READERS enabled. If so, Connext will invoke the on_data_on_readers() callback. Otherwise, Connext dispatches the event to the Listener (on_data_available()) of the DataReader whose DATA_AVAILABLE status actually changed.

A particular callback in a DataReader is not enabled if either:

The application installed a NULL DataReaderListener (meaning there are no callbacks for the DataReader at all).

The application has disabled the callback for a DataReaderListener. This is done by turning off the associated status bit in the mask parameter passed to the set_listener() or create_datareader() call when installing the DataReaderListener on the DataReader. For more information on DataReaderListener, see Section 7.3.4.

Similarly, the callbacks in the DomainParticipantListener act as ‘default’ callbacks for all the Subscribers that belong to it. For more information on DomainParticipantListeners, see Section 8.3.5.

The Subscriber also provides an operation called notify_datareaders() that can be used to invoke the on_data_available() callbacks of DataReaders who have new data samples in their receive queues. Often notify_datareaders() will be used in the on_data_on_readers() callback to pass off the real processing of data from the SubscriberListener to the individual DataReaderListeners.

Calling notify_datareaders() causes the DATA_ON_READERS status to be reset.

Figure 7.8 shows a SubscriberListener that simply notifies its DataReaders when new data arrives.

Figure 7.8 Simple SubscriberListener

class MySubscriberListener : public DDSSubscriberListener { public:

void on_data_on_readers(DDSSubscriber *);

/* For this example we take no action other operations */

};

void MySubscriberListener::on_data_on_readers (DDSSubscriber *subscriber)

{

... // do global processing

// now dispatch data arrival event to specific DataReaders subscriber->notify_datareaders();

}

7-14

7.2.7Getting DataReaders with Specific Samples

The Subscriber’s get_datareaders() operation retrieves a list of DataReaders that have samples with specific sample_states, view_states, and instance_states.

If the application is outside a begin_access()/end_access() block, or if the Subscriber’s access_scope (in the PRESENTATION QosPolicy (Section 6.4.6)) is INSTANCE or TOPIC, or ordered_access (also in the PRESENTATION QosPolicy (Section 6.4.6)) is FALSE, the returned collection is a 'set' containing each DataReader at most once, in no specified order.

If the application is within a begin_access()/end_access() block, and the Subscriber’s access_scope is GROUP or HIGHEST_OFFERED, and ordered_access is TRUE, the returned collection is a 'list' of DataReaders, where a DataReader may appear more than one time.

To retrieve the samples in the order in which they were published across DataWriters of the same group (a Publisher configured with GROUP access_scope), the application should read()/take() from each DataReader in the same order as appears in the output sequence. The application will move to the next DataReader when the read()/take() operation fails with NO_DATA.

DDS_ReturnCode_t get_datareaders (DDSDataReaderSeq & readers, DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)

For more information, see The SampleInfo Structure (Section 7.4.6).

7.2.8Finding a Subscriber’s Related Entities

These Subscriber operations are useful for obtaining a handle to related entities:

get_participant(): Gets the DomainParticipant with which a Subscriber was created.

lookup_datareader(): Finds a DataReader created by the Subscriber with a Topic of a particular name. Note that if multiple DataReaders were created by the same Subscriber with the same Topic, any one of them may be returned by this method.

You can use this operation on a built-in Subscriber to access the built-in DataReaders for the built-in topics. The built-in DataReader is created when this operation is called on a built-in topic for the first time.

If you are going to modify the transport properties for the built-in DataReaders, do so before using this operation. Built-in transports are implicitly registered when the DomainParticipant is enabled or the first DataWriter/DataReader is created. To ensure that built-in DataReaders receive all the discovery traffic, you should lookup the DataReader before the DomainParticipant is enabled. Therefore the suggested sequence when looking up built-in DataReaders is:

1.Create a disabled DomainParticipant (see Section 6.4.2).

2.If you want to use non-default values, modify the built-in transport properties (see Section 15.5).

3.Call get_builtin_subscriber() (see Section 16.2).

4.Call lookup_datareader().

5.Call enable() on the DomainParticipant (see Section 4.1.2).

DDS_Subscriber_as_Entity(): This method is provided for C applications and is necessary when invoking the parent class Entity methods on Subscribers. For example, to call the Entity method get_status_changes() on a Subscriber, my_sub, do the following:

DDS_Entity_get_status_changes(DDS_Subscriber_as_Entity(my_sub))

DDS_Subscriber_as_Entity() is not provided in the C++, C++/CLI, C# and Java APIs because the object-oriented features of those languages make it unnecessary.

7-15

7.2.9Statuses for Subscribers

The status indicators for a Subscriber are the same as those available for its DataReaders, with one additional status: DATA_ON_READERS (Section 7.2.9.1). The following statuses can be monitored by the SubscriberListener.

DATA_ON_READERS Status (Section 7.2.9.1)

DATA_AVAILABLE Status (Section 7.3.7.1)

LIVELINESS_CHANGED Status (Section 7.3.7.4)

REQUESTED_DEADLINE_MISSED Status (Section 7.3.7.5)

REQUESTED_INCOMPATIBLE_QOS Status (Section 7.3.7.6)

SAMPLE_LOST Status (Section 7.3.7.7)

SAMPLE_REJECTED Status (Section 7.3.7.8)

SUBSCRIPTION_MATCHED Status (Section 7.3.7.9)

You can access Subscriber status by using a SubscriberListener or its inherited get_status_changes() operation (see Section 4.1.4), which can be used to explicitly poll for the

DATA_ON_READERS status of the Subscriber.

7.2.9.1DATA_ON_READERS Status

The DATA_ON_READERS status, like the DATA_AVAILABLE status for DataReaders, is a read communication status, which makes it somewhat different from other plain communication statuses. (See Types of Communication Status (Section 4.3.1) for more information on statuses and the difference between read and plain statuses.) In particular, there is no status-specific data structure; the status is either changed or not, there is no additional associated information.

The DATA_ON_READERS status indicates that there is new data available for one or more DataReaders that belong to this Subscriber. The DATA_AVAILABLE status for each such DataReader will also be updated.

The DATA_ON_READERS status is reset (the corresponding bit in the bitmask is turned off) when you call read/take (or one of the variations) on any of the DataReaders that belong to the Subscriber. This is true even if the DataReader on which you call read/take is not the same DataReader that caused the DATA_ON_READERS status to be set in the first place. This status is also reset when you call notify_datareaders() on the Subscriber, or after on_data_on_readers() is invoked.

If a SubscriberListener has both on_data_on_readers() and on_data_available() callbacks enabled (by turning on both status bits), only on_data_on_readers() is called.

7.3DataReaders

To create a DataReader, you need a DomainParticipant, a Topic, and optionally, a Subscriber. You need at least one DataReader for each Topic whose data samples you want to receive.

After you create a DataReader, you will be able to use the operations listed in Table 7.3. You are likely to use many of these operations from within your DataReader’s Listener, which is invoked when there are status changes or new data samples. For more details on all operations, see the API reference HTML documentation. The DataReaderListener is described in Section 7.3.4.

DataReaders are created by using operations on a DomainParticipant or a Subscriber, as described in Section 7.2.1. If you use the DomainParticipant’s operations, the DataReader will belong to an implicit Subscriber that is automatically created by the middleware. If you use a Subscriber’s

7-16

operations, the DataReader will belong to that Subscriber. So either way, the DataReader belongs to a Subscriber.

Note: Some operations cannot be used within a listener callback, see Restricted Operations in Listener Callbacks (Section 4.5.1).

Table 7.3 DataReader Operations

Purpose

Operation

 

 

Description

 

 

Reference

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

enable

Enables the DataReader.

 

 

 

Section 4.1.2

 

 

 

 

 

 

 

 

 

 

 

 

get_qos

Gets the QoS.

 

 

 

 

 

 

Configuring

 

 

 

 

 

 

 

 

 

set_qos

Modifies the QoS.

 

 

 

 

Section 7.3.8

the

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

set_qos_with_profile

Modifies the QoS based on a QoS profile.

 

 

DataReader

 

 

 

 

 

 

 

 

 

 

 

 

 

get_listener

Gets the currently installed Listener.

 

 

Section 7.3.4

 

 

 

 

 

 

 

 

 

 

 

 

set_listener

Replaces the Listener.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

read

Reads (copies) a collection of data samples

Section 7.4.3

 

 

 

from the DataReader.

 

 

 

 

 

 

 

Identical to read, but all samples returned

 

 

 

read_instance

belong to a single instance, which you specify

Section 7.4.3.4

 

 

 

as a parameter.

 

 

 

 

 

 

 

 

 

 

 

 

 

Identical to read_instance, but all samples

 

Accessing

 

read_instance_w_condition

returned belong to a single instance and satisfy

Section 7.4.3.7

 

 

a specific ReadCondition.

 

 

 

 

Data

 

 

 

 

 

 

 

 

 

 

 

 

Similar

to read_instance,

but the

actual

 

Samples with

 

 

 

instance

is

not

directly

specified

as

a

 

“Read”

 

 

 

 

read_next_instance

parameter. Instead, the samples will all belong

Section 7.4.3.5

(Use

 

 

 

to instance ordered after the one previously

 

FooData-

 

 

 

 

 

read.

 

 

 

 

 

 

 

Reader,

see

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Accesses a collection of data samples of the

 

Section 7.4.3)

read_next_instance_w_

 

next instance

that

match a

specific

set

of

Section 7.4.3.8

 

 

condition

 

 

ReadConditions, from the DataReader.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

read_next_sample

Reads the next not-previously-accessed data

Section 7.4.3.3

 

 

 

value from the DataReader.

 

 

 

 

 

 

 

Accesses a collection of data samples from the

 

 

 

read_w_condition

DataReader that match specific ReadCondition

Section 7.4.3.6

 

 

 

criteria.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

take

Like read, but the samples are removed from

Section 7.4.3

 

 

 

the DataReader’s receive queue.

 

 

 

 

 

 

Identical to take, but all samples returned

 

 

 

take_instance

belong to a single instance, which you specify

Section 7.4.3.4

 

 

 

as a parameter.

 

 

 

 

 

 

 

 

 

 

Accessing

 

 

Identical to take_instance, but all samples

 

 

take_instance_w_condition

returned belong to a single instance and satisfy

Section 7.4.3.7

Data

 

 

a specific ReadCondition.

 

 

 

 

Samples with

 

 

 

 

 

 

 

 

 

 

Like read_next_instance, but the samples are

 

“Take”

 

take_next_instance

Section 7.4.3.5

(Use

 

 

removed from the DataReader’s receive queue.

 

 

 

Accesses (and removes) a collection of data

 

FooData-

 

 

 

Reader,

see

take_next_instance_w_

samples of the next instance that match a

Section 7.4.3.8

Section 7.4.3)

condition

specific set of ReadConditions, from the

 

 

 

DataReader.

 

 

 

 

 

 

 

 

 

 

 

 

 

take_next_sample

Like read_next_sample, but the samples are

Section 7.4.3.3

 

 

 

removed from the DataReader’s receive queue.

 

 

 

 

Accesses (and removes) a collection of data

 

 

 

take_w_condition

samples from the DataReader that match

Section 7.4.3.6

 

 

 

specific ReadCondition criteria.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

7-17

Table 7.3 DataReader Operations

Purpose

Operation

 

Description

Reference

 

 

 

 

 

 

 

 

Working

 

A type-safe way to cast a pointer. This takes a

 

 

DDSDataReader pointer and ‘narrows’ it to a

 

with Data

narrow

Section 7.4.1

Samples and

 

‘FooDataReader’ where ‘Foo’ is the related

 

 

data type.

 

FooData-

 

 

 

 

 

 

Reader

return_loan

Returns buffers loaned in a previous read or

Section 7.4.2

(Use

 

take call.

 

 

 

 

 

FooData-

get_key_value

Gets the key for an instance handle.

Section 7.3.9.4

Reader, see

 

 

 

 

lookup_instance

Gets the instance handle that corresponds to

Section 7.3.9.3

Section 7.4.3)

 

 

an instance key.

 

Acknowledgi

acknowledge_all

Acknowledge all previously accessed samples.

Section 7.4.4

ng Samples

acknowledge_sample

Acknowledge a single sample.

 

 

 

 

 

 

get_liveliness_changed_

Gets LIVELINESS_CHANGED_STATUS

 

 

status

status.

 

 

 

 

 

 

 

get_requested_deadline_

Gets REQUESTED_DEADLINE_

 

 

missed_status

MISSED_STATUS status.

 

 

 

 

 

 

get_requested_

Gets REQUESTED_INCOMPATIBLE_

 

 

incompatible_qos_status

QOS_STATUS status.

Section 7.3.7

 

get_sample_lost_status

Gets SAMPLE_LOST_STATUS status.

 

 

 

 

 

 

 

get_sample_rejected_

Gets SAMPLE_REJECTED_STATUS status.

 

 

status

 

 

 

 

 

 

 

 

 

 

Checking

get_subscription_matched_

Gets

SUBSCRIPTION_MATCHED_STATUS

 

status

status.

 

 

Status

 

 

 

 

 

 

 

 

Gets a list of statuses that changed since last

 

 

get_status_changes

time the application read the status or the

Section 4.1.4

 

 

listeners were called.

 

 

 

 

 

 

 

get_datareader_cache_

Gets

DATA_READER_CACHE_STATUS

 

 

status

status.

 

 

 

 

 

 

 

get_datareader_protocol_

Gets DATA_READER_PROTOCOL_

Section 7.3.5

 

status

STATUS status.

 

Section 7.3.7

 

 

 

 

 

get_matched_publication_

Get the protocol status for this DataReader, per

 

 

 

datareader_protocol_

matched publication identified by the

 

 

status

publication_handle.

 

 

 

 

 

 

get_instance_handle

Returns the DDS_InstanceHandle_t associated

Section 4.1.3

 

 

with the Entity.

 

 

get_matched_publication_

Gets information on a publication with a

 

 

data

matching Topic and compatible QoS.

 

 

 

 

 

Navigating

 

Gets a list of publications that have a matching

Section 7.3.9.1

Relationships

get_matched_publications

Topic and compatible QoS. These are the

 

 

 

publications currently associated with the

 

 

 

DataReader.

 

 

 

 

 

 

get_subscriber

Gets the Subscriber that created the DataReader.

Section 7.3.9.2

 

 

 

 

 

get_topicdescription

Gets the Topic associated with the DataReader.

 

 

 

 

 

 

 

7-18

Table 7.3 DataReader Operations

Purpose

Operation

 

 

Description

Reference

 

 

 

 

 

 

 

 

 

 

 

create_querycondition

Creates a QueryCondition.

 

 

 

 

 

 

 

 

create_readcondition

Creates a ReadCondition.

 

Section 4.6.7

 

 

 

 

 

 

 

delete_readcondition

Deletes

a

ReadCondition/QueryCondition

 

 

Working

attached to the DataReader.

 

 

 

 

 

with

 

 

 

 

 

 

 

Deletes all the ReadConditions/QueryConditions

 

Conditions

 

 

delete_contained_entities

that were created by means of the "create"

Section 7.3.3.1

 

 

 

operations on the DataReader.

 

 

 

 

 

 

 

get_statuscondition

Gets the StatusCondition associated with the

Section 4.6.8

 

 

Entity.

 

 

 

 

Waiting for

 

Waits until all

"historical"

(previously sent)

 

 

data is received. Only valid for Reliable

 

Historical

wait_for_historical_data

Section 7.3.6

DataReaders

with

non-VOLATILE

Data

 

DURABILITY.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

7.3.1Creating DataReaders

Before you can create a DataReader, you need a DomainParticipant and a Topic.

DataReaders are created by calling create_datareader() or create_datareader_with_profile()— these operations exist for DomainParticipants and Subscribers. If you use the DomainParticipant to create a DataReader, it will belong to the implicit Subscriber described in Section 7.2.1. If you use a Subscriber’s operations to create a DataReader, it will belong to that Subscriber.

DDSDataReader* create_datareader(DDSTopicDescription *topic, const DDS_DataReaderQos &qos,

DDSDataReaderListener *listener, DDS_StatusMask mask);

DDSDataReader * create_datareader_with_profile ( DDSTopicDescription * topic, const char * library_name, const char * profile_name,

DDSDataReaderListener * listener, DDS_StatusMask mask)

A QoS profile is way to use QoS settings from an XML file or string. With this approach, you can change QoS settings without recompiling the application. For details, see Chapter 17: Configuring QoS with XML.

topic The Topic to which the DataReader is subscribing. This must have been previously created by the same DomainParticipant.

qos If you want the default QoS settings (described in the API Reference HTML documentation), use DDS_DATAREADER_QOS_DEFAULT for this parameter (see Figure 7.9 on page 7-20). If you want to customize any of the QosPolicies, supply a QoS structure (see Section 7.3.8).

Note: If you use DDS_DATAREADER_QOS_DEFAULT for the qos parameter, it is not safe to create the DataReader while another thread may be simultaneously calling the Sub- scriber’s set_default_datareader_qos() operation.

listener A DataReader’s Listener is where you define the callback routine that will be notified when new data samples arrive. Connext also uses this Listener to notify your application of specific events (status changes) that may occur with respect to the DataReader. For more information, see Section 7.3.4 and Section 7.3.7.

7-19

The listener parameter is optional; you may use NULL instead. In that case, the Subscriber’s Listener (or if that is NULL, the DomainParticipant’s Listener) will receive the notifications instead. See Section 7.3.4 for more on DataReaderListeners.

mask This bit mask indicates which status changes will cause the Listener to be invoked. The bits set in the mask must have corresponding callbacks implemented in the Listener. If you use NULL for the Listener, use DDS_STATUS_MASK_NONE for this parameter. If the Listener implements all callbacks, use DDS_STATUS_MASK_ALL. For information on statuses, see Listeners (Section 4.4).

library_name A QoS Library is a named set of QoS profiles. See QoS Libraries (Section 17.10).

profile_name A QoS profile groups a set of related QoS, usually one per entity. See QoS Profiles (Section 17.9).

After you create a DataReader, you can use it to retrieve received data. See Section 7.4.

Note: When a DataReader is created, only those transports already registered are available to the DataReader. The built-in transports are implicitly registered when (a) the DomainParticipant is enabled, (b) the first DataReader is created, or (c) you lookup a built-in DataReader, whichever happens first.

Figure 7.9 shows an example of how to create a DataReader with default QosPolicies.

Figure 7.9 Creating a DataReader with Default QosPolicies

// MyReaderListener is user defined, extends DDSDataReaderListener DDSDataReaderListener *reader_listener = new MyReaderListener();

DataReader* reader = subscriber->create_datareader(topic, DDS_DATAREADER_QOS_DEFAULT, reader_listener, DDS_STATUS_MASK_ALL);

if (reader == NULL) { // ... error

}

// narrow it into your specific data type

FooDataReader* foo_reader = FooDataReader::narrow(reader);

For more examples on how to create a DataWriter, see Configuring QoS Settings when the DataReader is Created (Section 7.3.8.1)

7.3.2Getting All DataReaders

To retrieve all the DataReaders created by the Subscriber, use the Subscriber’s get_all_datareaders() operation:

DDS_ReturnCode_t get_all_datareaders(

DDS_Subscriber* self,

struct DDS_DataReaderSeq* readers);

7.3.3Deleting DataReaders

To delete a DataReader:

1.Delete any ReadConditions and QueryConditions that were created with the DataReader.

Use the DataReader’s delete_readcondition() operation to delete them one at a time, or use the delete_contained_entities() operation (Section 7.3.3.1) to delete them all at the same time.

DDS_ReturnCode_t delete_readcondition (DDSReadCondition *condition)

7-20

2. Delete the DataReader by using the Subscriber’s delete_datareader() operation (Section 7.2.3).

Note: A DataReader cannot be deleted within its own reader listener callback, see Restricted Operations in Listener Callbacks (Section 4.5.1).

To delete all of a Subscriber’s DataReaders, use the Subscriber’s delete_contained_entities() operation (see Section 7.2.3.1).

7.3.3.1Deleting Contained ReadConditions

The DataReader’s delete_contained_entities() operation deletes all the ReadConditions and QueryConditions (Section 4.6.7) that were created by the DataReader.

DDS_ReturnCode_t delete_contained_entities ()

After this operation returns successfully, the application may delete the DataReader (see Section 7.3.3).

7.3.4Setting Up DataReaderListeners

DataReaders may optionally have Listeners. A DataReaderListener is a collection of callback methods; these methods are invoked by Connext when data samples are received or when there are status changes for the DataReader.

Note: Some operations cannot be used within a listener callback, see Restricted Operations in Listener Callbacks (Section 4.5.1).

If you do not implement a DataReaderListener, the associated Subscriber’s Listener is used instead. If that Subscriber does not have a Listener either, then the DomainParticipant’s Listener is used if one exists (see Section 7.2.6 and Section 8.3.5).

If you do not require asynchronous notification of data availability or status changes, you do not need to set a Listener for the DataReader. In that case, you will need to periodically call one of the read() or take() operations described in Section 7.4 to access the data that has been received.

Listeners are typically set up when the DataReader is created (see Section 7.3.1). You can also set one up after creation by using the DataReader’s get_listener() and set_listener() operations. Connext will invoke a DataReader’s Listener to report the status changes listed in Table 7.4 (if the Listener is set up to handle the particular status, see Section 7.3.4).

Table 7.4 DataReaderListener Callbacks

This DataReaderListener callback...

...is triggered by a change in this status:

 

 

 

 

on_data_available()

DATA_AVAILABLE Status (Section 7.3.7.1)

 

 

on_liveliness_changed()

LIVELINESS_CHANGED Status (Section 7.3.7.4)

 

 

on_requested_deadline_missed()

REQUESTED_DEADLINE_MISSED Status (Section 7.3.7.5)

 

 

on_requested_incompatible_qos()

REQUESTED_INCOMPATIBLE_QOS Status (Section 7.3.7.6)

 

 

on_sample_lost()

SAMPLE_LOST Status (Section 7.3.7.7)

 

 

on_sample_rejected()

SAMPLE_REJECTED Status (Section 7.3.7.8)

 

 

on_subscription_matched()

SUBSCRIPTION_MATCHED Status (Section 7.3.7.9)

 

 

Note that the same callbacks can be implemented in the SubscriberListener or

DomainParticipantListener instead. There is only one SubscriberListener callback that takes precedence over a DataReaderListener’s. An on_data_on_readers() callback in the

SubscriberListener (or DomainParticipantListener) takes precedence over the on_data_available() callback of a DataReaderListener.

If the SubscriberListener implements an on_data_on_readers() callback, it will be invoked instead of the DataReaderListener’s on_data_available() callback when new data arrives. The on_data_on_readers() operation can in turn cause the on_data_available() method of the

7-21

appropriate DataReaderListener to be invoked by calling the Subscriber’s notify_datareaders() operation. For more information on status and Listeners, see Listeners (Section 4.4).

Figure 7.10 shows a DataReaderListener that simply prints the data it receives.

Figure 7.10 Simple DataReaderListener

class MyReaderListener : public DDSDataReaderListener { public:

virtual void on_data_available(DDSDataReader* reader);

// don’t do anything for the other callbacks

};

void MyReaderListener::on_data_available(DDSDataReader* reader)

{

FooDataReader *Foo_reader = NULL;

FooSeq data_seq;

 

//

In C, sequences

have to

be initialized

DDS_SampleInfoSeq info_seq;

//

before use, see

Section

7.4.5.

DDS_ReturnCode_t

retcode;

 

 

 

 

int i;

// Must cast generic reader into reader of specific type Foo_reader = FooDataReader::narrow(reader);

if (Foo_reader == NULL) { printf("DataReader narrow error\n"); return;

}

retcode = Foo_reader->take(data_seq, info_seq,

DDS_LENGTH_UNLIMITED, DDS_ANY_SAMPLE_STATE,

DDS_ANY_VIEW_STATE, DDS_ANY_INSTANCE_STATE); if (retcode == DDS_RETCODE_NO_DATA) {

return;

} else if (retcode != DDS_RETCODE_OK) { printf("take error %d\n", retcode); return;

}

for (i = 0; i < data_seq.length(); ++i) {

//the data may not be valid if the sample is meta information

//about the creation or deletion of an instance

if (info_seq[i].valid_data) { FooTypeSupport::print_data(&data_seq[i]);

}

}

//Connext gave a pointer to internal memory via

//take(), must return the memory when finished processing the data retcode = Foo_reader->return_loan(data_seq, info_seq);

if (retcode != DDS_RETCODE_OK) { printf("return loan error %d\n", retcode);

}

}

7.3.5Checking DataReader Status and StatusConditions

You can access individual communication status for a DataReader with the operations shown in Table 7.5.

Table 7.5 DataReader Status Operations

Use this operation...

...to retrieve this status:

 

 

 

 

get_datareader_cache_status

DATA_READER_CACHE_STATUS (Section 7.3.7.2)

 

 

get_datareader_protocol_status

 

 

DATA_READER_PROTOCOL_STATUS (Section 7.3.7.3)

get_matched_publication_

datareader_protocol_status

 

 

 

get_liveliness_changed_status

LIVELINESS_CHANGED Status (Section 7.3.7.4)

 

 

get_sample_lost_status

SAMPLE_LOST Status (Section 7.3.7.7)

 

 

7-22

Table 7.5 DataReader Status Operations

Use this operation...

...to retrieve this status:

 

 

 

 

get_sample_rejected_status

SAMPLE_REJECTED Status (Section 7.3.7.8)

 

 

get_requested_deadline_missed_status

REQUESTED_DEADLINE_MISSED Status (Section 7.3.7.5)

 

 

get_requested_incompatible_qos_status

REQUESTED_INCOMPATIBLE_QOS Status (Section 7.3.7.6)

 

 

get_subscription_match_status

SUBSCRIPTION_MATCHED Status (Section 7.3.7.9)

 

 

get_status_changes

All of the above

 

 

get_statuscondition

See StatusConditions (Section 4.6.8)

 

 

These methods are useful in the event that no Listener callback is set to receive notifications of status changes. If a Listener is used, the callback will contain the new status information, in which case calling these methods is unlikely to be necessary.

The get_status_changes() operation provides a list of statuses that have changed since the last time the status changes were ‘reset.’ A status change is reset each time the application calls the corresponding get_*_status(), as well as each time Connext returns from calling the Listener callback associated with that status.

For more on status, see Setting Up DataReaderListeners (Section 7.3.4), Statuses for DataReaders (Section 7.3.7), and Listeners (Section 4.4).

7.3.6Waiting for Historical Data

The wait_for_historical_data() operation waits (blocks) until all "historical" data is received from matched DataWriters. "Historical" data means samples that were written before wait_for_historical_data() is called.

This operation is intended only for DataReaders that have:

DURABILITY QosPolicy (Section 6.5.7) kind set to TRANSIENT_LOCAL (not VOLATILE)

RELIABILITY QosPolicy (Section 6.5.19) kind set to RELIABLE.

Calling wait_for_historical_data() on a non-reliable DataReader will always return immediately, since Connext will never deliver historical data to non-reliable DataReaders.

As soon as an application enables a non-VOLATILE DataReader, it will start receiving both "historical" data as well as any new data written by matching DataWriters. If you want the subscribing application to wait until all "historical" data is received, use this operation:

DDS_ReturnCode_t wait_for_historical_data

(const DDS_Duration_t & max_wait)

The wait_for_historical_data() operation blocks the calling thread until either all "historical" data is received, or the duration specified by the max_wait parameter elapses, whichever happens first. A return value of OK indicates that all the "historical" data was received; a return value of "TIMEOUT" indicates that max_wait elapsed before all the data was received.

7.3.7Statuses for DataReaders

There are several types of statuses available for a DataReader. You can use the get_*_status() operations (Section 7.3.5) to access them, use a DataReaderListener (Section 7.3.4) to listen for changes in their values (for those statuses that have Listeners), or use a StatusCondition and a WaitSet (Section 4.6.8) to wait for changes. Each status has an associated data structure and is described in more detail in the following sections.

DATA_AVAILABLE Status (Section 7.3.7.1)

DATA_READER_CACHE_STATUS (Section 7.3.7.2)

7-23

DATA_READER_PROTOCOL_STATUS (Section 7.3.7.3)

LIVELINESS_CHANGED Status (Section 7.3.7.4)

REQUESTED_DEADLINE_MISSED Status (Section 7.3.7.5)

REQUESTED_INCOMPATIBLE_QOS Status (Section 7.3.7.6)

SAMPLE_LOST Status (Section 7.3.7.7)

SAMPLE_REJECTED Status (Section 7.3.7.8)

SUBSCRIPTION_MATCHED Status (Section 7.3.7.9)

7.3.7.1DATA_AVAILABLE Status

This status indicates that new data is available for the DataReader. In most cases, this means that one new sample has been received. However, there are situations in which more than one samples for the DataReader may be received before the DATA_AVAILABLE status changes. For example, if the DataReader has the DURABILITY QosPolicy (Section 6.5.7) set to be non- VOLATILE, then the DataReader may receive a batch of old data samples all at once. Or if data is being received reliably from DataWriters, Connext may present several samples of data simultaneously to the DataReader if they have been originally received out of order.

A change to this status also means that the DATA_ON_READERS status is changed for the

DataReader’s Subscriber.

This status is reset when you call read(), take(), or one of their variations.

Unlike most other statuses, this status (as well as DATA_ON_READERS for Subscribers) is a read communication status. See Section 7.2.9 and Section 4.3.1 for more information on read communication statuses.

The DataReaderListener’s on_data_available() callback is invoked when this status changes, unless the SubscriberListener (Section 7.2.6) or DomainParticipantListener (Section 8.3.5) has implemented an on_data_on_readers() callback. In that case, on_data_on_readers() will be invoked instead.

7.3.7.2DATA_READER_CACHE_STATUS

This status keeps track of the number of samples in the reader's cache.

This status does not have an associated Listener. You can access this status by calling the DataReader’s get_datareader_cache_status() operation, which will return the status structure described in Table 7.6.

Table 7.6 DDS_DataReaderCacheStatus

Type

Field Name

Description

 

 

 

 

 

 

DDS_Long

sample_count_peak

Highest number of samples in the DataReader’s queue over the

lifetime of the DataReader.

 

 

 

 

 

 

 

Current number of samples in the DataReader’s queue.

DDS_Long

sample_count

Includes samples that may not yet be available to be read or taken by

the user due to samples being received out of order or settings in the

 

 

 

 

PRESENTATION QosPolicy (Section 6.4.6).

 

 

 

7.3.7.3DATA_READER_PROTOCOL_STATUS

The status of a DataReader’s internal protocol related metrics (such as the number of samples received, filtered, rejected) and the status of wire protocol traffic. The structure for this status appears in Table 7.7 on page 7-25.

This status does not have an associated Listener. You can access this status by calling the following operations on the DataReader (all of which return the status structure described in Table 7.7):

7-24

get_datareader_protocol_status() returns the sum of the protocol status for all the matched publications for the DataReader.

get_matched_publication_datareader_protocol_status() returns the protocol status of a particular matched publication, identified by a publication_handle.

Note: Status for a remote entity is only kept while the entity is alive. Once a remote entity is no longer alive, its status is deleted. If you try to get the matched subscription status for a remote entity that is no longer alive, the ‘get status’ call will return an error.

Table 7.7 DDS_DataReaderProtocolStatus

Type

Field Name

Description

 

 

 

 

 

 

 

 

The number of user samples from a remote

 

received_sample_count

DataWriter received for the first time by a local

 

 

DataReader.

 

 

 

 

 

The incremental change in the number of user

 

received_sample_count_

samples from a remote DataWriter received for the

 

change

first time by a local DataReader since the last time the

DDS_LongLong

 

status was read.

 

 

 

The number of bytes of user samples from a remote

 

 

 

received_sample_bytes

DataWriter received for the first time by a local

 

 

DataReader.

 

 

 

 

 

The incremental change in the number of bytes of

 

received_sample_bytes_

user samples from a remote DataWriter received for

 

change

the first time by a local DataReader since the last time

 

 

the status was read.

 

 

 

 

duplicate_sample_count

The number of samples from a remote DataWriter

 

received, not for the first time, by a local DataReader.

 

 

 

 

 

 

 

The incremental change in the number of samples

 

duplicate_sample_count_

from a remote DataWriter received, not for the first

 

change

time, by a local DataReader since the last time the

 

 

status was read.

DDS_LongLong

 

 

 

The number of bytes of samples from a remote

 

duplicate_sample_bytes

DataWriter received, not for the first time, by a local

 

 

DataReader.

 

 

 

 

 

The incremental change in the number of bytes of

 

duplicate_sample_bytes_

samples from a remote DataWriter received, not for

 

change

the first time, by a local DataReader since the last time

 

 

the status was read.

 

 

 

 

 

The number of user samples filtered by the local

 

filtered_sample_count

DataReader due to ContentFilteredTopics or Time-

 

 

Based Filter.

 

 

 

 

 

The incremental change in the number of user

 

filtered_sample_count_

samples filtered by the local DataReader due to

 

change

Content-FilteredTopics or Time-Based Filter since the

DDS_LongLong

 

last time the status was read.

 

 

 

The number of bytes of user samples filtered by the

 

 

 

filtered_sample_bytes

local DataReader due to ContentFilteredTopics or

 

 

Time-Based Filter.

 

 

 

 

 

The incremental change in the number of bytes of

 

filtered_sample_bytes_

user samples filtered by the local DataReader due to

 

change

ContentFilteredTopics or Time-Based Filter since the

 

 

last time the status was read.

 

 

 

7-25

Table 7.7 DDS_DataReaderProtocolStatus

Type

Field Name

 

 

 

Description

 

 

 

 

 

 

 

 

 

received_heartbeat_count

The number of Heartbeats from a remote DataWriter

 

received by a local DataReader.

 

 

 

 

 

 

 

 

 

 

received_heartbeat_count_

The incremental change in the number of Heartbeats

 

from

a remote

DataWriter received by

a local

 

change

 

DataReader since the last time the status was read.

 

 

DDS_LongLong

 

 

received_heartbeat_bytes

The number of bytes of Heartbeats from a remote

 

DataWriter received by a local DataReader.

 

 

 

 

 

 

 

 

 

The incremental change in the number of bytes of

 

received_heartbeat_bytes_

Heartbeats from a remote DataWriter received by a

 

change

local DataReader since the last time the status was

 

 

read.

 

 

 

 

 

 

 

 

 

 

sent_ack_count

The number of ACKs sent from a local DataReader to a

 

matching remote DataWriter.

 

 

 

 

 

 

 

 

 

 

 

 

 

The incremental change in the number of ACKs sent

 

sent_ack_count_change

from a local DataReader to a matching remote

 

 

DataWriter since the last time the status was read.

DDS_LongLong

 

 

sent_ack_bytes

The number of bytes of ACKs sent from a local

 

DataReader to a matching remote DataWriter.

 

 

 

 

 

 

 

 

 

The incremental change in the number of bytes of

 

sent_ack_bytes_change

ACKs sent from a local DataReader to a matching

 

remote DataWriter since the last time the status was

 

 

 

 

read.

 

 

 

 

 

 

 

 

 

 

sent_nack_count

The number of NACKs sent from a local DataReader

 

to a matching remote DataWriter.

 

 

 

 

 

 

 

 

 

 

 

The incremental change in the number of NACKs

 

sent_nack_count_change

sent from a local DataReader to a matching remote

 

 

DataWriter since the last time the status was read.

DDS_LongLong

 

 

sent_nack_bytes

The number of bytes of NACKs sent from a local

 

DataReader to a matching remote DataWriter.

 

 

 

 

 

 

 

 

 

The incremental change in the number of bytes of

 

sent_nack_bytes_change

NACKs sent from a local DataReader to a matching

 

remote DataWriter since the last time the status was

 

 

 

 

read.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

received_gap_count

The

number

of

GAPs

received

from

remote

 

DataWriter to this DataReader.

 

 

 

 

 

 

 

 

 

 

 

The incremental change in the number of GAPs

 

received_gap_count_change

received from remote DataWriter to this DataReader

DDS_LongLong

 

since the last time the status was read.

 

 

 

 

 

 

 

 

 

 

received_gap_bytes

The number of bytes of GAPs received from remote

 

 

DataWriter to this DataReader.

 

 

 

 

 

 

 

 

 

 

 

The incremental change in the number of bytes of

 

received_gap_bytes_change

GAPs received from remote DataWriter to this

 

 

DataReader since the last time the status was read.

 

 

 

 

 

 

 

 

 

rejected_sample_count

The

number

of

times a

sample is

rejected for

 

unanticipated reasons in the receive path.

 

 

 

 

DDS_LongLong

 

 

rejected_sample_

The incremental change in the number of times a

 

sample is rejected for unanticipated reasons in the

 

count_change

 

receive path since the last time the status was read.

 

 

 

 

 

 

 

 

 

 

 

7-26

Table 7.7 DDS_DataReaderProtocolStatus

Type

Field Name

 

Description

 

 

 

 

 

 

 

first_available_sample_

Sequence number of the first available sample in a

 

matched

DataWriter's reliability queue. Applicable

 

sequence_number

 

only when retrieving matched DataWriter statuses.

 

 

 

 

 

 

last_available_sample_

Sequence number of the last available sample in a

 

matched

DataWriter's reliability queue. Applicable

 

sequence_number

 

only when retrieving matched DataWriter statuses.

 

 

 

 

 

DDS_

 

Sequence number of the last committed sample (i.e.

 

available

to be read or

taken) in a matched

SequenceNumber_t

 

 

DataWriter's reliability queue. Applicable only when

 

 

 

last_committed_sample_

retrieving matched DataWriter statuses.

 

For best-effort DataReaders,

this is the sequence

 

sequence_number

 

number of the latest sample received.

 

 

 

 

For reliable DataReaders, this is the sequence number

 

 

of the latest sample that is available to be read or

 

 

taken from the DataReader's queue.

 

 

 

 

 

Number of received samples that are not yet available

DDS_Long

uncommitted_sample_count

to be read or taken due to

being received out of

 

 

order. Applicable only when retrieving matched

 

 

DataWriter statuses.

 

 

 

 

 

 

7.3.7.4LIVELINESS_CHANGED Status

This status indicates that the liveliness of one or more matched DataWriters has changed (i.e., one or more DataWriters has become alive or not alive). The mechanics of determining liveliness between a DataWriter and a DataReader is specified in their LIVELINESS QosPolicy (Section 6.5.13).

The structure for this status appears in Table 7.8.

Table 7.8 DDS_LivelinessChangedStatus

Type

Field Name

Description

 

 

 

 

alive_count

Number of matched DataWriters that are currently alive.

 

 

 

 

not_alive_count

Number of matched DataWriters that are not currently alive.

 

 

 

DDS_Long

alive_count_change

The change in the alive_count since the last time the Listener

was called or the status was read.

 

 

 

 

 

 

not_alive_count_change

The change in the not_alive_count since the last time the

 

 

Listener was called or the status was read.

DDS_Instance

last_publication_handle

A handle to the last DataWriter to change its liveliness.

Handle_t

 

 

The DataReaderListener’s on_liveliness_changed() callback may be called for the following reasons:

Liveliness is truly lost—a sample has not been received within the time-frame specified in the LIVELINESS QosPolicy (Section 6.5.13) lease_duration.

Liveliness is recovered after being lost.

A new matching entity has been discovered.

A QoS has changed such that a pair of matching entities are no longer matching (such as a change to the PartitionQosPolicy). In this case, the middleware will no longer keep track of the entities’ liveliness. Furthermore:

If liveliness was maintained: alive_count will decrease and not_alive_count will remain the same.

7-27

If liveliness had been lost: alive_count will remain the same and not_alive_count will decrease.

You can also retrieve the value by calling the DataReader’s get_liveliness_changed_status() operation.

This status is reciprocal to the RELIABLE_READER_ACTIVITY_CHANGED Status (DDS Extension) (Section 6.3.6.8) for a DataWriter.

7.3.7.5REQUESTED_DEADLINE_MISSED Status

This status indicates that the DataReader did not receive a new sample for an data-instance within the time period set in the DataReader’s DEADLINE QosPolicy (Section 6.5.5). For non- keyed Topics, this simply means that the DataReader did not receive data within the DEADLINE period. For keyed Topics, this means that for one of the data-instances that the DataReader was receiving, it has not received a new sample within the DEADLINE period. For more information about keys and instances, see Section 2.2.2.

The structure for this status appears in Table 7.9.

Table 7.9 DDS_RequestedDeadlineMissedStatus

Type

Field Name

Description

 

 

 

 

 

 

 

total_count

Cumulative number of times that the deadline was violated for any

 

instance read by the DataReader.

DDS_Long

 

 

 

total_count_change

The change in total_count since the last time the Listener was called

 

 

or the status was read.

 

 

 

 

 

DDS_Instance

last_instance_handle

Handle to the last data-instance in the DataReader for which a

Handle_t

requested deadline was missed.

 

 

 

The DataReaderListener’s on_requested_deadline_missed() callback is invoked when this status changes. You can also retrieve the value by calling the DataReader’s get_requested_deadline_missed_status() operation.

7.3.7.6REQUESTED_INCOMPATIBLE_QOS Status

A change to this status indicates that the DataReader discovered a DataWriter for the same Topic, but that DataReader had requested QoS settings incompatible with this DataWriter’s offered QoS.

The structure for this status appears in Table 7.10.

Table 7.10 DDS_RequestedIncompatibleQosStatus

Type

Field Name

Description

 

 

 

 

 

Cumulative number of times the DataReader discovered

DDS_Long

total_count

a DataWriter for the same Topic with an offered QoS

that is incompatible with that requested by the

 

 

 

 

DataReader.

 

 

 

DDS_Long

total_count_change

The change in total_count since the last time the

Listener was called or the status was read.

 

 

 

 

 

 

 

The ID of the QosPolicy that was found to be

DDS_QosPolicyId_t

last_policy_id

incompatible the last time an incompatibility was

detected. (Note: if there are multiple incompatible

 

 

 

 

policies, only one of them is reported here.)

 

 

 

 

 

A list containing—for each policy—the total number of

DDS_QosPolicyCountSeq

policies

times that the DataReader discovered a DataWriter for

the same Topic with a offered QoS that is incompatible

 

 

 

 

with that requested by the DataReader.

 

 

 

7-28

The DataReaderListener’s on_requested_incompatible_qos() changes. You can also retrieve the value get_requested_incompatible_qos_status() operation.

callback is invoked when this status by calling the DataReader’s

7.3.7.7SAMPLE_LOST Status

This status indicates that one or more samples written by a matched DataWriter have failed to be received.

For a DataReader, when there are insufficient resources to accept incoming samples of data, samples may be dropped by the receiving application. Those samples are considered to be REJECTED (see Section 7.3.7.8). But DataWriters are limited in the number of published data samples that they can store, so that if a DataWriter continues to publish data samples, new data may overwrite old data that have not yet been received by the DataReader. The samples that are overwritten can never be resent to the DataReader and thus are considered to be lost.

This status applies to reliable and best-effort DataReaders, see the RELIABILITY QosPolicy (Section 6.5.19).

The structure for this status appears in Table 7.11.

Table 7.11 DDS_SampleLostStatus

 

Type

 

Field Name

Description

 

 

 

 

 

 

 

 

 

 

 

 

 

 

total_count

 

Cumulative count of all the samples that have been

 

 

 

lost, across all instances of data written for the Topic.

 

 

 

 

 

 

DDS_Long

 

 

 

 

 

 

 

 

The incremental number of samples lost since the

 

 

total_count_change

last time the Listener was called or the status was

 

 

 

 

 

read.

 

 

 

 

 

 

DDS_SampleLostStatusKind

last_reason

 

The reason the last sample was lost. See Table 7.12.

 

 

 

 

 

 

The reason the sample was lost appears in the last_reason field. The possible values are listed in

 

Table 7.12.

 

 

 

Table 7.12 DDS_SampleLostStatusKind

 

 

 

 

 

 

 

 

 

Reason Kind

 

 

Description

 

 

 

 

 

 

 

 

 

NOT_LOST

 

The sample was not lost.

 

 

 

 

LOST_BY_AVAILABILITY_WAITING_TIME

AvailabilityQosPolicy’s

 

 

 

 

max_data_availability_waiting_time expired.

 

LOST_BY_INCOMPLETE_COHERENT_SET

A sample is lost because it is part of an incomplete

 

 

 

 

coherent set.

 

LOST_BY_INSTANCES_LIMIT

 

A resource limit on the number of instances was reached.

 

 

 

 

LOST_BY_LARGE_COHERENT_SET

A sample is lost because it is part of a large coherent set.

 

 

 

 

 

 

LOST_BY_REMOTE_WRITER_SAMPLES_

A resource limit on the number of samples published by a

 

remote writer on behalf of a virtual writer that a

 

PER_VIRTUAL_QUEUE_LIMIT"

 

 

 

DataReader may store was reached.

 

 

 

 

 

 

 

 

 

 

LOST_BY_REMOTE_WRITERS_PER_

A resource limit on the number of remote writers for a

 

single instance from which a DataReader may read was

 

INSTANCE_LIMIT

 

 

 

reached.

 

 

 

 

 

 

 

 

LOST_BY_REMOTE_WRITERS_PER_

A resource limit on the number of remote writers per

 

SAMPLE_LIMIT

 

sample was reached.

 

 

 

 

LOST_BY_SAMPLES_PER_REMOTE_

A resource limit on the number of samples from a given

 

WRITER_LIMIT

 

remote writer that a DataReader may store was reached.

 

 

 

 

 

 

7-29

Table 7.12 DDS_SampleLostStatusKind

Reason Kind

Description

LOST_BY_VIRTUAL_WRITERS_LIMIT

A resource limit on the number of virtual writers from which a DataReader may read was reached.

LOST_BY_WRITER

A DataWriter removed the sample before being received by the DataReader.

The DataReaderListener’s on_sample_lost() callback is invoked when this status changes. You can also retrieve the value by calling the DataReader’s get_sample_lost_status() operation.

7.3.7.8SAMPLE_REJECTED Status

This status indicates that one or more samples received from a matched DataWriter have been dropped by the DataReader because a resource limit would have been exceeded. For example, if the receive queue is full, the number of samples in the queue is equal to the max_samples parameter of the RESOURCE_LIMITS QosPolicy (Section 6.5.20).

The structure for this status appears in Table 7.13. The reason the sample was rejected appears in the last_reason field. The possible values are listed in Table 7.14.

Table 7.13 DDS_SampleRejectedStatus

 

Type

Field Name

 

Description

 

 

 

 

 

 

 

 

 

 

total_count

Cumulative count of all the samples that have

 

 

 

been rejected by the DataReader.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

The incremental number of samples rejected

 

 

 

total_count_change

since the last time the Listener was called or

 

 

DDS_Long

 

the status was read.

 

 

 

 

 

 

 

 

 

 

 

current_count

The current number of writers with which the

 

 

 

 

 

 

DataReader is matched.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

The change in current_count since the last

 

 

 

current_count_change

time the Listener was called or the status was

 

 

 

 

read.

 

 

 

 

 

 

 

 

 

 

 

DDS_SampleRejectedStatusKind

last_reason

Reason for rejecting the last sample. See

 

 

Table 7.14.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

DDS_InstanceHandle_t

last_instance_handle

Handle to the data-instance for which the last

 

 

sample was rejected.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Table 7.14 DDS_SampleRejectedStatusKind

 

 

 

 

 

 

 

 

 

 

 

 

 

Reason Kind

Description

Related QosPolicy

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

DDS_NOT_REJECTED

Sample was accepted.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

A resource limit on the number of

 

 

 

 

 

DDS_REJECTED_BY_

instances that can be handled at the

RESOURCE_LIMITS QosPolicy

 

INSTANCES_LIMIT

same time by the DataReader was

(Section 6.5.20)

 

 

 

 

reached.

 

 

 

 

 

 

 

 

 

 

 

 

 

DDS_REJECTED_BY_

A resource limit on the number of

 

 

 

 

 

DataWriters from which a DataReader

 

 

 

 

 

REMOTE_WRITERS_LIMIT

 

 

 

 

 

may read was reached.

 

DATA_READER_RESOURCE_

 

 

 

 

DDS_REJECTED_BY_

A resource limit on the number of

LIMITS

QosPolicy

(DDS

 

DataWriters for a single instance from

Extension) (Section 7.6.2)

 

 

 

REMOTE_WRITERS_

 

 

 

which a DataReader may read was

 

 

 

 

 

PER_INSTANCE_LIMIT

 

 

 

 

 

reached.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

7-30

Table 7.14 DDS_SampleRejectedStatusKind

Reason Kind

 

Description

 

 

Related QosPolicy

 

 

 

 

 

 

DDS_REJECTED_BY_

A resource limit on the total number

 

SAMPLES_LIMIT

of samples was reached.

 

 

RESOURCE_LIMITS QosPolicy

 

 

 

 

 

 

DDS_REJECTED_BY_

 

 

 

 

 

A resource limit

on the

number

of

(Section 6.5.20)

SAMPLES_PER_

samples per instance was reached.

 

 

INSTANCE_LIMIT

 

 

 

 

 

 

 

 

 

 

 

 

 

DDS_REJECTED_BY_

A resource limit on the

number

of

 

samples that a DataReader may store

 

SAMPLES_PER_

 

from a

specific

DataWriter was

 

REMOTE_WRITER_LIMIT

 

reached.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

DDS_REJECTED_BY_

A resource limit on the

number

of

 

virtual

writers

from

which

a

 

VIRTUAL_WRITERS_LIMIT

DATA_READER_RESOURCE_

DataReader may read was reached.

 

 

 

LIMITS QosPolicy (DDS

 

 

 

 

 

 

DDS_REJECTED_BY_

A resource limit on the number of

Extension) (Section 7.6.2)

REMOTE_WRITERS_

remote writers per sample was

 

PER_SAMPLE_LIMIT

reached.

 

 

 

 

 

 

 

 

 

 

DDS_REJECTED_BY_

A resource limit on the

number

of

 

samples published by a remote writer

 

REMOTE_WRITER_SAMPLES_

 

PER_VIRTUAL_QUEUE_LIMIT

on behalf of a virtual writer that a

 

 

DataReader may store was reached.

 

 

The DataReaderListener’s on_sample_rejected()

You can also retrieve the value by calling operation.

callback is invoked when this status changes. the DataReader’s get_sample_rejected_status()

7.3.7.9SUBSCRIPTION_MATCHED Status

A change to this status indicates that the DataReader discovered a matching DataWriter. A ‘match’ occurs only if the DataReader and DataWriter have the same Topic, same data type (implied by having the same Topic), and compatible QosPolicies. In addition, if user code has directed Connext to ignore certain DataWriters, then those DataWriters will never be matched. See Section 16.4.2 for more on setting up a DomainParticipant to ignore specific DataWriters.

The structure for this status appears in Table 7.15.

Table 7.15 DDS_SubscriptionMatchedStatus

Type

Field Name

Description

 

 

 

 

 

 

 

total_count

Cumulative number of times the DataReader discovered a

 

"match" with a DataWriter.

 

 

 

 

 

 

total_count_change

The change in total_count since the last time the Listener was

 

called or the status was read.

 

 

 

 

 

DDS_Long

current_count

The number of DataWriters currently matched to the concerned

 

DataReader.

 

 

 

 

 

 

current_count_change

The change in current_count since the last time the listener was

 

 

called or the status was read.

 

current_count_peak

The highest value that current_count has reached until now.

 

 

 

DDS_Instance

last_publication_

Handle to the last DataWriter that matched the DataReader

Handle_t

handle

causing the status to change.

 

 

 

The DataReaderListener’s on_subscription_matched() callback is invoked when this status changes. You can also retrieve the value by calling the DataReader’s get_subscription_match_status() operation.

7-31

7.3.8Setting DataReader QosPolicies

A DataReader’s QosPolicies control its behavior. Think of QosPolicies as the ‘properties’ for the DataReader. The DDS_DataReaderQos structure has the following format:

struct DDS_DataReaderQos {

 

DDS_DurabilityQosPolicy

durability;

DDS_DeadlineQosPolicy

deadline;

DDS_LatencyBudgetQosPolicy

latency_budget;

DDS_LivelinessQosPolicy

liveliness;

DDS_ReliabilityQosPolicy

reliability;

DDS_DestinationOrderQosPolicy

destination_order;

DDS_HistoryQosPolicy

history;

DDS_ResourceLimitsQosPolicy

resource_limits;

DDS_UserDataQosPolicy

user_data;

DDS_TimeBasedFilterQosPolicy

time_based_filter;

DDS_ReaderDataLifecycleQosPolicy

reader_data_lifecycle;

DDS_TypeConsistencyEnforcementQosPolicy

type_consistency;

// Extensions to the DDS standard:

 

DDS_DataReaderResourceLimitsQosPolicy

reader_resource_limits;

DDS_DataReaderProtocolQosPolicy

protocol;

DDS_TransportSelectionQosPolicy

transport_selection;

DDS_TransportUnicastQosPolicy

unicast;

DDS_TransportMulticastQosPolicy

multicast;

DDS_PropertyQosPolicy

property;

DDS_AvailabilityQosPolicy

availability;

DDS_EntityNameQosPolicy

subscription_name;

DDS_TypeSupportQosPolicy

type_support;

};

 

Note: set_qos() cannot always be used within a listener callback, see Restricted Operations in Listener Callbacks (Section 4.5.1).

Table 7.16 summarizes the meaning of each policy. (They appear alphabetically in the table.) For information on why you would want to change a particular QosPolicy, see the referenced section. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 7.16 DataReader QosPolicies

QosPolicy

Description

 

 

 

This QoS policy is used in the context of two features:

 

For a Collaborative DataWriter, specifies the group of DataWriters

 

expected to collaboratively provide data and the timeouts that

Availability

control when to allow data to be available that may skip samples.

For a Durable Subscription, configures a set of Durable Subscriptions

 

 

on a DataWriter.

 

See Section 6.5.1

 

 

DataReaderProtocol

This QosPolicy configures the DDS on-the-network protocol, RTPS.

See Section 7.6.1.

 

 

 

DataReaderResourceLimits

Various settings that configure how DataReaders allocate and use

physical memory for internal resources. See Section 7.6.2.

 

 

 

 

For a DataReader, specifies the maximum expected elapsed time

 

between arriving data samples.

Deadline

For a DataWriter, specifies a commitment to publish samples with no

 

greater elapsed time between them.

 

See Section 6.5.5.

 

 

 

Controls how Connext will deal with data sent by multiple

DestinationOrder

DataWriters for the same topic. Can be set to "by reception

 

timestamp" or to "by source timestamp". See Section 6.5.6.

 

 

7-32

Table 7.16 DataReader QosPolicies

QosPolicy

Description

 

 

 

 

Durability

Specifies whether or not Connext will store and deliver data that were

previously published to new DataReaders. See Section 6.5.7.

 

 

 

EntityName

Assigns a name to a DataReader. See Section 6.5.9.

 

 

 

Specifies how much data must to stored by Connextfor the DataWriter

History

or DataReader. This QosPolicy affects the RELIABILITY QosPolicy

(Section 6.5.19) as well as the DURABILITY QosPolicy (Section 6.5.7).

 

 

See Section 6.5.10.

 

 

LatencyBudget

Suggestion to Connext on how much time is allowed to deliver data.

See Section 6.5.11.

 

 

 

 

Specifies and configures the mechanism that allows DataReaders to

Liveliness

detect when DataWriters become disconnected or "dead." See

 

Section 6.5.13.

 

 

 

Stores name/value (string) pairs that can be used to configure certain

 

parameters of Connext that are not exposed through formal QoS

Property

policies. It can also be used to store and propagate application-

 

specific name/value pairs, which can be retrieved by user code

 

during discovery. See Section 6.5.17.

 

 

ReaderDataLifeCycle

Controls how a DataReader manages the lifecycle of the data that it

has received. See Section 7.6.3.

 

 

 

Reliability

Specifies whether or not Connext will deliver data reliably. See

Section 6.5.19.

 

 

 

 

Controls the amount of physical memory allocated for entities, if

ResourceLimits

dynamic allocations are allowed, and how they occur. Also controls

memory usage among different instance values for keyed topics. See

 

 

Section 6.5.20.

 

 

TimeBasedFilter

Set by a DataReader to limit the number of new data values received

over a period of time. See Section 7.6.4.

 

 

 

 

Specifies the multicast address on which a DataReader wants to

TransportMulticast

receive its data. Can specify a port number as well as a subset of the

available transports with which to receive the multicast data. See

 

 

Section 7.6.5.

 

 

TransportSelection

Allows you to select which physical transports a DataWriter or

DataReader may use to send or receive its data. See Section 6.5.22.

 

 

 

TransportUnicast

Specifies a subset of transports and port number that can be used by

an Entity to receive data. See Section 6.5.23.

 

 

 

 

Used to attach application-specific value(s) to a DataWriter or

TypeSupport

DataReader. These values are passed to the serialization or

 

deserialization routine of the associated data type. See Section 6.5.24.

 

 

 

Defines rules that determine whether the type used to publish a

TypeConsistencyEnforcement

given data stream is consistent with that used to subscribe to it. See

 

Section 7.6.6.

 

Along with Topic Data QosPolicy and Group Data QosPolicy, used to

UserData

attach a buffer of bytes to Connext's discovery meta-data. See

 

Section 6.5.25.

 

 

For a DataReader to communicate with a DataWriter, their corresponding QosPolicies must be compatible. For QosPolicies that apply both to the DataWriter and the DataReader, the setting in the DataWriter is considered what the DataWriter “offers” and the setting in the DataReader is what the DataReader “requests.” Compatibility means that what is offered by the DataWriter equals or surpasses what is requested by the DataReader. See QoS Requested vs. Offered Compatibility—the RxO Property (Section 4.2.1).

7-33

Some of the policies may be changed after the DataReader has been created. This allows the application to modify the behavior of the DataReader while it is in use. To modify the QoS of an existing DataReader, use the get_qos() and set_qos() operations on the DataReader. This is a general pattern for all Entities, described in more detail in Section 4.1.7.3.

7.3.8.1Configuring QoS Settings when the DataReader is Created

As described in Creating DataReaders (Section 7.3.1), there are different ways to create a

DataReader, depending on how you want to specify its QoS (with or without a QoS Profile).

In Figure 7.9 on page 7-20, we saw an example of how to create a DataReader with default QosPolicies by using the special constant, DDS_DATAREADER_QOS_DEFAULT, which indicates that the default QoS values for a DataReader should be used. The default

DataReader QoS values are configured in the Publisher or DomainParticipant; you can change them with set_default_datareader_qos() or set_default_datareader_qos_with_profile(). Then any DataReaders created with the

Subscriber will use the new default values. As described in Section 4.1.7, this is a general pattern that applies to the construction of all Entities.

To create a DataReader with non-default QoS without using a QoS Profile, see the example code in Figure 7.11 on page 7-34. It uses the Publisher’s get_default_reader_qos() method to initialize a DDS_DataReaderQos structure. Then, the policies are modified from their default values before the structure is used in the create_datareader() method.

You can also create a DataReader and specify its QoS settings via a QoS Profile. To do so, you will call create_datareader_with_profile(), as seen in Figure 7.12 on page 7-35.

If you want to use a QoS profile, but then make some changes to the QoS before creating the DataReader, call get_datareader_qos_from_profile() and create_datareader() as seen in Figure 7.13 on page 7-35.

For more information, see Creating DataReaders (Section 7.3.1) and Chapter 17: Configuring QoS with XML.

Figure 7.11 Creating a DataReader with Modified QosPolicies (not from a profile)

DDS_DataReaderQos reader_qos;1

//initialize reader_qos with default values subscriber->get_default_datareader_qos(reader_qos);

//make QoS changes here

reader_qos.history.depth = 5;

// Create the reader with modified qos

DDSDataReader * reader = subscriber->create_datareader( topic, reader_qos,

NULL, DDS_STATUS_MASK_NONE);

if (reader == NULL) { // ... error

}

// narrow it for your specific data type

FooDataReader* foo_reader = FooDataReader::narrow(reader);

1.Note: In C, you must initialize the QoS structures before they are used, see Section 4.2.2.

7.3.8.2Changing QoS Settings After DataReader Has Been Created

There are 2 ways to change an existing DataReader’s QoS after it is has been created—again depending on whether or not you are using a QoS Profile.

7-34

Figure 7.12 Creating a DataReader with a QoS Profile

// Create the datareader DDSDataReader * reader =

subscriber->create_datareader_with_profile( topic,

“MyReaderLibrary”,

“MyReaderProfile”,

NULL, DDS_STATUS_MASK_NONE);

if (reader == NULL) { // ... error

};

// narrow it for your specific data type

FooDataReader* foo_reader = FooDataReader::narrow(reader);

Figure 7.13 Getting QoS Values from a Profile, Changing QoS Values, Creating a DataReader with Modified QoS Values

DDS_DataReaderQos reader_qos;1

// Get reader QoS from profile

retcode = factory->get_datareader_qos_from_profile( reader_qos, “ReaderProfileLibrary”, “ReaderProfile”);

if (retcode != DDS_RETCODE_OK) { // handle error

}

// Makes QoS changes here reader_qos.history.depth = 5;

DDSDataReader * reader = subscriber->create_datareader( topic,reader_qos,

NULL, DDS_STATUS_MASK_NONE);

if (reader == NULL) { // handle error

}

1.Note: In C, you must initialize the QoS structures before they are used, see Section 4.2.2.

To change QoS programmatically (that is, without using a QoS Profile), use get_qos() and set_qos(). See the example code in Figure 7.14. It retrieves the current values by calling the DataReader’s get_qos() operation. Then it modifies the value and calls set_qos() to apply the new value. Note, however, that some QosPolicies cannot be changed after the DataReader has been enabled—this restriction is noted in the descriptions of the individual QosPolicies.

You can also change a DataReader’s (and all other Entities’) QoS by using a QoS Profile and calling set_qos_with_profile(). For an example, see Figure 7.15. For more information, see Chapter 17: Configuring QoS with XML.

7.3.8.3Using a Topic’s QoS to Initialize a DataWriter’s QoS

Several DataReader QosPolicies can also be found in the QosPolicies for Topics (see Section 5.1.3). The QosPolicies set in the Topic do not directly affect the DataReaders (or DataWriters) that use that Topic. In many ways, some QosPolicies are a Topic-level concept, even though the DDS standard allows you to set different values for those policies for different DataReaders and

7-35

Figure 7.14 Changing the QoS of an Existing DataReader (without a QoS Profile)

DDS_DataReaderQos reader_qos;1

// Get current QoS.

if (datareader->get_qos(reader_qos) != DDS_RETCODE_OK) { // handle error

}

//Makes QoS changes here reader_qos.history.depth = 5;

//Set the new QoS

if (datareader->set_qos(reader_qos) != DDS_RETCODE_OK ) { // handle error

}

1.For the C API, you need to use DDS_ParticipantQos_INITIALIZER or DDS_ParticipantQos_initialize(). See Special QosPolicy Handling Considerations for C (Section 4.2.2)

Figure 7.15 Changing the QoS of an Existing DataReader with a QoS Profile

retcode = datareader->set_qos_with_profile( “ReaderProfileLibrary”,”ReaderProfile”);

if (retcode != DDS_RETCODE_OK) { // handle error

}

DataWriters of the same Topic. Thus, the policies in the DDS_TopicQos structure exist as a way to help centralize and annotate the intended or suggested values of those QoSs. Connext does not check to see if the actual policies set for a DataReader is aligned with those set in the Topic to which it is bound.

There are many ways to use the QosPolicies’ values set in the Topic when setting the QosPolicies’ values in a DataReader. The most straight forward way is to get the values of policies directly from the Topic and use them in the policies for the DataReader. Figure 6.21 on page 6-50 shows an example of how to this for a DataWriter; the pattern applies to DataReaders as well.

The Subscriber’s copy_from_topic_qos() operation can be used to copy all the common policies from the Topic QoS to a DataReaderQoS, as illustrated in Figure 6.22 on page 6-51 for

DataWriters.

The special macro, DDS_DATAREADER_QOS_USE_TOPIC_QOS, can be used to indicate that the DataReader should be created with the QoS that results from modifying the default DataReader QoS with the values specified by the Topic. See Figure 6.23 on page 6-52 and Figure 6.24 on page 6-52 for examples involving DataWriters. The same pattern applies to DataReaders. For more information on the use and manipulation of QoS, see Section 4.1.7.

7.3.9Navigating Relationships Among Entities

7.3.9.1Finding Matching Publications

The following DataReader operations can be used to get information about the DataWriters that will send data to this DataReader.

get_matched_publications()

get_matched_publication_data()

The get_matched_publications() operation will return a sequence of handles to matched DataWriters. You can use these handles in the get_matched_publication_data() method to get information about the DataWriter such as the values of its QosPolicies.

7-36

Note that DataWriter that have been ignored using the DomainParticipant’s ignore_publication() operation are not considered to be matched even if the DataWriter has the same Topic and compatible QosPolicies. Thus, they will not be included in the list of DataWriters returned by get_matched_publications(). See Section 16.4.2 for more on ignore_publication().

You can also get the DATA_READER PROTOCOL_STATUS for matching publications with get_matched_publication_datareader_protocol_status() (see Section 7.3.7.3).

Notes:

Status/data for a matched publication is only kept while the matched publication is alive. Once a matched publication is no longer alive, its status is deleted. If you try to get the status/data for a matched publication that is no longer alive, the 'get data' or 'get status' call will return an error.

The get_matched_publication_data() operation does not retrieve the type_code or property fields from built-in-topic data structures. This information is available through the on_data_available() callback (if a DataReaderListener is installed on the PublicationBuiltinTopicDataDataReader).

7.3.9.2Finding a DataReader’s Related Entities

These DataReader operations are useful for obtaining a handle to various related entities:

get_subscriber()

get_topicdescription()

The get_subscriber() operation returns the Subscriber that created the DataReader. get_topicdescription() returns the Topic with which the DataReader is associated.

7.3.9.3Looking Up an Instance Handle

Some operations, such as read_instance() and take_instance(), take an instance_handle parameter. If you need to get such as handle, you can call the lookup_instance() operation, which takes an instance as a parameter and returns a handle to that instance.

7.3.9.4Getting the Key Value for an Instance

If you have a handle to a data-instance, you can use the FooDataReader’s get_key_value() operation to retrieve the key for that instance. The value of the key is decomposed into its constituent fields and returned in a Foo structure. For information on keys and keyed data types, please see Section 2.2.2.

7.4Using DataReaders to Access Data (Read & Take)

For user applications to access the data received for a DataReader, they must use the type-specific derived class or set of functions in the C API. Thus for a user data type ‘Foo’, you must use methods of the FooDataReader class. The type-specific class or functions are automatically generated if you use rtiddsgen. Else, you will have to create them yourself, see Section 3.8.5.1 for more details.

7.4.1Using a Type-Specific DataReader (FooDataReader)

Using a Subscriber you will create a DataReader associating it with a specific data type, for example ‘Foo’. Note that the Subscriber’s create_datareader() method returns a generic DataReader. When your code is ready to access data samples received for the DataReader, you must use type-specific operations associated with the FooDataReader, such as read() and take().

7-37

To cast the generic DataReader returned by create_datareader() into an object of type FooDataReader, you should use the type-safe narrow() method of the FooDataReader class. narrow() will make sure that the generic DataReader passed to it is indeed an object of the FooDataReader class before it makes the cast. Else, it will return NULL. Figure 7.8 on page 7-14 shows an example:

Foo_reader = FooDataReader::narrow(reader);

Table 7.3, “DataReader Operations,” on page 7-17 lists type-specific operations using a FooDataReader. Also listed are generic, non-type specific operations that can be performed using the base class object DDSDataReader (or DDS_DataReader in C). In C, you must pass a pointer to a DDS_DataReader to those generic functions.

7.4.2Loaning and Returning Data and SampleInfo Sequences

The read() and take() operations (and their variations) return information to your application in two sequences:

received data samples in a sequence of the data type

corresponding information about each sample in a SampleInfo sequence

These sequences are parameters that are passed by your code into the read() and take() operations. If you use empty sequences (sequences that are initialized but have a maximum length of 0), Connext will fill those sequences with memory directly loaned from the receive queue itself. There is no copying of the data or of SampleInfo when the contents of the sequences are loaned. This is certainly the most efficient way for your code to retrieve the data.

However when you do so, your code must return the loaned sequences back to Connext so that they can be reused by the receive queue. If your code does not return the loan by calling the FooDataReader’s return_loan() method, then Connext will eventually run out of memory to store data samples received from the network for that DataReader. See Figure 7.16 for an example of borrowing and returning loaned sequences.

DDS_ReturnCode_t return_loan(FooSeq &received_data,

DDS_SampleInfoSeq &info_seq);

If your code provides its own sequences to the read/take operations, then Connext will copy the data from the receive queue. In that case, you do not have to call return_loan() when you are finished with the data. However, you must make sure the following is true, or the read/take operation will fail with a return code of DDS_RETCODE_PRECONDITION_NOT_MET:

The received_data of type FooSeq and info_seq of type DDS_SampleInfoSeq passed in as parameters have the same maximum size (length).

The maximum size (length) of the sequences are less than or equal to the passed in parameter, max_samples.

7.4.3Accessing Data Samples with Read or Take

To access the data samples that Connext has received for a DataReader, you must invoke the read() or take() methods. These methods return a list (sequence) of data samples and additional information about the samples in a corresponding list (sequence) of SampleInfo structures. The contents of SampleInfo are described in Section 7.4.6.

The way Connext builds the collection of samples depends on QoS policies set on the DataReader and Subscriber, the source_timestamp of the samples, and the sample_states, view_states, and instance_states parameters passed to the read/take operation.

In read() and take(), you may enter parameters so that Connext selectively returns data samples currently stored in the DataReader’s receive queue. You may want Connext to return all of the data in a single list or only a subset of the available samples as configured using the

7-38

Figure 7.16 Using Loaned Sequences in read() and take()

//In C++ and Java, sequences are automatically initialized

//to be empty

FooSeq data_seq;1 DDS_SampleInfoSeq info_seq; DDS_ReturnCode_t retcode;

...

//with empty sequences, a take() or read() will return loaned

//sequence elements

retcode = Foo_reader->take(data_seq, info_seq, DDS_LENGTH_UNLIMITED, DDS_ANY_SAMPLE_STATE, DDS_ANY_VIEW_STATE, DDS_ANY_INSTANCE_STATE);

... // process the returned data

// must return the loaned sequences when done processing Foo_reader->return_loan(data_seq, info_seq);

...

1.In the C API, you must use the FooSeq_initialize() and DDS_SampleInfoSeq_initialize() operations or the macro DDS_SEQUENCE_INITIALIZER to initialize the FooSeq and DDS_SampleInfoSeq to be empty. For example,

DDS_SampleInfoSeq infoSeq; DDS_SampleInfoSeq_initialize(&infoSeq); or

FooSeq fooSeq = DDS_SEQUENCE_INITIALIZER;

sample_states, view_states, and instance_states masks. Section 7.4.6 describes how these masks are used to determine which data samples should be returned.

7.4.3.1Read vs. Take

The difference between read() and take() is how Connext treats the data that is returned. With take(), Connext will remove the data from the DataReader’s receive queue. The data returned by Connext is no longer stored by Connext. With read(), Connext will continue to store the data in the DataReader’s receive queue. The same data may be read again until it is taken in subsequent take() calls. Note that the data stored in the DataReader’s receive queue may be overwritten, even if it has not been read, depending on the setting of the HISTORY QosPolicy (Section 6.5.10).

The read() and take() operations are non-blocking calls, so that they may return no data (DDS_RETCODE_NO_DATA) if the receive queue is empty or has no data that matches the criteria specified by the StateMasks.

The read_w_condition() and take_w_condition() operations take a ReadCondition as a parameter instead of sample, view or instance states. The only samples returned will be those for which the ReadCondition is TRUE. These operations, in conjunction with ReadConditions and a WaitSet, allow you to perform ‘waiting reads.’ For more information, see ReadConditions and QueryConditions (Section 4.6.7).

As you will see, read and take have the same parameters:

DDS_ReturnCode_t read(

 

FooSeq

&received_data_seq,

DDS_SampleInfoSeq

&info_seq,

DDS_Long

max_samples,

DDS_SampleStateMask

sample_states,

DDS_ViewStateMask

view_states,

DDS_InstanceStateMask

instance_states);

DDS_ReturnCode_t take(

 

FooSeq

&received_data_seq,

DDS_SampleInfoSeq

&info_seq,

DDS_Long

max_samples,

DDS_SampleStateMask

sample_states,

7-39

DDS_ViewStateMask

view_states,

DDS_InstanceStateMask

instance_states);

Note: These operations may loan internal Connext memory, which must be returned with return_loan(). See Loaning and Returning Data and SampleInfo Sequences (Section 7.4.2).

Both operations return an ordered collection of data samples (in the received_data_seq parameter) and information about each sample (in the info_seq parameter). Exactly how they are ordered depends on the setting of the PRESENTATION QosPolicy (Section 6.4.6) and the DESTINATION_ORDER QosPolicy (Section 6.5.6). For more details please see the API Reference HTML documentation for read() and take().

In read() and take(), you can use the sample_states, view_states, and instance_states parameters to specify properties that are used to select the actual samples that are returned by those methods. With different combinations of these three parameters, you can direct Connext to return all data samples, data samples that you have not accessed before, the data samples of instances that you have not seen before, data samples of instances that have been disposed, etc. The possible values for the different states are described both in the API Reference HTML documentation and in Section 7.4.6.

Table 7.17 lists the variations of the read() and take() operations.

Table 7.17 Read and Take Operations

Read Operations

Take Operations

 

Description

 

Reference

 

 

 

 

 

 

Reads/takes a collection of data samples

 

read

take

from the DataReader.

 

Section 7.4.3

Can be used for both keyed and non-

 

 

keyed data types.

 

 

 

 

 

 

 

 

 

Identical to read() and take(), but all

 

 

 

returned samples belong to a single

 

read_instance

take_instance

instance, which you specify as a

Section 7.4.3.4

 

 

parameter.

 

 

 

 

 

 

Can only be used with keyed data types.

 

 

 

 

 

 

 

 

 

 

Identical

to

read_instance()

and

 

read_instance_

take_instance_

take_instance(), but all returned samples

Section 7.4.3.7

w_condition

w_condition

belong to the single specified instance

 

 

and satisfy the specified ReadCondition.

 

 

 

 

 

 

 

 

 

 

Similar

to

read_instance()

and

 

 

 

take_instance(), but the actual instance is

 

 

 

not directly specified as a parameter.

 

read_next_instance

take_next_instance

Instead, the samples will all belong to

Section 7.4.3.5

 

 

instance ordered after the instance that is

 

 

 

specified by the previous_handle

 

 

 

parameter.

 

 

 

 

 

 

 

 

read_next_instance_

take_next_instance_

Accesses a collection of data samples of

 

the next instance that match a specific set

Section 7.4.3.8

w_condition

w_condition

of ReadConditions, from the DataReader.

 

 

 

 

 

 

 

 

 

 

Provide a convenient way to access

 

read_next_sample

take_next_sample

the next data sample in the receive

Section 7.4.3.3

queue that has not been accessed

 

 

before.

 

 

 

 

 

 

 

 

 

 

Accesses a collection of data samples from

 

read_w_condition

take_w_condition

the DataReader that match specific

Section 7.4.3.6

 

 

ReadCondition criteria.

 

 

 

 

 

 

 

 

 

7-40

7.4.3.2General Patterns for Accessing Data

Once the data samples are available to the data readers, the samples can be read or taken by the application. The basic rule is that the application may do this in any order it wishes. This approach is very flexible and allows the application ultimate control.

To access data coherently, or in order, the PRESENTATION QosPolicy (Section 6.4.6) must be set properly.

Accessing Samples If No Order or Coherence Is Required

Simply access the data by calling read/take on each DataReader in any order you want.

You do not have to call begin_access() and end_access(). However, doing so is not an error and it will have no effect.

You can call the Subscriber’s get_datareaders() operation to see which DataReaders have data to be read, but you do not need to read all of them or read them in a particular order. The get_datareaders() operation will return a logical 'set' in the sense that the same DataReader will not appear twice. The order of the DataReaders returned is not specified.

Accessing Samples within a SubscriberListener

This case describes how to access the data inside the listener's on_data_on_readers() operation (regardless of the PRESENTATION QoS policy settings).

To do so, you can call read/take on each DataReader in any order. You can also delegate accessing of the data to the DataReaderListeners by calling the Subscriber’s notify_datareaders() operation.

Similar to the previous case, you can still call the Subscriber’s get_datareaders() operation to determine which DataReaders have data to be read, but you do not have to read all of them, or read them in a particular order. get_datareaders() will return a logical 'set.'

You do not have to call begin_access() and end_access(). However, doing so is not an error and it will have no effect.

7.4.3.3read_next_sample and take_next_sample

The read_next_sample() or take_next_sample() operation is used to retrieve the next sample that hasn’t already been accessed. It is a simple way to 'read' samples and frees your application from managing sequences and specifying sample, instance or view states. It behaves the same as calling read() or take() with max_samples = 1, sample_states = NOT_READ, view_states = ANY_VIEW_STATE, and instance_states = ANY_INSTANCE_STATE.

DDS_ReturnCode_t read_next_sample(Foo & received_data,

DDS_SampleInfo & sample_info);

DDS_ReturnCode_t take_next_sample(Foo & received_data,

DDS_SampleInfo & sample_info);

It copies the next, not-previously-accessed data value from the DataReader. It also copies the sample’s corresponding DDS_SampleInfo structure.

If there is no unread data in the DataReader, the operation will return

DDS_RETCODE_NO_DATA and nothing is copied.

Since this operation copies both the data sample and the SampleInfo into user-provided storage, it does not allocate nor loan memory. You do not have to call return_loan() after this operation.

Note: If the received_data parameter references a structure that contains a sequence and that sequence has not been initialized, the operation will return DDS_RETCODE_ERROR.

7-41

7.4.3.4read_instance and take_instance

The read_instance() and take_instance() operations are identical to read() and take(), but they are used to access samples for just a specific instance (key value). The parameters are the same, except you must also supply an instance handle. These functions can only be used when the DataReader is tied to a keyed type, see Section 2.2.2 for more about keyed data types.

These operations may return BAD_PARAMETER if the instance handle does not correspond to an existing data-object known to the DataReader.

The handle to a particular data instance could have been cached from a previous read() operation (value taken from the SampleInfo struct) or created by using the DataReader’s lookup_instance() operation.

DDS_ReturnCode_t read_instance(

 

FooSeq

&received_data,

DDS_SampleInfoSeq

&info_seq,

DDS_Long

max_samples,

const DDS_InstanceHandle_t &a_handle,

DDS_SampleStateMask

sample_states,

DDS_ViewStateMask

view_states,

DDS_InstanceStateMask

instance_states);

Note: This operation may loan internal Connext memory, which must be returned with return_loan(). See Loaning and Returning Data and SampleInfo Sequences (Section 7.4.2).

7.4.3.5read_next_instance and take_next_instance

The read_next_instance() and take_next_instance() operations are similar to read_instance() and take_instance() in that they return samples for a specific data instance (key value). The difference is that instead of passing the handle of the data instance for which you want data samples, instead you pass the handle to a ‘previous’ instance. The returned samples will all belong to the 'next' instance, where the ordering of instances is explained below.

DDS_ReturnCode_t read_next_instance(

 

FooSeq

&received_data,

DDS_SampleInfoSeq

&info_seq,

DDS_Long

max_samples,

const DDS_InstanceHandle_t &previous_handle,

DDS_SampleStateMask sample_states, DDS_ViewStateMask view_states, DDS_InstanceStateMask instance_states)

Connext orders all instances relative to each other.1 This ordering depends on the value of the key as defined for the data type associated with the Topic. For the purposes of this discussion, it is 'as if' each instance handle is represented by a unique integer and thus different instance handles can be ordered by their value.

This operation will return values for the next instance handle that has data samples stored in the receive queue (that meet the criteria specified by the StateMasks). The next instance handle will be ordered after the previous_handle that is passed in as a parameter.

The special value DDS_HANDLE_NIL can be passed in as the previous_handle. Doing so, you will receive values for the “smallest” instance handle that has data samples stored in the receive queue that you have not yet accessed.

You can call the read_next_instance() operation with a previous_handle that does not correspond to an instance currently managed by the DataReader. For example, you could use this approach to iterate though all the instances, take all the samples with a NOT_ALIVE_NO_WRITERS instance_state, return the loans (at which point the instance

1.The ordering of the instances is specific to each implementation of the DDS standard; to maximize the portability of your code, do not assume any particular order. In the case of Connext (and likely other DDS implementations as well), the order is not likely to be meaningful to you as a developer; it is simply important that some ordering exists.

7-42

information may be removed, and thus the handle becomes invalid), and then try to read the next instance.

The example in Figure 7.17 shows how to use take_next_instance() iteratively to process all the data received for an instance, one instance at a time. We always pass in DDS_HANDLE_NIL as the value of previous_handle. Each time through the loop, we will receive samples for a different instance, since the previous time through the loop, all of the samples of the previous instance were returned (and thus accessed).

Figure 7.17 Using take_next_instance() to process received data

FooSeq

received_data;1

DDS_SampleInfoSeq info_seq;

while (retcode = reader->take_next_instance( received_data, info_seq, DDS_LENGTH_UNLIMITED, DDS_HANDLE_NIL, DDS_ANY_SAMPLE_STATE, DDS_ANY_VIEW_STATE, DDS_ANY_INSTANCE_STATE)

!= DDS_RETCODE_NO_DATA) {

//the data samples returned in received_data will all

//be for a single instance

... // process the data

// now return the loaned sequences

if (reader->return_loan(received_data, info_seq) != DDS_RETCODE_OK) {

... // handle error

}

}

1.In the C API, you must use the FooSeq_initialize() and DDS_SampleInfoSeq_initialize() operations or the macro DDS_SEQUENCE_INITIALIZER to initialize the FooSeq and DDS_SampleInfoSeq to be empty. For example,

DDS_SampleInfoSeq infoSeq; DDS_SampleInfoSeq_initialize(&infoSeq); or

FooSeq fooSeq = DDS_SEQUENCE_INITIALIZER;

Note: This operation may loan internal Connext memory, which must be returned with return_loan(). See Loaning and Returning Data and SampleInfo Sequences (Section 7.4.2).

7.4.3.6read_w_condition and take_w_condition

The read_w_condition() and take_w_condition() operations are identical to read() and take(), but instead of passing in the sample_states, view_states, and instance_states mask parameters directly, you pass in a ReadCondition (which specifies these masks).

DDS_ReturnCode_t read_w_condition

 

(FooSeq

&received_data,

DDS_SampleInfoSeq

&info_seq,

DDS_Long

max_samples,

DDSReadCondition

*condition)

Note: This operation may loan internal Connext memory, which must be returned with return_loan(). See Loaning and Returning Data and SampleInfo Sequences (Section 7.4.2).

7-43

7.4.3.7read_instance_w_condition and take_instance_w_condition

The read_instance_w_condition() and take_instance_w_condition() operations are similar to read_instance() and take_instance(), respectively, except that the returned samples must also satisfy a specified ReadCondition.

DDS_ReturnCode_t read_instance_w_condition(

 

FooSeq

& received_data,

DDS_SampleInfoSeq

& info_seq,

DDS_Long

max_samples,

const DDS_InstanceHandle_t

& a_handle,

DDSReadCondition

* condition);

The behavior of read_instance_w_condition() and take_instance_w_condition() follows the same rules as read() and take() regarding pre-conditions and post-conditions for the received_data and sample_info parameters.

These functions can only be used when the DataReader is tied to a keyed type, see Section 2.2.2 for more about keyed data types.

Similar to read(), these operations must be provided on the specialized class that is generated for the particular application data-type that is being accessed.

Note: These operations may loan internal Connext memory, which must be returned with return_loan(). See Loaning and Returning Data and SampleInfo Sequences (Section 7.4.2).

7.4.3.8read_next_instance_w_condition and take_next_instance_w_condition

The read_next_instance_w_condition() and take_next_instance_w_condition() operations are identical to read_next_instance() and take_next_instance(), but instead of passing in the sample_states, view_states, and instance_states mask parameters directly, you pass in a ReadCondition (which specifies these masks).

DDS_ReturnCode_t read_next_instance_w_condition

(FooSeq

&received_data,

DDS_SampleInfoSeq

&info_seq,

DDS_Long

max_samples,

const DDS_InstanceHandle_t &previous_handle,

DDSReadCondition *condition)

Note: This operation may loan internal Connext memory, which must be returned with return_loan(). See Loaning and Returning Data and SampleInfo Sequences (Section 7.4.2).

7.4.4Acknowledging Samples

Samples can be acknowledged one at a time, or as a group. To explicitly acknowledge a single sample:

DDS_ReturnCode_t acknowledge_sample (const DDS_SampleInfo & sample_info)

Or you may acknowledge all previously accessed samples by calling:

DDS_ReturnCode_t DDSDataReader::acknowledge_all ()

Where:

sample_info DDS_SampleInfo identifying the sample being acknowledged.

Both of these operations can only be used when the DataReader’s RELIABILITY QosPolicy (Section 6.5.19) has an acknowledgment_kind set to DDS_APPLICATION_EXPLICIT_.ACKNOWLEDGMENT_MODE.

See also: Application Acknowledgment (Section 6.3.12) and Chapter 13: Guaranteed Delivery of Data.

7-44

7.4.5The Sequence Data Structure

The DDS specification uses sequences whenever a variable-length array of elements must be passed through the API. This includes passing QosPolicies into Connext, as well as retrieving data samples from Connext. A sequence is an ordered collection of elements of the same type. The type of a sequence containing elements of type “Foo” (whether “Foo” is one of your types or a built-in Connext type) is typically called “FooSeq.”

In all APIs except Java, FooSeq contains deep copies of Foo elements; in Java, which does not provide direct support for deep copy semantics, FooSeq contains references to Foo objects. In Java, sequences implement the java.util.List interface, and thus support all of the collection APIs and idioms familiar to Java programmers.

A sequence is logically composed of three things: an array of elements, a maximum number of elements that the array may contain (i.e. its allocated size), and a logical length indicating how many of the allocated elements are valid. The length may vary dynamically between 0 and the maximum (inclusive); it is not permissible to access an element at an index greater than or equal to the length.

A sequence may either “own” the memory associated with it, or it may “borrow” that memory. If a sequence owns its own memory, then the sequence itself will allocate the its memory and is permitted to grow and shrink that memory (i.e. change its maximum) dynamically.

You can also loan a sequence of memory using the sequence-specific operations loan_contiguous() or loan_discontiguous(). This is useful if you want Connext to copy the received data samples directly into data structures allocated in user space.

Please do not confuse (a) the user loaning memory to a sequence with (b) Connext loaning internal memory from the receive queue to the user code via the read() or take() operations. For sequences of user data, these are complementary operations. read() and take() loan memory to the user, passing in a sequence that has been loaned memory with loan_contiguous() or loan_discontinguous().

A sequence with loaned of memory may not change its maximum size.

For C developers: In C, because there is no concept of a constructor, sequences must be initialized before they are used. You can either set a sequence equal to the macro DDS_SEQUENCE_INITIALIZER or use a sequence-specific method, <type>Seq_initialize(), to initialize sequences.

For C++, C++/CLI, and C# developers: C++ sequence classes overload the [ ] operators to allow you to access their elements as if the sequence were a simple array. However, for code portability reasons, Connext’s implementation of sequences does not use the Standard Template Library (STL).

For Java developers: In Java, sequences implement the List interface, and typically, a List must contain Objects; it cannot contain primitive types directly. This restriction makes Lists of primitives types less efficient because each type must be wrapped and unwrapped into and from an Object as it is added to and removed from the List.

Connext provides a more efficient implementation for sequences of primitive types. In Connext, primitive sequence types (e.g., IntSeq, FloatSeq, etc.) are implemented as wrappers around arrays of primitive types. The wrapper also provides the usual List APIs; however, these APIs manipulate Objects that store the primitive type.

More efficient APIs are also provided that manipulate the primitive types directly and thus avoid unnecessary memory allocations and type casts. These additional methods are named according to the pattern <standard method><primitive type>; for example, the IntSeq class defines methods addInt() and getInt() that correspond to the List APIs add() and get(). addInt() and getInt() directly manipulate int values while add() and get() manipulate Objects that contain a single int.

7-45

For more information on sequence APIs in all languages, please consult the API Reference HTML documentation (from the main page, select Modules, Infrastructure, Sequence Support).

7.4.6The SampleInfo Structure

When you invoke the read/take operations, for every data sample that is returned, a corresponding SampleInfo is also returned. SampleInfo structures provide you with additional information about the data samples received by Connext.

Table 7.18 shows the format of the SampleInfo structure.

Table 7.18 DDS_SampleInfo Structure

Type

Field Name

 

 

Description

 

 

 

 

 

 

 

 

 

 

 

DDS_SampleStateKind

sample_state

See Section 7.4.6.2

 

 

 

 

 

 

 

DDS_ViewStateKind

view_state

See Section 7.4.6.3

 

 

 

 

 

 

 

DDS_InstanceStateKind

instance_state

See Section 7.4.6.4

 

 

 

 

 

 

 

 

DDS_Time_t

source_timestamp

Time

stored

by

the DataWriter when the

sample was written.

 

 

 

 

 

 

 

DDS_InstanceHandle_t

instance_handle

Handle to the data-instance corresponding to

the sample.

 

 

 

 

 

 

 

 

 

 

 

 

 

Local handle to the DataWriter that modified

 

 

the instance. This is the same instance handle

DDS_InstanceHandle_t

publication_handle

returned by get_matched_publications(). You

 

 

can

use

this

handle when

calling

 

 

get_matched_publication_data().

 

 

 

 

 

 

 

 

 

disposed_generation_count

 

 

 

 

 

 

 

 

 

 

 

 

 

no_writers_generation_count

 

 

 

 

 

 

 

 

 

DDS_Long

sample_rank

See Section 7.4.6.5.

 

 

 

 

 

 

 

 

 

generation_rank

 

 

 

 

 

 

 

 

 

 

 

 

 

absolute_generation_rank

 

 

 

 

 

 

 

 

DDS_Boolean

valid_data

Indicates whether the data sample includes

valid data. See Section 7.4.6.6.

 

 

 

 

 

 

 

DDS_Time_t

reception_timestamp

Time stored when the sample was committed

by the DataReader. See Section 7.4.6.1.

 

 

 

 

 

DDS_SequenceNumber_t

publication_sequence_number

Publication sequence number assigned when

the sample was written by the DataWriter.

 

 

 

 

 

 

 

Reception sequence number assigned when

DDS_SequenceNumber_t

reception_sequence_number

the sample was committed by the

 

 

DataReader. See Section 7.4.6.1.

 

 

 

 

 

 

 

Original publication virtual GUID.

 

struct DDS_GUID_t

original_publication_

If the Publisher’s access_scope is GROUP, this

virtual_guid

field contains the Publisher virtual GUID that

 

 

 

uniquely identifies the DataWriter group.

 

 

 

 

 

 

Original publication virtual

sequence

 

 

number.

 

 

 

struct

original_publication_

If the Publisher’s access_scope is GROUP, this

DDS_SequenceNumber_t

virtual_sequence_number

field contains the Publisher virtual sequence

 

 

number that

uniquely identifies a sample

 

 

within the DataWriter group.

 

 

 

 

 

 

 

 

7-46

7.4.6.1Reception Timestamp

In reliable communication, if data samples are received out received of order, Connext will not deliver them until all the previous data samples have been received. For example, if Sample 2 arrives before Sample 1, Sample 2 cannot be delivered until Sample 1 is received. The reception_timestamp is the time when all previous samples has been received—the time at which the sample is committed. If samples are all received in order, the committed time will be same as reception time. However, if samples are lost on the wire, then the committed time will be later than the initial reception time.

7.4.6.2Sample States

For each sample received, Connext keeps a sample_state relative to each DataReader. The sample_state can be either:

READ The DataReader has already accessed that sample by means of read().

NOT_READ The DataReader has never accessed that sample before.

The samples retrieved by a read() or take() need not all have the same sample_state.

7.4.6.3View States

For each instance (identified by a unique key value), Connext keeps a view_state relative to each DataReader. The view_state can be either:

NEW Either this is the first time the DataReader has ever accessed samples of the instance, or the DataReader has accessed previous samples of the instance, but the instance has since been reborn (i.e. become not-alive and then alive again). These two cases are distinguished by examining the disposed_generation_count and the no_writers_generation_count (see Section 7.4.6.5).

NOT_NEW The DataReader has already accessed samples of the same instance and the instance has not been reborn since.

The view_state in the SampleInfo structure is really a per-instance concept (as opposed to the sample_state which is per data sample). Thus all data samples related to the same instance that are returned by read() or take() will have the same value for view_state.

7.4.6.4Instance States

Connext keeps an instance_state for each instance; it can be:

ALIVE The following are all true: (a) samples have been received for the instance, (b) there are live DataWriters writing the instance, and (c) the instance has not been explicitly disposed (or more samples have been received after it was disposed).

NOT_ALIVE_DISPOSED The instance was explicitly disposed by a DataWriter by means of the dispose() operation.

NOT_ALIVE_NO_WRITERS The instance has been declared as not-alive by the DataReader because it has determined that there are no live DataWriter entities writing that instance.

The events that cause the instance_state to change can depend on the setting of the OWNERSHIP QosPolicy (Section 6.5.15):

If OWNERSHIP QoS is set to EXCLUSIVE, the instance_state becomes NOT_ALIVE_DISPOSED only if the DataWriter that currently “owns” the instance explicitly disposes it. The instance_state will become ALIVE again only if the DataWriter that owns the instance writes it. Note that ownership of the instance is determined by a combination of the OWNERSHIP and OWNERSHIP_STRENGTH QosPolicies. Ownership of an instance can dynamically change.

7-47

If OWNERSHIP QoS is set to SHARED, the instance_state becomes NOT_ALIVE_DISPOSED if any DataWriter explicitly disposes the instance. The instance_state becomes ALIVE as soon as any DataWriter writes the instance again.

Since the instance_state in the SampleInfo structure is a per-instance concept, all data samples related to the same instance that are returned by read() or take() will have the same value for instance_state.

7.4.6.5Generation Counts and Ranks

Generation counts and ranks allow your application to distinguish samples belonging to different ‘generations’ of the instance. It is possible for an instance to become alive, be disposed and become not-alive, and then to cycle again from alive to not-alive states during the operation of an application. Each time an instance becomes alive defines a new generation for the instance.

It is possible that an instance may cycle through alive and not-alive states multiple times before the application accesses the data samples for the instance. This means that the data samples returned by read() and take() may cross generations. That is, some samples were published when the instance was alive in one generation and other samples were published when the instance transitioned through the non-alive state into the alive state again. It may be important to your application to distinguish the data samples by the generation in which they were published.

Each DataReader keeps two counters for each new instance it detects (recall that instances are distinguished by their key values):

disposed_generation_count Counts how many times the instance_state of the corresponding instance changes from NOT_ALIVE_DISPOSED to ALIVE. The counter is reset when the instance resource is reclaimed.

no_writers_generation_count Counts how many times the instance_state of the corresponding instance changes from NOT_ALIVE_NO_WRITERS to ALIVE. The counter is reset when the instance resource is reclaimed.

The disposed_generation_count structure capture a snapshot of sample was received.

and no_writers_generation_count fields in the SampleInfo the corresponding counters at the time the corresponding

The sample_rank and generation_rank in the SampleInfo structure are computed relative to the sequence of samples returned by read() or take():

sample_rank Indicates how many samples of the same instance follow the current one in the sequence. The samples are always time-ordered, thus the newest sample of an instance will have a sample_rank of 0. Depending on what you have configured read() and take() to return, a sample_rank of 0 may or may not be the newest sample that was ever received. It is just the newest sample in the sequence that was returned.

generation_rank Indicates the difference in ‘generations’ between the sample and the newest sample of the same instance as returned in the sequence. If a sample belongs to the same generation as the newest sample in the sequence returned by read() and take(), then generation_rank will be 0.

absolute_generation_rank Indicates the difference in ‘generations’ between the sample and the newest sample of the same instance ever received by the DataReader. Recall that the data sequence returned by read() and take() may not contain all of the data in the DataReader’s receive queue. Thus, a sample that belongs to the newest generation of the instance will have an absolute_generation_rank of 0.

Like the ‘generation count’ values, the ‘rank’ values are also reset to 0 if the instance resource is reclaimed.

By using the sample_rank, generation_rank and absolute_generation_rank information in the

SampleInfo structure, your application can determine exactly what happened to the instance

7-48

and thus make appropriate decisions of what to do with the data samples received for the instance. For example:

A sample with sample_rank = 0 is the newest sample of the instance in the returned sequence.

Samples that belong to the same generation will have the same generation_rank (as well as absolute_generation_rank).

Samples with absolute_generation_rank = 0 belong to the newest generation for the instance received by the DataReader.

7.4.6.6Valid Data Flag

The SampleInfo structure’s valid_data flag indicates whether the sample contains data or is only used to communicate a change in the instance_state of the instance.

Normally, each sample contains both a SampleInfo structure and some data. However, there are situations in which the sample only contains the SampleInfo and does not have any associated data. This occurs when Connext notifies the application of a change of state for an instance that was caused by some internal mechanism (such as a timeout) for which there is no associated data. An example is whenConnext detects that an instance has no writers and changes the corresponding instance_state to NOT_ALIVE_NO_WRITERS.

If this flag is TRUE, then the sample contains valid Data. If the flag is FALSE, the Sample contains no data.

To ensure correctness and portability, your application must check the valid_data flag prior to accessing the data associated with the sample, and only access the data if it is TRUE.

7.5Subscriber QosPolicies

Subscribers have the same set of QosPolicies as Publishers; see Publisher/Subscriber QosPolicies (Section 6.4).

ENTITYFACTORY QosPolicy (Section 6.4.2)

EXCLUSIVE_AREA QosPolicy (DDS Extension) (Section 6.4.3)

GROUP_DATA QosPolicy (Section 6.4.4)

PARTITION QosPolicy (Section 6.4.5)

PRESENTATION QosPolicy (Section 6.4.6)

7.6DataReader QosPolicies

This section describes the QosPolicies that are strictly for DataReaders (not for DataWriters). For a complete list of QosPolicies that apply to DataReaders, see Table 7.16 on page 7-32.

DATA_READER_PROTOCOL QosPolicy (DDS Extension) (Section 7.6.1)

DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 7.6.2)

READER_DATA_LIFECYCLE QoS Policy (Section 7.6.3)

TIME_BASED_FILTER QosPolicy (Section 7.6.4)

TRANSPORT_MULTICAST QosPolicy (DDS Extension) (Section 7.6.5)

7-49

TYPE_CONSISTENCY_ENFORCEMENT QosPolicy (Section 7.6.6)

7.6.1DATA_READER_PROTOCOL QosPolicy (DDS Extension)

The DATA_READER_PROTOCOL QosPolicy applies only to DataReaders that are set up for reliable operation (see RELIABILITY QosPolicy (Section 6.5.19)). This policy allows the application to fine-tune the reliability protocol separately for each DataReader. For details of the reliable protocol used by Connext, see Chapter 10.

Connext uses a standard protocol for packet (user and meta data) exchange between applications. The DataReaderProtocol QosPolicy gives you control over configurable portions of the protocol, including the configuration of the reliable data delivery mechanism of the protocol on a per DataReader basis.

These configuration parameters control timing and timeouts, and give you the ability to trade off between speed of data loss detection and repair, versus network and CPU bandwidth used to maintain reliability.

It is important to tune the reliability protocol on a per DataReader basis to meet the requirements of the end-user application so that data can be sent between DataWriters and DataReaders in an efficient and optimal manner in the presence of data loss.

You can also use this QosPolicy to control how DDS responds to "slow" reliable DataReaders or ones that disconnect or are otherwise lost.

See the RELIABILITY QosPolicy (Section 6.5.19) for more information on the per-DataReader/ DataWriter reliability configuration. The HISTORY QosPolicy (Section 6.5.10) and RESOURCE_LIMITS QosPolicy (Section 6.5.20) also play an important role in the DDS reliability protocol.

This policy includes the members presented in Table 7.19 and Table 7.20. For defaults and valid ranges, please refer to the API Reference HTML documentation.

When setting the fields in this policy, the following rule applies. If this is false, Connext returns

DDS_RETCODE_INCONSISTENT_POLICY when setting the QoS:

max_heartbeat_response_delay >= min_heartbeat_response_delay

Table 7.19 DDS_DataReaderProtocolQosPolicy

Type

Field Name

 

Description

 

 

 

 

 

 

 

 

The virtual GUID (Global Unique Identifier) is used to uniquely

 

 

identify the same DataReader across multiple incarnations. In

 

 

other words, this value allows Connext to remember information

 

 

about a DataReader that may be deleted and then recreated.

 

 

This value is used to provide durable reader state.

DDS_GUID_t

virtual_guid

For more information, see Durability and Persistence Based on

Virtual GUIDs (Section 12.2).

 

 

 

 

By default, Connext will assign a virtual GUID automatically. If

 

 

you want to restore the DataReader’s state after a restart, you can

 

 

get the DataReader's virtual GUID using its get_qos() operation,

 

 

then set the virtual GUID of the restarted DataReader to the same

 

 

value.

 

 

 

 

 

 

Determines the DataReader’s RTPS object ID, according to the

 

 

DDS-RTPS Interoperability Wire Protocol.

 

 

Only the last 3 bytes are used; the most significant byte is ignored.

DDS_

rtps_object_id

The rtps_host_id,

rtps_app_id, rtps_instance_id in the

UnsignedLong

WIRE_PROTOCOL QosPolicy (DDS Extension) (Section 8.5.9),

 

 

 

together with the 3 least significant bytes in rtps_object_id, and

 

 

another byte assigned by Connext to identify the entity type,

 

 

forms the BuiltinTopicKey in SubscriptionBuiltinTopicData.

 

 

 

 

7-50

Table 7.19 DDS_DataReaderProtocolQosPolicy

Type

Field Name

Description

Specifies whether this DataReader expects inline QoS with every sample.

DataReaders usually rely on the discovery process to propagate QoS changes for matched DataWriters. Another way to get QoS information is to have it sent inline with a sample.

With Connext, DataWriters and DataReaders cache discovery

DDS_

information, so sending inline QoS is typically unnecessary. The

Boolean

expects_inline_qos use of inline QoS is only needed for stateless implementations of DDS in which DataReaders do not cache Discovery information. The complete set of QoS that a DataWriter may send inline is specified by the Real-Time Publish-Subscribe (RTPS) Wire Interoperability Protocol.

Note: The use of inline QoS creates an additional wire-payload, consuming extra bandwidth and serialization/deserialization time.

Determines whether the DataReader sends positive acknowledgements (ACKs) to matching DataWriters.

DDS_

When TRUE. the matching DataWriter will keep samples in its

Boolean

disable_positive_acks queue for this DataReader for a minimum keep duration (see Disabling Positive Acknowledgements (Section 6.5.3.3)).

 

When strict-reliability is not required and NACK-based reliability

 

is sufficient, setting this field reduces overhead network traffic.

 

 

 

 

Indicates whether or not an instance can move to

the

 

DDS_NOT_ALIVE_DISPOSED_INSTANCE_STATE

state

 

without being in the DDS_ALIVE_INSTANCE_STATE state.

 

 

When set to TRUE, the DataReader will receive dispose

 

notifications even if the instance is not alive.

 

propagate_dispose_

This field only applies to keyed DataReaders.

 

DDS_Boolean of_unregistered_

To make sure the key is available to the FooDataReader’s

instances

get_key_value() operation, use this option in combination with

 

setting the DataWriter’s serialize_key_with_dispose field (in the

 

DATA_WRITER_PROTOCOL QosPolicy (DDS Extension)

 

(Section 6.5.3)) to TRUE.

 

 

See Propagating Serialized Keys with Disposed-Instance

 

Notifications (Section 6.5.3.5).

 

 

 

 

DDS_Rtps-

 

 

ReliableReader- rtps_reliable_reader

See Table 7.20

 

Protocol_t

 

 

7.6.1.1Receive Window Size

A reliable DataReader presents samples it receives to the user in-order. If it receives samples out- of-order, it stores them internally until the other missing samples are received. For example, if the DataWriter sends samples 1 and 2, if the DataReader receives 2 first, it will wait until it receives 1 before passing the samples to the user.

The number of out-of-order samples that a DataReader can keep is set by the receive_window_size. A larger window allows more out-of-order samples to be kept. When the window is full, any subsequent out-of-samples received will be dropped, and such drops would necessitate NACK repairs that would degrade throughput. So, in network environments where out-of-order samples are more probable or where NACK repairs are costly, this window likely should be increased.

By default, the window is set to 256, which is the maximum number of samples a single NACK submessage can request.

7-51

Table 7.20 DDS_RtpsReliableReaderProtocol_t

Type

Field Name

 

 

 

 

Description

 

 

 

 

 

 

 

 

 

 

 

 

 

How long additionally received heartbeats are suppressed.

 

 

 

When a reliable DataReader receives consecutive heartbeats

 

heartbeat_suppression_

within a short duration, this may trigger redundant NACKs. To

 

prevent the DataReader from sending redundant NACKs, the

 

duration

 

DataReader may ignore the latter heartbeat(s) for this amount of

 

 

 

 

time.

 

 

 

 

 

 

 

 

DDS_

 

See Section 10.3.4.1.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Duration_t

min_heartbeat_response_

Minimum delay between when the DataReader receives a

 

delay

heartbeat and when it sends an ACK/NACK.

 

 

 

 

 

 

max_heartbeat_response_

Maximum delay between when the DataReader receives a

 

delay

heartbeat and when it sends an ACK/NACK. Increasing this

 

value helps prevent NACK storms, but increases latency.

 

 

 

 

 

 

 

 

 

 

 

 

 

nack_period

Rate

at which

to

send

negative acknowledgements to

new

 

DataWriters. See Section 7.6.1.3.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

DDS_Long

receive_window_size

The number of received out-of-order samples a reader can keep

at a time. See Receive Window Size (Section 7.6.1.1)

 

 

 

 

 

 

 

 

 

DDS_

 

The duration from sending a NACK to receiving a repair of a

round_trip_time

sample. See Round-Trip Time For Filtering Redundant NACKs

Duration_t

 

(Section 7.6.1.2)

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

The period at which application-level acknowledgment

 

 

messages are sent.

 

 

 

 

 

 

 

DDS_

app_ack_period

A

DataReader

sends

application-level

acknowledgment

Duration_t

messages to a DataWriter at this periodic rate, and will continue

 

 

 

sending until it receives a message from the DataWriter that it

 

 

has received and processed the acknowledgment.

 

 

 

 

 

 

 

The minimum number of samples acknowledged by one

 

 

application-level acknowledgment message.

 

 

 

 

 

This setting applies only when the RELIABILITY QosPolicy

 

 

(Section 6.5.19) acknowledgment_kind is set to

 

 

APPLICATION_EXPLICIT or APPLICATION_AUTO.

 

 

 

A DataReader will immediately send an application-level

 

 

acknowledgment message when it has at least this many

 

 

samples that have been acknowledged. It will not send an

 

 

acknowledgment message until it has at least this many samples

 

 

pending acknowledgment.

 

 

 

 

 

DDS_

samples_per_app_ack

For example, calling the DataReader’s acknowledge_sample()

this many times consecutively will trigger the sending of an

Boolean

 

acknowledgment

message.

 

Calling

the

DataReader’s

 

 

 

 

 

acknowledge_all() may trigger the sending of an

 

 

acknowledgment message, if at least this many samples are

 

 

being acknowledged at once. See Acknowledging Samples

 

 

(Section 7.4.4).

 

 

 

 

 

 

 

 

 

 

This is independent of the DDS_RtpsReliableReaderProtocol_t’s

 

 

app_ack_period,

where

a

DataReader

will

send

 

 

acknowledgment messages at the periodic rate regardless.

 

 

 

When this is set to DDS_LENGTH_UNLIMITED,

 

 

acknowledgment messages are sent only periodically, at the rate

 

 

set by DDS_RtpsReliableReaderProtocol_t’s app_ack_period.

 

 

 

 

 

 

 

 

 

 

 

 

7.6.1.2Round-Trip Time For Filtering Redundant NACKs

When a DataReader requests for a sample to be resent, there is a delay from when the NACK is sent, to when it receives the resent sample. During that delay, the DataReader may receive

7-52

HEARTBEATs that normally would trigger another NACK for the same sample. Such redundant repairs waste bandwidth and degrade throughput.

The round_trip_time is a user-configured estimate of the delay between sending a NACK to receiving a repair. A DataReader keeps track of when a sample has been NACK'd, and will prevent subsequent NACKs from redundantly requesting for the same sample, until the round trip time has passed.

Note that the default value of 0 seconds means that the DataReader does not filter for redundant NACKs.

7.6.1.3Example

For many applications, changing these values will not be necessary. However, the more nodes that your distributed application uses, and the greater the amount of network traffic it generates, the more likely it is that you will want to consider experimenting with these values.

When a reliable DataReader receives a heartbeat from a DataWriter, it will send an ACK/NACK packet back to the DataWriter. Instead of sending the packet out immediately, the DataReader can choose to send it after a delay. This policy sets the minimum and maximum time to delay; the actual delay will be a random value in between. (For more on heartbeats and ACK/NACK messages, see Chapter 14: Discovery.)

Why is a delay useful? For DataWriters that have multiple reliable DataReaders, an efficient way of heartbeating all of the DataReaders is to send a single heartbeat via multicast. In that case, all of the DataReaders will receive the heartbeat (approximately) simultaneously. If all DataReaders immediately respond with a ACK/NACK packet, the network may be flooded. While the size of a ACK/NACK packet is relatively small, as the number of DataReaders increases, the chance of packet collision also increases. All of these conditions may lead to dropped packets which forces the DataWriter to send out additional heartbeats that cause more simultaneous heartbeats to be sent, ultimately resulting a network packet storm.

By forcing each DataReader to wait for a random amount of time, bounded by the minimum and maximum values in this policy, before sending an ACK/NACK response to a heartbeat, the use of the network is spread out over a period of time, decreasing the peak bandwidth required as well as the likelihood of dropped packets due to collisions. This can increase the overall performance of the reliable connection while avoiding a network storm.

When a reliable DataReader first matches a reliable DataWriter, the DataReader sends periodic NACK messages at the specified period to pull historical data from the DataWriter. The DataReader will stop sending periodic NACKs when it has received all historical data available at the time that it matched the DataWriter. The DataReader ensures that at least one NACK is sent per period; for example, if, within a NACK period, the DataReader responds to a HEARTBEAT message with a NACK, then the DataReader will not send another periodic NACK.

7.6.1.4Properties

This QosPolicy cannot be modified after the DataReader is created.

It only applies to DataReaders, so there are no restrictions for setting it compatibly with respect to

DataWriters.

7.6.1.5Related QosPolicies

DATA_WRITER_PROTOCOL QosPolicy (DDS Extension) (Section 6.5.3)

RELIABILITY QosPolicy (Section 6.5.19)

7.6.1.6Applicable Entities

DataReaders (Section 7.3)

7-53

7.6.1.7System Resource Considerations

Changing the values in this policy requires making tradeoffs between minimizing latency (decreasing min_heartbeat_response_delay), maximizing determinism (decreasing the difference between min_heartbeat_response_delay and max_heartbeat_response_delay), and minimizing network collisions/spreading out the ACK/NACK packets across a time interval (increasing the difference between min_heartbeat_response_delay and max_heartbeat_response_delay and/or shifting their values between different DataReaders).

If the values are poorly chosen with respect to the characteristics and requirements of a given application, the latency and/or throughput of the application may suffer.

7.6.2DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension)

The DATA_READER_RESOURCE_LIMITS QosPolicy extends your control over the memory allocated by Connext for DataReaders beyond what is offered by the RESOURCE_LIMITS QosPolicy (Section 6.5.20). RESOURCE_LIMITS controls memory allocation with respect to the DataReader itself: the number of samples that it can store in the receive queue and the number of instances that it can manage simultaneously. DATA_READER_RESOURCE_LIMITS controls memory allocation on a per matched-DataWriter basis. The two are orthogonal.

This policy includes the members in Table 7.21, “DDS_DataReaderResourceLimitsQosPolicy,” on page 7-54. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 7.21 DDS_DataReaderResourceLimitsQosPolicy

Type

Field Name

 

 

Description

 

 

 

 

 

 

 

 

 

 

 

Maximum number of DataWriters from which a DataReader may receive

DDS_

max_remote_writers

data samples, among all instances.

 

 

 

Long

For

unkeyed

Topics:

max_remote_writers

must

=

 

 

 

max_remote_writers_per_instance

 

 

 

 

 

 

 

 

Maximum number of DataWriters from which a DataReader may receive

DDS_

max_remote_writers_

data samples for a single instance.

 

 

 

Long

per_instance

For

unkeyed

Topics:

max_remote_writers

must

=

 

 

max_remote_writers_per_instance

 

 

 

 

 

 

 

 

Maximum number of samples received out-of-order that a DataReader

DDS_

max_samples_

can store from a single reliable DataWriter.

 

 

 

Long

per_remote_writer

max_samples_per_remote_writer

must

be

<=

 

 

RESOURCE_LIMITS::max_samples

 

 

 

 

 

 

DDS_

 

Maximum number of DDS_SampleInfo structures that a DataReader can

max_infos

allocate.

 

 

 

 

 

Long

 

 

 

 

 

 

max_infos must be >= RESOURCE_LIMITS::max_samples

 

 

 

 

 

 

 

 

 

Initial number of DataWriters from which a DataReader may receive data

DDS_

initial_remote_writers

samples, including all instances.

 

 

 

 

Long

For

unkeyed

Topics:

initial_remote_writers

must

=

 

 

 

initial_remote_writers_per_instance

 

 

 

 

 

 

 

 

Initial number of DataWriters from which a DataReader may receive data

DDS_

initial_remote_

samples for a single instance.

 

 

 

 

Long

writers_per_instance

For

unkeyed

Topics:

initial_remote_writers

must

=

 

 

initial_remote_writers_per_instance

 

 

 

 

 

 

DDS_

initial_infos

Initial number of DDS_SampleInfo structures that a DataReader will

Long

allocate.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

7-54

Table 7.21 DDS_DataReaderResourceLimitsQosPolicy

Type

Field Name

 

 

Description

 

 

 

 

 

 

 

 

 

 

initial_outstanding_

Initial number of times in which memory can be concurrently loaned

DDS_

reads

via read/take calls without being returned with return_loan().

 

Long

max_outstanding_

Maximum number of times in which memory can be concurrently

 

reads

loaned via read/take calls without being returned with return_loan().

 

 

 

 

 

 

 

 

 

DDS_

max_samples_per_

Maximum number of samples that can be read/taken on a DataReader.

Long

read

 

 

 

 

 

 

 

 

 

 

DDS_

disable_fragmentation_

Determines whether the DataReader can receive fragmented samples.

When fragmentation support is not needed, disabling fragmentation

Boolean

support

support will save some memory resources.

 

 

 

 

 

 

 

 

 

 

 

 

 

The maximum number of samples for which the DataReader may store

 

 

fragments at a given point in time.

 

 

 

 

 

 

At any given time, a DataReader may store fragments for up to

 

 

max_fragmented_samples samples while waiting for the remaining

 

 

fragments. These samples need not have consecutive sequence

 

 

numbers and may have been sent by different DataWriters. Once all

 

 

fragments of a sample have been received, the sample is treated as a

DDS_

max_fragmented_

regular sample and becomes subject to standard QoS settings, such as

max_samples.

Connext

will

drop

fragments

if

the

Long

samples

max_fragmented_samples limit has been reached.

 

 

 

 

 

 

 

 

For best-effort communication, Connext will accept a fragment for a

 

 

new sample, but drop the oldest fragmented sample from the same

 

 

remote writer.

 

 

 

 

 

 

 

 

For reliable communication, Connext will drop fragments for any new

 

 

samples until all fragments for at least one older sample from that

 

 

writer have been received.

 

 

 

 

 

 

 

Only applies if disable_fragmentation_support is FALSE.

 

 

 

 

 

 

 

 

 

DDS_

initial_fragmented_

The initial number of samples for

which

a DataReader

may

store

fragments.

 

 

 

 

 

 

Long

samples

 

 

 

 

 

 

Only applies if disable_fragmentation_support is FALSE.

 

 

 

 

 

 

 

 

 

 

max_fragmented_

The maximum number of samples per remote writer for which a

DDS_

DataReader may store fragments. This is a logical limit, so a single

samples_per_remote_

Long

remote writer cannot consume all available resources.

 

 

writer

 

 

 

Only applies if disable_fragmentation_support is FALSE.

 

 

 

 

 

 

 

 

 

 

 

DDS_

max_fragments_per_

Maximum number of fragments for a single sample.

 

 

Long

sample

Only applies if disable_fragmentation_support is FALSE.

 

 

 

 

 

 

 

 

 

 

 

7-55

Table 7.21 DDS_DataReaderResourceLimitsQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

Determines whether the DataReader pre-allocates storage for storing

 

 

fragmented samples.

 

 

By default, Connext will allocate memory up front for storing fragments

 

 

for up to initial_fragmented_samples samples. This memory may grow

 

 

up to max_fragmented_samples if needed.

 

 

If dynamically_allocate_fragmented_samples is TRUE, Connext does

 

 

not allocate memory up front, but instead allocates memory from the

 

 

heap upon receiving the first fragment of a new sample. The amount of

 

 

memory allocated equals the amount of memory needed to store all

DDS_

dynamically_allocate_

fragments in the sample. Once all fragments of a sample have been

Boolean

fragmented_samples

received, the sample is deserialized and stored in the regular receive

 

 

queue. At that time, the dynamically allocated memory is freed again.

 

 

This QoS setting may be useful for large, but variable-sized data types

 

 

where up front memory allocation for multiple samples based on the

 

 

maximum possible sample size may be expensive. The main

 

 

disadvantage of not pre-allocating memory is that one can no longer

 

 

guarantee Connext will have sufficient resources at run-time. Also,

 

 

dynamic memory allocation and memory freeing at run time may not

 

 

give you good performance.

 

 

Only applies if disable_fragmentation_support is FALSE.

 

 

 

DDS_

max_total_instances

Maximum number of instances for which a DataReader will keep state.

Long

See max_total_instances and max_instances (Section 7.6.2.1)

 

 

 

 

 

 

The maximum number of virtual writers (identified by a virtual GUID)

 

 

from which a DataReader may read, including all instances.

DDS_

max_remote_virtual_

When the Subscriber’s access_scope is GROUP, this value determines

Long

writers

the maximum number of DataWriter groups supported by the

 

 

Subscriber. Since the Subscriber may contain more than one DataReader,

 

 

only the setting of the first applies.

 

 

 

DDS_

initial_remote_virtual_

The initial number of virtual writers from which a DataReader may

Long

writers

read, including all instances.

 

 

 

 

 

Maximum number of virtual remote writers that can be associated with

 

 

an instance.

 

 

For unkeyed types, this value is ignored.

 

 

The features of Durable Reader State and MultiChannel DataWriters, as

 

 

well as Persistence Servicea, require Connext to keep some internal state

 

 

per virtual writer and instance that is used to filter duplicate samples.

 

 

These duplicate samples could be coming from different DataWriter

 

 

channels or from multiple executions of Persistence Service.

DDS_

max_remote_virtual_

Once an association between a remote virtual writer and an instance is

Long

writers_per_instance

established, it is permanent—it will not disappear even if the physical

 

 

writer incarnating the virtual writer is destroyed.

 

 

If max_remote_virtual_writers_per_instance is exceeded for an

 

 

instance, Connext will not associate this instance with new virtual

 

 

writers. Duplicates samples coming from these virtual writers will not

 

 

be filtered on the reader.

 

 

If you are not using Durable Reader State, MultiChannel DataWriters or

 

 

Persistence Service, you can set this property to 1 to optimize resources.

 

 

For additional information about the virtual writers see Chapter 12.

 

 

 

DDS_

initial_remote_virtual_

Initial number of virtual remote writers per instance.

Long

writers_per_instance

For unkeyed types, this value is ignored.

 

 

 

7-56

Table 7.21 DDS_DataReaderResourceLimitsQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

Maximum number of remote writers that are allowed to write the same

 

 

sample.

DDS_

max_remote_writers_

One scenario in which two DataWriters may write the same sample is

Long

per_sample

when using Persistence Service. The DataReader may receive the same

 

 

sample from the original DataWriter and from an Persistence Service

 

 

DataWriter.

 

 

 

 

 

This value determines the maximum number of unique query

 

 

condition content filters that a reader may create.

DDS_

max_query_condition_

Each query condition content filter is comprised of both its

Long

filters

query_expression and query_parameters. Two query conditions that

have the same query_expression will require unique query condition

 

 

 

 

filters if their query_parameters differ. Query conditions that differ

 

 

only in their state masks will share the same query condition filter.

 

 

 

a. Persistence Service is included with Connext Messaging. It saves data samples so they can be delivered to subscrib- ing applications that join the system at a later time (see Chapter 26: Introduction to RTI Persistence Service).

DataReaders must allocate internal structures to handle: the maximum number of DataWriters that may connect to it; whether or not a DataReader handles data fragmentation and how many data fragments that it may handle (for data samples larger than the MTU of the underlying network transport); how many simultaneous outstanding loans of internal memory holding data samples can be provided to user code; as well as others.

Most of these internal structures start at an initial size and, by default, will grow as needed by dynamically allocating additional memory. You may set fixed, maximum sizes for these internal structures if you want to bound the amount of memory that can be used by a DataReader. Setting the initial size to the maximum size will prevent Connext from dynamically allocating any memory after the DataReader is created.

This policy also controls how the allocated internal data structure may be used. For example, DataReaders need data structures to keep track of all of the DataWriters that may be sending it data samples. The total number of DataWriters that it can keep track of is set by the initial_remote_writers and max_remote_writers values. For keyed Topics, initial_remote_writers_per_instance and max_remote_writers_per_instance control the number of DataWriters allowed by the DataReader to modify the value of a single instance.

By setting the max value to be less than max_remote_writers, you can prevent instances with many DataWriters from using up the resources and starving other instances. Once the resources for keeping track of DataWriters are used up, the DataReader will not be able to accept “connections” from new DataWriters. The DataReader will not be able to receive data from new matching DataWriters which would be ignored.

In the reliable protocol used by Connext to support a RELIABLE setting for the RELIABILITY QosPolicy (Section 6.5.19), the DataReader must temporarily store data samples that have been received out-of-order from a reliable DataWriter. The storage of out-of-order samples is allocated from the DataReader’s receive queue and shared among all reliable DataWriters. The parameter max_samples_per_remote_writer controls the maximum number of out-of-order data samples that the DataReader is allowed to store for a single DataWriter. This value must be less than the max_samples value set in the RESOURCE_LIMITS QosPolicy (Section 6.5.20).

max_samples_per_remote_writer allows Connext to share the limited resources of the DataReader equitably so that a single DataWriter is unable to use up all of the storage of the DataReader while missing data samples are being resent.

When setting the values of the members, the following rules apply:

max_remote_writers >= initial_remote_writers

7-57

max_remote_writers_per_instance >= initial_remote_writers_per_instance max_remote_writers_per_instance <= max_remote_writers

max_infos >= initial_infos

max_infos >= RESOURCE_LIMITS::max_samples

max_outstanding_reads >= initial_outstanding_reads

max_remote_writers >= max_remote_writers_per_instance

max_samples_per_remote_writer <= RESOURCE_LIMITS::max_samples

If any of the above are false, Connext returns the error code

DDS_RETCODE_INCONSISTENT_POLICY when setting the DataReader’s QoS.

7.6.2.1max_total_instances and max_instances

The maximum number of instances actively managed by a DataReader is determined by max_instances in the RESOURCE_LIMITS QosPolicy (Section 6.5.20). These instances have associated DataWriters or samples in the DataReader’s queue and are visible to the user through operations such as take(), read(), and get_key().

The features Durable Reader State (Section 12.4), multi-channel DataWriters (Chapter 18), and Persistence Service1 require Connext to keep some internal state even for instances without DataWriters or samples in the DataReader’s queue. The additional state is used to filter duplicate samples that could be coming from different DataWriter channels or from multiple executions of Persistence Service. The total maximum number of instances that will be managed by the middleware, including instances without associated DataWriters or samples, is determined by max_total_instances.

max_total_instances must be greater than max_instances or equal to DDS_AUTO_MAX_TOTAL_INSTANCES, which treats max_total_instances as being equal to max_instances in the RESOURCE_LIMITS QosPolicy (Section 6.5.20).

When a new instance is received, Connext will check the resource limit max_instances in the RESOURCE_LIMITS QosPolicy (Section 6.5.20). If the limit is exceeded, Connext will drop the sample and report it as lost and rejected. If the limit is not exceeded, Connext will check max_total_instances. If max_total_instances is exceeded, Connext will replace an existing instance without DataWriters and samples with the new one. The application could receive duplicate samples for the replaced instance if it becomes alive again.

7.6.2.2Example

The max_samples_per_remote_writer value affects sharing and starvation. max_samples_per_remote_writer can be set to less than the RESOURCE_LIMITS QosPolicy’s max_samples to prevent a single DataWriter from starving others. This control is especially important for Topics that have their OWNERSHIP QosPolicy (Section 6.5.15) set to SHARED.

In the case of EXCLUSIVE ownership, a lower-strength remote DataWriter can "starve" a higher- strength remote DataWriter by making use of more of the DataReader's resources, an undesirable condition. In the case of SHARED ownership, a remote DataWriter may starve another remote DataWriter, making the sharing not really equal.

7.6.2.3Properties

This QosPolicy cannot be modified after the DataReader is created.

It only applies to DataReaders, so there are no restrictions for setting it compatibly on the

DataWriter.

1.Persistence Service is included with Connext Messaging. It saves data samples so they can be delivered to subscribing applications that join the system at a later time (see Chapter 26: Introduction to RTI Persistence Service).

7-58

7.6.2.4Related QosPolicies

RESOURCE_LIMITS QosPolicy (Section 6.5.20)

OWNERSHIP QosPolicy (Section 6.5.15)

7.6.2.5Applicable Entities

DataReaders (Section 7.3)

7.6.2.6System Resource Considerations

Increasing any of the “initial” values in this policy will increase the amount of memory allocated by Connext when a new DataReader is created. Increasing any of the “max” values will not affect the initial memory allocated for a new DataReader, but will affect how much additional memory may be allocated as needed over the DataReader’s lifetime.

Setting a max value greater than an initial value thus allows your application to use memory more dynamically and efficiently in the event that the size of the application is not well-known ahead of time. However, Connext may dynamically allocate memory in response to network communications.

7.6.3READER_DATA_LIFECYCLE QoS Policy

This policy controls the behavior of the DataReader with regards to the lifecycle of the data instances it manages, that is, the data instances that have been received and for which the DataReader maintains some internal resources.

When a DataReader receives data, it is stored in a receive queue for the DataReader. The user application may either take the data from the queue or leave it there. This QoS controls whether or not Connext will automatically remove data from the receive queue (so that user applications cannot access it afterwards) when Connext detects that there are no more DataWriters alive for that data.

DataWriters may also call dispose() on its data, informing DataReaders that the data no longer exists. This QosPolicy also controls whether or not Connext automatically removes disposed data from the receive queue.

For keyed Topics, the consideration of removing data samples from the receive queue is done on a per instance (key) basis. Thus when Connext detects that there are no longer DataWriters alive for a certain key value for a Topic (an instance of the Topic), it can be configured to remove all data samples for a certain instance (key). DataWriters also can dispose its data on a per instance basis. Only the data samples of disposed instances would be removed by Connext if so configured.

This policy helps purge untaken samples from not-alive-instances and thus may prevent a DataReader from reclaiming resources. With this policy, the untaken samples from not-alive- instances are purged and treated as if the samples were taken after the specified amount of time.

The DataReader internally maintains the samples that have not been taken by the application, subject to the constraints imposed by other QoS policies such as HISTORY QosPolicy (Section 6.5.10) and RESOURCE_LIMITS QosPolicy (Section 6.5.20).

The DataReader also maintains information regarding the identity, view-state, and instance-state of data instances, even after all samples have been ‘taken’ (see Section 7.4.3). This is needed to properly compute the states when future samples arrive.

Under normal circumstances, a DataReader can only reclaim all resources for instances for which there are no DataWriters and for which all samples have been ‘taken.’ The last sample taken by the DataReader for that instance will have an instance state of NOT_ALIVE_NO_WRITERS or NOT_ALIVE_DISPOSED_INSTANCE (depending on whether or not the instance was disposed by the last DataWriter that owned it.) If you are using the default (infinite) values for this QosPolicy, this behavior can cause problems if the application does not ‘take’ those samples for

7-59

some reason. The ‘untaken’ samples will prevent the DataReader from reclaiming the resources and they would remain in the DataReader indefinitely.

It includes the members in Table 7.22.

Table 7.22 DDS_ReaderDataLifecycleQosPolicy

Type

Field Name

 

 

Description

 

 

 

 

 

 

 

 

autopurge_nowriter_

How long the DataReader maintains information about an

DDS_Duration_t

instance

once

its

instance_state

becomes

samples_delay

 

NOT_ALIVE_NO_WRITERS.

 

 

 

 

 

 

 

 

 

 

autopurge_disposed_

How long the DataReader maintains information about an

DDS_Duration_t

instance

once

its

instance_state

becomes

samples_delay

 

NOT_ALIVE_DISPOSED.

 

 

 

 

 

 

 

 

 

 

 

 

 

autopurge_nowriter_samples_delay This defines the maximum duration for which the DataReader will maintain information regarding an instance once its instance_state becomes NOT_ALIVE_NO_WRITERS. After this time elapses, the DataReader will purge all internal information regarding the instance, any untaken samples will also be lost.

autopurge_disposed_samples_delay This defines the maximum duration for which the DataReader will maintain samples of an instance once its instance_state becomes NOT_ALIVE_DISPOSED. After this time elapses, the DataReader will purge all internal information regarding the instance; any untaken samples will also be lost.

7.6.3.1Properties

This QoS policy can be modified after the DataReader is enabled.

It only applies to DataReaders, so there are no RxO restrictions for setting it compatibly on the

DataWriter.

7.6.3.2Related QoS Policies

HISTORY QosPolicy (Section 6.5.10)

LIVELINESS QosPolicy (Section 6.5.13)

OWNERSHIP QosPolicy (Section 6.5.15)

RESOURCE_LIMITS QosPolicy (Section 6.5.20)

WRITER_DATA_LIFECYCLE QoS Policy (Section 6.5.26)

7.6.3.3Applicable Entities

DataReaders (Section 7.3)

7.6.3.4System Resource Considerations

None.

7.6.4TIME_BASED_FILTER QosPolicy

The TIME_BASED_FILTER QosPolicy allows you to specify that data should not be delivered more than once per specified period for data-instances of a DataReader—regardless of how fast DataWriters are publishing new samples of the data-instance.

This QoS policy allows you to optimize resource usage (CPU and possibly network bandwidth) by only delivering the required amount of data to different DataReaders.

7-60

DataWriters may send data faster than needed by a DataReader. For example, a DataReader of sensor data that is displayed to a human operator in a GUI application does not need to receive data updates faster than a user can reasonably perceive changes in data values. This is often measure in tenths (0.1) of a second up to several seconds. However, a DataWriter of sensor information may have DataReaders that are processing the sensor information to control parts of the system and thus need new data updates in measures of hundredths (0.01) or thousandths (0.001) of a second.

With this QoS policy, different DataReaders can set their own time-based filters, so that data published faster than the period set by a DataReader will be dropped by the middleware and not delivered to the DataReader. Note that all filtering takes place on the reader side.

It includes the member in Table 7.23. For the default and valid range, please refer to the API Reference HTML documentation.

Table 7.23 DDS_TimeBasedFilterQosPolicy

Type

Field Name

Description

 

 

 

 

 

Minimum separation time between samples of the same

DDS_Duration_t

minimum_separation

instance.

 

 

Must be <= DEADLINE::period

 

 

 

As seen in Figure 7.18, it is inconsistent to set a DataReader’s minimum_separation longer than its DEADLINE QosPolicy (Section 6.5.5) period.

Figure 7.18 Accepting Data for DataReaders

 

 

 

 

 

 

 

 

 

 

 

Data received for same

New sample for instance will

 

 

 

instance is dropped

be accepted

Time

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

REQUESTED_DEADLINE_

 

 

 

 

 

Minimum_

 

 

 

 

 

 

Last data sample is

 

 

Separation

 

 

 

 

 

 

MISSED status changes if

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

no sample received for

received

 

 

 

 

 

 

 

 

 

 

 

 

Deadline

 

 

 

 

 

instance

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Data samples for a DataReader can be filtered out using the TIME_BASED_FILTER QoS (minimum_separation). Once a data sample for an instance has been received, Connext will accept but drop any new data samples for the same instance that arrives within the time specified by minimum_separation. After the minimum_separation, a new sample that arrives is accepted and stored in the receive queue, and the timer starts again. If no samples arrive by the DEADLINE, the REQUESTED_DEADLINE_MISSED status will be changed and Listeners called back if installed.

This QosPolicy allows a DataReader to subsample the data being published for a data instance by DataWriters. If a user application only needs new samples for a data instance to be received at a specified period, then there is no need for Connext to deliver data faster than that period. However, whether or not data being published by a DataWriter at a faster rate than set by the TIME_BASED_FILTER QoS is sent on the wire depends on several factors, including whether the DataReader is receiving the data reliably and if the data is being sent via multicast for multiple DataReaders.

For best effort data delivery, if the data type is unkeyed and the DataWriter has an infinite liveliness lease_duration (LIVELINESS QosPolicy (Section 6.5.13)), Connext will only send as many packets to a DataReader as required by the TIME_BASED_FILTER, no matter how fast the DataWriter’s write() function is called.

For multicast data delivery to multiple DataReaders, the DataReader with the lowest TIME_BASED_FILTER minimum_separation determines the DataWriter's send rate. For

7-61

example, if a DataWriter seconds and one with second.

sends multicast to two DataReaders, one with minimum_separation of 2 minimum_separation of 1 second, the DataWriter will send every 1

Other configurations (for example, when the DataWriter is reliable, or the data type is keyed, or the DataWriter has finite a liveliness lease_duration) must send all data published by the DataWriter. On reception, only the data that passes the TIME_BASED_FILTER will be stored in the DataReader’s receive queue. Extra data will be accepted but dropped. Note that filtering is only applied on ‘alive’ samples (that is, samples that have not been disposed/unregistered).

7.6.4.1Example

The purpose of this QosPolicy is to prevent fast DataWriters from overwhelming a DataReader that cannot process the data at the rate the data is being published. In certain configurations, the number of packets sent by Connext can also be reduced thus minimizing the consumption of network bandwidth.

You may want to change the minimum_separation between data samples for one or more of the following reasons:

The DataReader is connected to the network via a low-bandwidth connection that is unable to sustain the amount of traffic generated by the matched DataWriter(s).

The rate at which the matched DataWriter(s) can generate samples is faster than the rate at which the DataReader can process them. Or faster than needed by the DataReader. For example, a graphical user interface seldom needs to be updated faster than 30 times a second, even if new data values are available much faster.

The resource limits of the DataReader are constrained relative to the number of samples that could be generated by the matched DataWriter(s). Too many packets coming at once will cause them to be exhausted before the DataReader has time to process them.

7.6.4.2Properties

This QosPolicy can be modified at any time.

It only applies to DataReaders, so there are no restrictions for setting it compatibly on the

DataWriter.

7.6.4.3Related QosPolicies

RELIABILITY QosPolicy (Section 6.5.19)

DEADLINE QosPolicy (Section 6.5.5)

TRANSPORT_MULTICAST QosPolicy (DDS Extension) (Section 7.6.5)

7.6.4.4Applicable Entities

DataReaders (Section 7.3)

7.6.4.5System Resource Considerations

Depending on the values of other QosPolicies such as RELIABILITY and TRANSPORT_MULTICAST, this policy may be able to decrease the usage of network bandwidth and CPU by preventing unneeded packets from being sent and processed.

7.6.5TRANSPORT_MULTICAST QosPolicy (DDS Extension)

This QosPolicy specifies the multicast address on which a DataReader wants to receive its data. It can also specify a port number as well as a subset of the available transports with which to receive the multicast data.

7-62

By default, DataWriters will send individually addressed packets for each DataReader that subscribes to the topic of the DataWriter—this is known as unicast delivery. Thus, as many copies of the data will be sent over the network as there are DataReaders for the data. The network bandwidth used by a DataWriter will thus increase linearly with the number of

DataReaders.

Multicast is a concept supported by some transports, most notably UDP/IP, so that a single packet on the network can be addressed such that it is received by multiple nodes. This is more efficient when the same data needs to be sent to multiple nodes. By using multicast, the network bandwidth usage will be constant, independent of the number of DataReaders.

Coordinating the multicast address specified by DataReaders can help optimize network bandwidth usage in systems where there are multiple DataReaders for the same Topic.

The QosPolicy structure includes the members in Table 7.24.

Table 7.24 DDS_TransportMulticastQosPolicy

 

 

Type

 

Field

 

 

Description

 

 

 

 

 

Name

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

DDS_TransportMulticastSettingSeq

 

value

A sequence of multicast locators. (See Locator

 

(A sequence of the type shown in Table 7.25)

Format (Section 14.2.1.1).)

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Can be either:

 

 

 

 

 

 

 

 

 

AUTOMATIC_TRANSPORT_MULTICAST_QOS

 

 

 

 

 

(a multicast address is selected automatically);

 

DDS_TransportMulticastKind

 

kind

this

setting

is

required

when

using

 

 

TRANSPORT_MULTICAST_MAPPING

 

 

 

 

 

 

 

 

 

 

 

 

QosPolicy (DDS Extension) (Section 8.5.8).

 

 

 

 

 

 

UNICAST_ONLY_TRANSPORT_MULTICAST_Q

 

 

 

 

 

OS (unicast-only mode)

 

 

 

 

 

 

 

 

 

 

 

 

 

Table 7.25 DDS_TransportMulticastSetting_t

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Type

Field Name

 

 

 

Description

 

 

 

 

 

 

 

 

 

 

DDS_StringSeq

transports

A sequence of

transport aliases

that

specifies which transports

 

should be used to receive multicast messages for this DataReader.

 

 

 

 

 

 

 

 

char *

receive_address

A multicast group address to which the DataWriter should send

 

 

 

data for this DataReader.

 

 

 

 

 

 

 

 

The port that should be used in the addressing of multicast

 

DDS_Long

receive_port

messages destined for

this DataReader. A value

of 0 will

cause

 

Connext to use a default port number based on domain ID. See Ports

 

 

 

 

 

 

Used for Discovery (Section 14.5).

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

To take advantage of multicast, the value of this QosPolicy must be coordinated among all of the applications on a network for DataReaders of the same Topic. For a DataWriter to send a single packet that will be received by all DataReaders simultaneously, the same multicast address must be used.

To use this QosPolicy, you will also need to specify a port number. A port number of 0 will cause Connext to automatically use a default value. As explained in Ports Used for Discovery (Section 14.5), the default port number for multicast addresses is based on the domain ID. Should you choose to use a different port number, then for every unique port number used by Entities in your application, depending on the transport, Connext may create a thread to process messages received for that port on that transport. See Chapter 19: Connext Threading Model for more about threads.

Threads are created on a per-transport basis, so if this QosPolicy specifies multiple transports for a receive_port, then a thread may be created for each transport for that unique port. Some transports may be able to share a single thread for different ports, others can not. Note that

7-63

different Entities can share the same port number, and thus, the same thread will process all of the data for all of the Entities sharing the same port number for a transport.

Also note that if the port number specified by this QoS is the same as a port number specified by a TRANSPORT_UNICAST QoS, then the transport may choose to process data received both via multicast and unicast with a single thread. Whether or not a transport must use different threads to process data received via multicast or unicast for the same port number depends on the implementation of the transport.

Notes:

The same multicast address can be used by DataReaders of different Topics.

Even though the TRANSPORT_MULTICAST QoS allows you to specify multiple multicast addresses for a DataReader, Connext currently only uses one multicast address (the first in the sequence) per DataReader.

If a DataWriter is using the MULTI_CHANNEL QosPolicy (DDS Extension) (Section 6.5.14), the multicast addresses specified in the TRANSPORT_MULTICAST QosPolicy are ignored by that DataWriter. The DataWriter will not publish samples on those locators.

7.6.5.1Example

In an airport, there may be many different monitors that display current flight information. Assuming each monitor is controlled by a networked application, network bandwidth would be greatly reduced if flight information was published using multicast.

Figure 7.19 shows an example of how to set this QosPolicy.

Figure 7.19 Setting Up a Multicast DataReader

...

DDS_DataReaderQos reader_qos;

reader_listener = new HelloWorldListener(); if (reader_listener == NULL) {

// handle error

}

// Get default data reader QoS to customize

retcode = subscriber->get_default_datareader_qos(reader_qos); if (retcode != DDS_RETCODE_OK) {

// handle error

}

// Set up multicast reader reader_qos.multicast.value.ensure_length(1,1); reader_qos.multicast.value[0].receive_address =

DDS_String_dup("239.192.0.1");

reader = subscriber->create_datareader(topic,reader_qos, reader_listener, DDS_STATUS_MASK_ALL);

7.6.5.2Properties

This QosPolicy cannot be modified after the Entity is created.

For compatibility between DataWriters and DataReaders, the DataWriter must be able to send to the multicast address that the DataReader has specified.

7-64

7.6.5.3Related QosPolicies

MULTI_CHANNEL QosPolicy (DDS Extension) (Section 6.5.14)

TRANSPORT_UNICAST QosPolicy (DDS Extension) (Section 6.5.23)

TRANSPORT_BUILTIN QosPolicy (DDS Extension) (Section 8.5.7)

7.6.5.4Applicable Entities

DomainParticipants (Section 8.3)

DataReaders (Section 7.3)

7.6.5.5System Resource Considerations

On Ethernet-based systems, the number of multicast addresses that can be “listened” to by the network interface card is usually limited. The exact number of multicast addresses that can be monitored simultaneously by a NIC depends on its manufacturer. Setting a multicast address for a DataReader will use up one of the multicast-address slots of the NIC.

What happens if the number of different multicast addresses used by different DataReaders across different applications on the same node exceeds the total number supported by a NIC depends on the specific operating system. Some will prevent you from configuring too many multicast addresses to be monitored.

Many operating systems will accommodate the extra multicast addresses by putting the NIC in promiscuous mode. This means that the NIC will pass every Ethernet packet to the operating system, and the operating system will pass the packets with the specified multicast addresses to the application(s). This results in extra CPU usage. We recommend that your applications do not use more multicast addresses on a single node than the NICs on that node can listen to simultaneously in hardware.

Depending on the implementation of a transport, Connext may need to create threads to receive and process data on a unique-port-number basis. Some transports can share the same thread to process data received for different ports; others like UDPv4 must have different threads for different ports. In addition, if the same port is used for both unicast and multicast, the transport implementation will determine whether or not the same thread can be used to process both unicast and multicast data. For UDPv4, only one thread is needed per port–independent of whether the data was received via unicast or multicast data. See Receive Threads (Section 19.3) for more information.

7.6.6TYPE_CONSISTENCY_ENFORCEMENT QosPolicy

The TypeConsistencyEnforcementQosPolicy defines the rules that determine whether the type used to publish a given topic is consistent with the type used to subscribe to it.

The QosPolicy structure includes the member in Table 7.26.

Table 7.26 DDS_TypeConsistencyEnforcementQosPolicy

Type

Field

Description

Name

 

 

 

 

 

 

 

 

 

 

Can be either:

DDS_TypeConsistencyKind

kind

DISALLOW_TYPE_COERCION

ALLOW_TYPE_COERCION (default)

 

 

 

 

See Values for TypeConsistencyKind for details.

 

 

 

The type-consistency enforcement rules consist of two steps:

7-65

Step 1. If both the DataWriter and DataReader specify a TypeObject, it is considered first. If the DataReader allows type coercion, then its type must be assignable from the DataWriter’s type. If the DataReader does not allow type coercion, then its type must be structurally identical to the type of the DataWriter.

Step 2. If either the DataWriter or the DataReader does not provide a TypeObject definition, then the registered type names are examined. The DataReader’s and DataWriter’s registered type names must match exactly.

If either Step 1 or Step 2 fails, the Topics associated with the DataReader and DataWriter are considered to be inconsistent and the INCONSISTENT_TOPIC Status (Section 5.3.1) is updated.

The default enforcement kind is DDS_ALLOW_TYPE_COERCION. However, when the middleware is introspecting the built-in topic data declaration of a remote DataReader in order to determine whether it can match with a local DataWriter, if it observes that no TypeConsistencyEnforcementQosPolicy value is provided (as would be the case when communicating with a Service implementation not in conformance with this specification), it assumes a kind of DDS_DISALLOW_TYPE_COERCION.

Values for TypeConsistencyKind

DISALLOW_TYPE_COERCION

With this setting, the DataWriter and DataReader must support the same data type in order for them to communicate. (This is the degree of enforcement required by the OMG

DDS Specification prior to the OMG Extensible and Dynamic Topic Types for DDS Specification1.)

When Connext is introspecting the built-in topic data declaration of a remote DataWriter or DataReader, if no TypeConsistencyEnforcementQosPolicy value is provided (as would be the case when communicating with an implementation not in conformance with the Extensible and Dynamic Topic Types for DDS" (DDS-XTypes) specification), Connext shall assume a kind of DISALLOW_TYPE_COERCION.

ALLOW_TYPE_COERCION (default)

With this setting, the DataWriter and the DataReader need not support the same data type in order for them to communicate, as long as the DataReader’s type is assignable from the

DataWriter’s type.

For example, the following two extensible types will be assignable to each other since MyDerivedType contains all the members of MyBaseType (member_1) plus an additional element (member_2).

struct MyBaseType { long member_1;

};

struct MyDerivedType: MyBaseType { long member_2;

};

Even if MyDerivedType was not explicitly inherited from MyBaseType, the types would still be assignable. For example:

struct MyBaseType { long member_1;

};

struct MyDerivedType { long member_1;

long member_2;

};

1. http://www.omg.org/spec/DDS-XTypes/

7-66

For more information, see the Core Libraries and Utilities Getting Started Guide Addendum for Extensible Types and the OMG ‘Extensible and Dynamic Topic Types for DDS’ Specification.

7.6.6.1Properties

This QosPolicy cannot be modified after the DataReader is enabled.

It only applies to DataReaders, so there is no requirement that the publishing and subscribing sides use compatible values.

7.6.6.2Related QoS Policies

None.

7.6.6.3Applicable Entities

DataReaders (Section 7.3)

7.6.6.4System Resource Considerations

None.

7-67

Chapter 8 Working with Domains

This chapter discusses how to use DomainParticipants. It describes the types of operations that are available for them and their QosPolicies.

This chapter includes the following sections:

Fundamentals of Domains and DomainParticipants (Section 8.1)

DomainParticipantFactory (Section 8.2)

DomainParticipants (Section 8.3)

DomainParticipantFactory QosPolicies (Section 8.4)

DomainParticipant QosPolicies (Section 8.5)

Clock Selection (Section 8.6)

System Properties (Section 8.7)

The goal of this chapter is to help you become familiar with the objects you need for setting up your Connext application. For specific details on any mentioned operations, see the API Reference HTML documentation.

8.1Fundamentals of Domains and DomainParticipants

DomainParticipants are the focal point for creating, destroying, and managing other Connext objects. A domain is a logical network of applications: only applications that belong to the same domain may communicate using Connext. A domain is identified by a unique integer value known as a domain ID. An application participates in a domain by creating a DomainParticipant for that domain ID.

As seen in Figure 8.1, a single application can participate in multiple domains by creating multiple DomainParticipants with different domain IDs. DomainParticipants in the same domain form a logical network; they are isolated from DomainParticipants of other domains, even those running on the same set of physical computers sharing the same physical network. DomainParticipants in different domains will never exchange messages with each other. Thus, a domain establishes a “virtual network” linking all DomainParticipants that share the same domain ID.

An application that wants to participate in a certain domain will need to create a "Domain Participant." As seen in Figure 8.2, a DomainParticipant object is a container for all other Entities that belong to the same domain. It acts as factory for the Publisher, Subscriber, and Topic entities.

8-1

Figure 8.1 Relationship between Applications and Domains

Domain-1

Application B

 

Application A

Domain-2

Application C

 

Applications can belong to multiple domains—A belongs to domains 1 and 2. Applications in the same domain can communicate with each other, such as A and B, or A and C. Applications in different domains, such as B and C, are not even aware of each other and will not exchange messages.

(As seen in Chapters 6 and 7, in turn, Publishers are factories for DataWriters and Subscribers are factories for DataReaders.) DomainParticipants cannot contain other DomainParticipants.

Like all Entities, DomainParticipants have QosPolicies and Listeners. The DomainParticipant entity also allows you to set ‘default’ values for the QosPolicies for all the entities created from it or from the entities that it creates (Publishers, Subscribers, Topics, DataWriters, and DataReaders).

Figure 8.2 Domain Module

Note: MultiTopics are not supported.

8-2

8.2DomainParticipantFactory

The main purpose of a DomainParticipantFactory is to create and destroy DomainParticipants.

In C++ terms, this is a singleton class; that is, you will only have a single

DomainParticipantFactory in an application—no matter how many DomainParticipants the application may create. Figure 8.3 shows how to instantiate a DomainParticipantFactory. Notice that there are no parameters to specify. Alternatively, in C++, C++/CLI, and C#, the predefined macro, DDSTheParticipantFactory,1 can also be used to retrieve the singleton factory.

Unlike the other Entities that you create, the DomainParticipantFactory does not have an associated Listener. However, it does have associated QosPolicies, see Section 8.2.1. You can change them using the factory’s get_qos() and set_qos() operations. The DomainParticipantFactory also stores the default QoS settings that can be used when a DomainParticipant is created. These default settings can be changed as well, see Section 8.3.6.4.

Figure 8.3 Instantiating a DomainParticipantFactory

DDSDomainParticipantFactory* factory = NULL;

factory = DDSDomainParticipantFactory::get_instance();

if (factory == NULL) { // ... error

}

Once you have a DomainParticipantFactory, you can use it to perform the operations listed in Table 8.1. The most important one is create_participant(), described in Section 8.3.1. For more details on all operations, see the API Reference HTML documentation as well as the section of the manual listed in the Reference column.

Table 8.1 DomainParticipantFactory Operations

Working

Operation

Description

Reference

with ...

 

 

 

 

 

 

 

 

 

 

 

 

create_participant

Creates a DomainParticipant.

 

 

 

 

Section 8.3.1

 

create_participant_with_

Creates a DomainParticipant based on a QoS

 

profile

profile.

 

 

 

 

 

 

delete_participant

Deletes a DomainParticipant.

Section 8.3.2

 

 

 

 

Domain-

get_default_participant_qos

Gets the default QoS for DomainParticipants.

Section 8.2.2

Participants

lookup_participant

Finds a specific DomainParticipant, based on

Section 8.2.4

 

 

 

a domain ID.

 

 

set_default_participant_qos

Sets the default QoS for DomainParticipants.

 

 

 

 

Section 8.2.2

 

set_default_participant_

Sets the default QoS for DomainParticipants

 

qos_with_profile

based on a QoS profile.

 

 

 

 

 

The

get_instance

Gets the singleton instance of this class.

 

 

 

Section 8.2.3

Factory’s

finalize_instance

Destroys the singleton instance of this class.

Instance

 

 

 

 

 

 

 

 

The

get_qos

Gets/sets the DomainParticipantFactory’s

 

 

Section 4.1.7

Factory’s

set_qos

Own QoS

QoS.

 

 

 

 

 

 

 

 

1. In C, the macro is DDS_TheParticipantFactory. In Java, use the static class method DomainParticipantFac- tory.TheParticipantFactory.

8-3

Table 8.1 DomainParticipantFactory Operations

Working

Operation

 

 

Description

 

 

Reference

with ...

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Frees all resources related to a thread.

 

 

 

 

This function is intended to be used at the

 

Threads

unregister_thread

end of any user-created threads that invoke

 

Connext APIs (not all users will have this

 

 

 

situation). The best approach is to call it

 

 

 

immediately before exiting such a thread,

 

 

 

after all Connext APIs have been called.

 

 

 

 

 

 

 

 

 

 

 

 

get_default_library

Gets

the

default

library

for

a

 

 

DomainParticipantFactory.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

get_default_profile

Gets the default QoS profile for a

Section 8.2.1.1

 

 

DomainParticipantFactory.

 

 

 

 

 

get_default_profile_library

Gets

the library that contains the

default

 

 

QoS profile for a DomainParticipantFactory.

 

 

 

 

 

 

 

 

 

 

 

 

 

Gets

the

<entity> QoS

values associated

 

 

get_<entity>_qos_from_

with a specified QoS profile. <entity> may

 

 

profile

be topic, datareader, datawriter, subscriber,

 

 

 

publisher, or participant.

 

 

 

 

 

 

 

 

 

 

Like get_<entity>_qos_from_profile(), but

Section 8.2.5

 

 

this operation allows you to specify a topic

 

get_<entity>_qos_from_

name associated with the entity. The topic

 

 

filter

expressions in the profile

will

be

 

 

profile_w_topic_name

 

 

evaluated on the topic name.

 

 

 

 

 

 

 

 

Profiles &

 

<entity> may be topic, datareader, or

 

Libraries

 

datawriter.

 

 

 

 

 

 

 

Gets the names of all XML QoS profiles

 

 

get_qos_profiles

associated with a specified XML QoS profile

Section 17.9.5

 

 

library.

 

 

 

 

 

 

 

 

 

 

 

Gets the names of all XML QoS profile

 

 

get_qos_profile_libraries

libraries

associated

with

 

the

Section 17.10.1

 

 

DomainParticipantFactory.

 

 

 

 

 

 

 

 

 

 

 

 

 

load_profiles

Explicitly loads or reloads the QoS profiles.

Section 17.2.1

 

 

 

reload_profiles

 

 

 

 

 

 

 

 

set_default_profile

Sets the default QoS profile for a

DomainParticipantFactory.

 

 

 

 

 

 

 

Section 8.2.1.1

set_default_library

Sets

the

default

library

for

a

 

DomainParticipantFactory.

 

 

 

 

 

 

 

 

 

 

unload_profiles

Frees the resources associated with loading

Section 17.2.1

 

QoS profiles.

 

 

 

 

 

8.2.1Setting DomainParticipantFactory QosPolicies

The DDS_DomainParticipantFactoryQos structure has the following format:

struct DDS_DomainParticipantFactoryQos {

 

DDS_EntityFactoryQosPolicy

entity_factory;

DDS_SystemResourceLimitsQosPolicy

resource_limits;

DDS_ProfileQosPolicy

profile;

DDS_LoggingQosPolicy

logging;

};

 

For information on why you would want to change a particular QosPolicy, see the section referenced in Table 8.2.

8-4

Table 8.2 DomainParticipantFactory QoS

QosPolicy

Description

 

 

 

 

EntityFactory

Controls whether or not child entities are created in the enabled state. See

Section 6.4.2.

 

 

 

Logging

Configures the properties associated with Connext logging. See Section 8.4.1.

 

 

Profile

Configures the way that XML documents containing QoS profiles are loaded by RTI.

See Section 8.4.2.

 

 

 

SystemResource-

Configures DomainParticipant-independent resources used by Connext. Mainly used

to change the maximum number of DomainParticipants that can be created within a

Limits

single process (address space). See Section 8.4.3.

 

 

 

8.2.1.1Getting and Setting the DomainParticipantFactory’s Default QoS Profile and Library

You can retrieve the default QoS profile for the DomainParticipantFactory with the get_default_profile() operation. You can also get the default library for the DomainParticipantFactory, as well as the library that contains the DomainParticipantFactory’s default profile (these are not necessarily the same library); these operations are called get_default_library() and get_default_library_profile(), respectively. These operations are for informational purposes only (that is, you do not need to use them as a precursor to setting a library or profile.) For more information, see Chapter 17: Configuring QoS with XML.

virtual const char * get_default_library () const char * get_default_profile ()

const char * get_default_profile_library ()

There are also operations for setting the DomainParticipantFactory’s default library and profile:

DDS_ReturnCode_t set_default_library (const char * library_name)

DDS_ReturnCode_t set_default_profile (const char * library_name, const char * profile_name)

set_default_profile() specifies the profile that will be used as the default the next time a default DomainParticipantFactory profile is needed during a call to a DomainParticipantFactory operation.

When calling a DomainParticipantFactory operation that requires a profile_name parameter, you can use NULL to refer to the default profile. (This same information applies to setting a default library.)

set_default_profile() does not set the default QoS for the DomainParticipant that can be created by the DomainParticipantFactory. To set the default QoS using a profile, use the DomainParticipantFactory’s set_default_participant_qos_with_profile() operation (see Section 8.2.2).

8.2.2Getting and Setting Default QoS for DomainParticipants

To get the default QoS that will be used for creating DomainParticipants if create_participant() is called with DDS_PARTICIPANT_QOS_DEFAULT as the ‘qos’ parameter, use this DomainParticipantFactory operation:

DDS_ReturnCode_t get_default_participant_qos (

DDS_DomainParticipantQos & qos)

This operation gets the QoS settings that were specified on the last successful call to set_default_participant_qos() or set_default_participant_qos_with_profile(), or if the call was never made, the default values listed in DDS_DomainParticipantQos.

To set the default QoS that will be used for new DomainParticipants, use the following operations. Then these default QoS will be used if create_participant() is called with DDS_PARTICIPANT_QOS_DEFAULT as the ‘qos’ parameter.

8-5

DDS_ReturnCode_t set_default_participant_qos (

const DDS_DomainParticipantQos &qos)

or

DDS_ReturnCode_t set_default_participant_qos_with_profile ( const char *library_name, const char *profile_name)

Notes:

These operations may potentially allocate memory, depending on the sequences contained in some QoS policies.

It is not safe to set the default DomainParticipant QoS values while another thread may be simultaneously calling get_default_participant_qos(), set_default_participant_qos(), or create_participant() with DDS_PARTICIPANT_QOS_DEFAULT as the qos parameter. It is also not safe to get the default DomainParticipant QoS values while another thread may be simultaneously calling set_default_participant_qos().

8.2.3Freeing Resources Used by the DomainParticipantFactory

The finalize_instance() operation explicitly reclaims resources used by the participant factory singleton (including resources use for QoS profiles).

On many operating systems, these resources are automatically reclaimed by the OS when the program terminates. However, some memory-check tools will flag those resources as unreclaimed. This method provides a way to clean up all the memory used by the participant factory.

Before calling finalize_instance() on a DomainParticipantFactory, all of the participants created by the factory must have been deleted. For a DomainParticipant to be successfully deleted, all Entities created by the participant or by the Entities that the participant created must have been deleted. In essence, the DomainParticipantFactory cannot be deleted until all other Entities have been deleted in an application.

Except for Linux systems: get_instance() and finalize_instance() are UNSAFE on the FIRST call. It is not safe for two threads to simultaneously make the first call to get or finalize the factory instance. Subsequent calls are thread safe.

8.2.4Looking Up a DomainParticipant

The DomainParticipantFactory has a useful operation for retrieving the handle to a particular

DomainParticipant:

DDSDomainParticipant* lookup_participant (DDS_DomainId_t domainId)

8.2.5Getting QoS Values from a QoS Profile

A QoS Profile may include configuration settings for all types of Entities. If you just want the settings for a specific type of Entity, call get_<entity>_qos_from_profile() (where <entity> may be participant, publisher, subscriber, datawriter, datareader, or topic). This is useful if you want to get the QoS values from the profile in a structure, make some changes, and then use that structure to create an entity.

DDS_ReturnCode_t get_<entity>_qos_from_profile ( DDS_<Entity>Qos &qos,

const char *library_name, const char *profile_name)

For an example, see Figure 6.5 on page 6-10.

The get_<entity>_qos_from_profile() operations do not take into account the topic_filter attributes that may be set for DataWriter, DataReader, or Topic QoSs in profiles (see Section 17.9.3).

8-6

If there is a topic name associated with an entity, you can call get_<entity>_qos_from_profile_w_topic_name() (where <entity> can be datawriter, datareader, or topic) and the topic filter expressions in the profile will be evaluated on the topic name.

DDS_ReturnCode_t get_<entity>_qos_from_profile_w_topic_name( DDS_<entity>Qos &qos, const char *library_name, const char *profile_name, const char *topic_name)

get_<entity>_qos_from_profile() and get_<entity>_qos_from_profile_w_topic_name() may allocate memory, depending on the sequences contained in some QoS policies.

8.3DomainParticipants

A DomainParticipant is a container for Entity objects that all belong to the same domain. Each DomainParticipant has its own set of internal threads and internal data structures that maintain information about the Entities created by itself and other DomainParticipants in the same domain. A DomainParticipant is used to create and destroy Publishers, Subscribers and Topics.

Once you have a DomainParticipant, you can use it to perform the operations listed in Table 8.3. For more details on all operations, see the API Reference HTML documentation. Some of the first operations you’ll be interested in are create_topic(), create_subscriber(), and create_publisher().

Note: Some operations cannot be used within a listener callback, see Restricted Operations in Listener Callbacks (Section 4.5.1).

Table 8.3 DomainParticipant Operations

Working

Operation

 

 

Description

 

 

Reference

with ...

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Builtin

get_builtin_subscriber

Returns the builtin Subscriber.

 

 

Section 16.2

Subscriber

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

add_peer

Adds an entry to the peer list.

 

 

Section 8.5.2.3

 

 

 

 

 

 

 

enable

Enables the DomainParticipant.

 

 

Section 4.1.2

 

 

 

 

 

 

get_discovered_participant_

Provides the

ParticipantBuiltinTopicData

 

 

data

for a discovered DomainParticipant.

 

Section 8.3.11

 

 

 

 

 

 

 

 

 

get_discovered_participants

Provides a list of DomainParticipants that

 

 

 

 

have been discovered.

 

 

 

 

 

get_domain_id

Gets

the

domain

ID

of

the

Section 8.3.4

 

 

DomainParticipant.

 

 

 

 

Domain-

get_listener

Gets

the

currently

installed

Section 8.3.5

Participants

 

DomainParticipantListener.

 

 

 

 

 

get_qos

Gets the DomainParticipant QoS.

 

 

Section 8.3.6

 

 

 

 

 

ignore_participant

Rejects the connection to a remote

Section 16.4

 

 

DomainParticipant.

 

 

 

 

 

remove_peer

Removes an entry from the peer list.

 

Section 8.5.2.3

 

 

 

 

 

 

set_listener

Replaces the DomainParticipantListener.

 

Section 8.3.5

 

 

 

 

 

 

 

set_qos

Sets the DomainParticipant QoS.

 

 

 

 

 

 

Section 8.3.6

 

set_qos_with_profile

Sets the DomainParticipant QoS based on a

 

QoS profile.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

8-7

Table 8.3 DomainParticipant Operations

Working

Operation

 

 

Description

 

Reference

with ...

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

create_contentfilteredtopic

Creates a ContentFilteredTopic that can be

 

 

create_contentfilteredtopic_

used

to

process

content-based

Section 5.4.3

Content-

with_filter

subscriptions.

 

 

 

 

 

 

 

 

 

 

 

 

delete_contentfilteredtopic

Deletes a ContentFilteredTopic.

 

Section 5.4.4

Filtered-

 

 

 

 

 

 

 

 

 

Topics

register_contentfilter

Registers a new content filter.

 

Section 5.4.8.2

 

 

 

 

 

 

unregister_contentfilter

Unregisters a new content filter.

 

Section 5.4.8.3

 

 

 

 

 

lookup_contentfilter

Gets a previously registered content filter.

Section 5.4.8.4

 

 

 

 

 

 

Creates a DataReader with a given

 

 

create_datareader

DataReaderListener,

and

an

implicit

 

 

 

Subscriber.

 

 

 

 

Section 7.3.1

 

 

 

 

 

 

 

 

 

create_datareader_with_

Creates

a

DataReader

based on

a QoS

 

 

 

profile, with a given DataReaderListener,

 

 

profile

 

 

and an implicit Subscriber.

 

 

 

 

 

 

 

 

 

 

 

 

 

delete_datareader

Deletes a DataReader that belongs to the

Section 7.3.3

DataReaders

‘implicit Subscriber.

 

 

 

 

 

 

 

 

get_default_datareader_qos

Copies the default DataReaderQoS values

 

 

into the provided structure.

 

 

 

 

 

 

 

ignore_subscription

Rejects the connection to a DataReader

Section 8.3.6.4

 

 

 

 

 

 

 

 

 

set_default_datareader_qos

Sets the default DataReaderQos values.

 

 

 

 

 

 

 

set_default_datareader_

Sets the default DataReaderQos using

 

 

qos_with_profile

values from a QoS profile.

 

 

 

 

 

 

 

 

 

Creates a DataWriter with a given

 

 

create_datawriter

DataWriterListener,

and

an

implicit

 

 

 

Publisher.

 

 

 

 

Section 6.2.2

 

 

 

 

 

 

 

 

 

create_datawriter_with_

Creates

a

DataWriter

based on

a QoS

 

 

 

profile, with a given DataWriterListener,

 

 

profile

 

 

and an implicit Publisher.

 

 

 

 

 

 

 

 

 

 

 

 

 

delete_datawriter

Deletes a DataWriter that belongs to the

Section 6.2.3

DataWriters

 

‘implicit Publisher.

 

 

 

 

ignore_publication

Rejects the connection to a DataWriter.

Section 16.4

 

 

 

 

 

 

 

Copies the default DataWriterQos values

 

 

get_default_datawriter_qos

into

the

provided

DataWriterQos

 

 

 

structure.

 

 

 

 

Section 8.3.6.4

 

 

 

 

 

 

 

 

 

set_default_datawriter_qos

Sets the default DataWriterQoS values.

 

 

 

 

 

 

 

set_default_datawriter_

Sets the default DataWriterQos using

 

 

qos _with_profile

values from a profile.

 

 

 

 

 

 

 

 

 

 

 

 

 

8-8

Table 8.3 DomainParticipant Operations

Working

Operation

 

 

Description

 

 

Reference

with ...

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

create_publisher

Creates

a

Publisher

and

a

 

 

PublisherListener.

 

 

 

 

 

 

 

Section 6.2.2

 

 

 

 

 

 

 

 

create_publisher_with_

Creates a Publisher based on a QoS profile,

 

 

 

profile

and a PublisherListener.

 

 

 

 

 

 

 

 

 

 

delete_publisher

Deletes a Publisher.

 

 

Section 6.2.3

 

 

 

 

 

get_default_publisher_qos

Copies the default PublisherQos values

Section 8.3.6.4

Publishers

 

into the provided PublisherQos structure.

 

get_implicit_publisher

Gets the Publisher that is implicitly created

Section 8.3.9

 

 

 

by the DomainParticipant.

 

 

 

 

get_publishers

Provides a list of all Publishers owned by

Section 8.3.13.3

 

 

the DomainParticipant.

 

 

 

 

set_default_publisher_qos

Sets the default PublisherQos values.

 

 

 

 

 

Section 8.3.6.4

 

set_default_publisher_qos_

Sets the default PublisherQos using values

 

with_profile

from a QoS profile.

 

 

 

 

 

 

 

 

 

 

 

 

create_subscriber

Creates

a

Subscriber

and

a

 

 

SubscriberListener.

 

 

 

 

 

 

 

Section 7.2.2

 

 

 

 

 

 

 

 

create_subscriber_with_

Creates a Subscriber based on a QoS

 

 

 

profile

profile, and a SubscriberListener.

 

 

 

 

 

 

 

 

 

delete_subscriber

Deletes a Subscriber.

 

 

Section 7.2.3

 

 

 

 

 

get_default_subscriber_qos

Copies the default SubscriberQos values

Section 8.3.6.4

Subscribers

 

into the provided SubscriberQos structure.

 

get_implicit_subscriber

Gets the Subscriber that is implicitly

Section 8.3.9

 

 

 

created by the DomainParticipant.

 

 

 

get_subscribers

Provides a list of all Subscribers owned by

Section 8.3.13.3

 

 

the DomainParticipant.

 

 

 

 

set_default_subscriber_qos

Sets the default SubscriberQos values.

 

 

 

 

 

Section 8.3.6.4

 

set_default_subscriber_qos_

Sets the default SubscriberQos values

 

with_profile

using values from a QoS profile.

 

 

 

 

 

 

 

 

 

Deletes an existing Durable Subscription.

 

 

delete_durable_subscription

The quorum of the existing samples will

 

 

 

be considered satisfied.

 

 

 

 

 

 

 

 

 

Creates a Durable Subscription that will

 

 

 

receive all samples published on a Topic,

 

 

 

including those published while a

 

 

 

DataReader is inactive or before it may be

 

 

 

created.

 

 

 

 

 

Durable

 

RTI Persistence Service will ensure that all

Section 27.9

 

the samples on that Topic are retained until

Subscriptions

 

register_durable_

they are acknowledged by at least N

 

 

 

 

subscription

DataReaders belonging to the Durable

 

 

 

Subscription, where N is the quorum

 

 

 

count.

 

 

 

 

 

 

 

If the same Durable Subscription is

 

 

 

created on a different Topic, RTI Persistence

 

 

 

Service will implicitly delete the previous

 

 

 

Durable Subscription and create a new

 

 

 

one on the new Topic.

 

 

 

 

 

 

 

 

 

 

 

8-9

Table 8.3 DomainParticipant Operations

Working

Operation

 

 

 

Description

 

 

Reference

with ...

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

create_topic

Creates a Topic and a TopicListener.

 

 

 

 

 

 

 

 

create_topic _with_profile

Creates a Topic based on a QoS profile,

Section 5.1.1

 

 

and a TopicListener.

 

 

 

 

 

delete_topic

Deletes a Topic.

 

 

 

 

 

 

 

 

 

 

get_default_topic_qos

Copies the default TopicQos values into

Section 8.3.6.4

 

 

the provided TopicQos structure.

 

 

 

 

get_discovered_topic_data

Retrieves

the

BuiltinTopicData

for

a

 

 

discovered Topic.

 

 

 

 

 

 

 

 

 

 

 

Section 8.3.12

 

 

 

 

 

 

 

 

 

 

Topics

get_discovered_topics

Returns

a

list

of all (non-ignored)

 

 

discovered Topics.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

ignore_topic

Rejects a remote topic.

 

 

 

Section 16.4

 

 

 

 

 

 

 

 

lookup_topicdescription

Gets

an

existing

locally-created

Section 8.3.7

 

 

TopicDescription (Topic).

 

 

 

 

 

set_default_topic_qos

Sets the default TopicQos values.

 

 

 

 

 

 

Section 8.3.6.4

 

set_default_topic_qos_with

Sets the default TopicQos values using

 

_profile

values from a profile.

 

 

 

 

 

 

 

 

 

find_topic

Finds an existing Topic, based on its name.

Section 8.3.8

 

 

 

 

 

create_flowcontroller

Creates a custom FlowController object.

Section 6.6.6

 

 

 

 

 

 

 

 

 

 

 

delete_flowcontroller

Deletes a custom FlowController object.

 

 

 

 

 

 

Flow-

get_default_flowcontroller_

Gets the default properties used when a

 

property

new FlowController is created.

 

 

 

Controllers

 

 

Section 6.6.7

 

 

 

 

 

 

 

 

 

set_default_flowcontroller_

Sets the default properties used when a

 

 

 

property

new FlowController is created.

 

 

 

 

 

 

 

 

lookup_flowcontroller

Finds a FlowController, based on its name.

Section 6.6.10

 

 

 

 

 

 

 

 

get_default_library

Gets the default library.

 

 

 

 

 

 

 

 

 

 

 

 

get_default_profile

Gets the default profile.

 

 

 

 

 

 

 

 

Libraries

get_default_profile_library

Gets the library that contains the default

Section 8.3.6.3

and Profiles

profile.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

set_default_profile

Sets the default QoS profile.

 

 

 

 

 

 

 

 

 

 

 

set_default_library

Sets the default library.

 

 

 

 

 

 

 

 

 

 

Creates a MultiTopic that can be used to

 

 

create_multitopic

subscribe to multiple topics and combine/

Currently not

MultiTopics

filter

the

received data

into a resulting

 

 

type.

 

 

 

 

 

 

 

supported.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

delete_multitopic

Deletes a MultiTopic.

 

 

 

 

 

 

 

 

 

assert_liveliness

Manually asserts the liveliness of this

Section 8.3.9

 

 

DomainParticipant.

 

 

 

 

 

 

Recursively deletes all the entities that

 

 

delete_contained_entities

were created using the "create" operations

Section 8.3.3

 

 

on the DomainParticipant and its children.

 

 

 

 

 

 

 

 

 

 

 

Other

contains_entity

Confirms

if

an

entity

belongs

to

the

Section 8.3.13.1

 

DomainParticipant or not.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

get_current_time

Gets the current time used by Connext.

 

Section 8.3.13.2

 

 

 

 

 

 

Gets a list of statuses that have changed

 

 

get_status_changes

since the last time the application read the

Section 4.1.4

 

 

status or the Listeners were called.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

8-10

8.3.1Creating a DomainParticipant

Typically, you will only need to create one DomainParticipant per domain per application. (Although unusual, you can create multiple DomainParticipants for the same domain in an application.)

To create a DomainParticipant, use the DomainParticipantFactory’s create_participant() or create_participant_with_profile() operation:

DDSDomainParticipant * create_participant( DDS_DomainId_t domainId,

const DDS_DomainParticipantQos &qos,

DDSDomainParticipantListener *listener, DDS_StatusMask mask)

DDSDomainParticipant * create_participant_with_profile ( DDS_DomainId_t domainId,

const char * library_name, const char *profile_name,

DDSDomainParticipantListener *listener, DDS_StatusMask mask)

A QoS profile is way to use QoS settings from an XML file or string. With this approach, you can change QoS settings without recompiling the application. For details, see Chapter 17: Configuring QoS with XML.

domainId The domain ID uniquely identifies the domain that the DomainParticipant is in. It controls with which other DomainParticipants it will communicate. See Section 8.3.4 for more information on domain IDs.

qos If you want the default QoS settings (described in the API Reference HTML documentation), use DDS_PARTICIPANT_QOS_DEFAULT for this parameter (see Figure 8.4 on page 8-12). If you want to customize any of the QosPolicies, supply a DomainParticipantQos structure that is described in Section 8.3.6.

Note: If you use DDS_PARTICIPANT_QOS_DEFAULT, it is not safe to create the

DomainParticipant while another thread may simultaneously be calling the DomainPartici- pantFactory’s set_default_participant_qos() operation.

listener Listeners are callback routines. Connext uses them to notify your application of specific events (status changes) that may occur. The listener parameter may be set to NULL if you do not want to install a Listener. The DomainParticipant’s Listener is a catchall for all of the events of all of its Entities. If an event is not handled by an Entity’s Listener, then the DomainParticipantListener may be called in response to the event. For more information, see Setting Up DomainParticipantListeners (Section 8.3.5).

mask This bit mask indicates which status changes will cause the Listener to be invoked. The bits set in the mask must have corresponding callbacks implemented in the Listener. If you use NULL for the Listener, use DDS_STATUS_MASK_NONE for this parameter. If the Listener implements all callbacks, use DDS_STATUS_MASK_ALL. For information on statuses, see Listeners (Section 4.4).

library_name A QoS Library is a named set of QoS profiles. See QoS Libraries (Section 17.10).

profile_name A QoS profile groups a set of related QoS, usually one per entity. See QoS Profiles (Section 17.9).

After you create a DomainParticipant, the next step is to register the data types that will be used by the application, see Using rtiddsgen (Section 3.6). Then you will need to create the Topics that the application will publish and/or subscribe, see Creating Topics (Section 5.1.1). Finally, you will use the DomainParticipant to create Publishers and/or Subscribers, see Creating Publishers (Section 6.2.2) and Creating Subscribers (Section 7.2.2).

Note: It is not safe to create one DomainParticipant while another thread may simultaneously be looking up (Section 8.2.4) or deleting (Section 8.3.2) the same DomainParticipant.

8-11

For more examples, see Configuring QoS Settings when the DomainParticipant is Created (Section 8.3.6.1).

Figure 8.4 Creating a DomainParticipant with Default QosPolicies

DDS_DomainId_t domain_id = 10;

//MyDomainParticipantListener is user defined and

//extends DDSDomainParticipantListener

MyDomainParticipantListener* participant_listener

=new MyDomainParticipantListener(); // or = NULL

//Create the participant

DDSDomainParticipant* participant = factory->create_participant(domain_id,

DDS_PARTICIPANT_QOS_DEFAULT, participant_listener, DDS_STATUS_MASK_ALL);

if (participant == NULL) { // ... error

};

8.3.2Deleting DomainParticipants

If the application is no longer interested in communicating in a certain domain, the DomainParticipant can be deleted. A DomainParticipant can be deleted only after all the entities that were created by the DomainParticipant have been deleted (see Deleting Contained Entities (Section 8.3.3)).

To delete a DomainParticipant:

1.You must first delete all Entities (Publishers, Subscribers, ContentFilteredTopics, and Topics) that were created with the DomainParticipant. Use the DomainParticipant’s delete_<entity>() operations to delete them one at a time, or use the delete_contained_entities() operation (Section 8.3.3) to delete them all at the same time.

DDS_ReturnCode_t delete_publisher (DDSPublisher *p) DDS_ReturnCode_t delete_subscriber (DDSSubscriber *s) DDS_ReturnCode_t delete_contentfilteredtopic

(DDSContentFilteredTopic *a_contentfilteredtopic) DDS_ReturnCode_t delete_topic (DDSTopic *topic)

2.Delete the DomainParticipant by using the DomainParticipantFactory’s delete_participant() operation.

DDS_ReturnCode_t delete_participant

(DDSDomainParticipant *a_participant)

Note: A DomainParticipant cannot be deleted within its Listener callback, see Restricted Operations in Listener Callbacks (Section 4.5.1).

After a DomainParticipant has been deleted, all of the participant’s internal Connext threads and allocated memory will have been deleted. You should delete the DomainParticipantListener only after the DomainParticipant itself has been deleted.

8.3.3Deleting Contained Entities

The DomainParticipant’s delete_contained_entities() operation deletes all the Publishers

(including an implicitly created one, if it exists), Subscribers (including an implicitly created one, if it exists), ContentFilteredTopics, and Topics that have been created by the DomainParticipant.

8-12

DDS_ReturnCode_t delete_contained_entities( )

Prior to deleting each contained entity, this operation recursively calls the corresponding delete_contained_entities() operation on each contained entity (if applicable). This pattern is applied recursively. Therefore, delete_contained_entities() on the DomainParticipant will end up deleting all the entities recursively contained in the DomainParticipant, that is also the DataWriter, DataReader, as well as the QueryCondition and ReadCondition objects belonging to the contained

DataReader.

If delete_contained_entities() returns successfully, the application may delete the DomainParticipant knowing that it has no contained entities (see Deleting DomainParticipants (Section 8.3.2)).

8.3.4Choosing a Domain ID and Creating Multiple Domains

A domain ID identifies the domain in which the DomainParticipant is communicating. DomainParticipants with the same domain ID are on the same communication “channel”. DomainParticipants with different domain IDs are completely isolated from each other.

The domain ID is a purely arbitrary value; you can use any integer 0 or higher, provided it does not violate the guidelines for the DDS_RtpsWellKnownPorts_t structure (Section 8.5.9.3). Domain IDs are typically between 0 and 232. Please see the API Reference HTML documentation for the DDS_RtpsWellKnownPorts_t structure and in particular, DDS_INTEROPERABLE_RTPS_WELL_KNOWN_PORTS.

Most distributed systems can use a single domain for all of its applications. Thus a single domain ID is sufficient. Some systems may need to logically partition nodes to prevent them from communicating with each other directly, and thus will need to use multiple domains. However, even in systems that only use a single domain, during the testing and development phases, one may want to assign different users/testers different domain IDs for running their applications so that their tests do not interfere with each other.

To run multiple applications on the same node with the same domain ID, Connext uses a participant ID to distinguish between the different DomainParticipants in the different applications. The participant ID is simply an integer value that must be unique across all DomainParticipants created on the same node that use the same domain ID. The participant_id is part of the WIRE_PROTOCOL QosPolicy (DDS Extension) (Section 8.5.9).

Although usually those DomainParticipants have been created in different applications, the same application can also create multiple DomainParticipants with the same domain ID. For optimal results, the participant_id should be assigned sequentially to the different DomainParticipants, starting from the default value of 0.

Once you have a DomainParticipant, you can retrieve its domain ID with the get_domain_id() operation.

The domain ID and participant ID are mapped to port numbers that are used by transports for discovery traffic. For information on how port numbers are calculated, see Ports Used for Discovery (Section 14.5). How DomainParticipants discover each other is discussed in Chapter 14.

8.3.5Setting Up DomainParticipantListeners

DomainParticipants may optionally have Listeners. Listeners are essentially callback routines and are how Connext will notify your application of specific events (changes in status) for entities

Topics, Publishers, Subscribers, DataWriters, and DataReaders. Each Entity may have a Listener installed and enabled to process the events for itself and all of the sub-Entities created from it. If an Entity does not have a Listener installed or is not enabled to listen for a particular event, then Connext will propagate the event to the Entity’s parent. If the parent Entity does not process the event, Connext will continue to propagate the event up the object hierarchy until either a Listener is invoked or the event is dropped.

8-13

The DomainParticipantListener is the last chance that an event can be processed for the Entities descended from a DomainParticipant. The DomainParticipantListener is used only if an event is not handled by any of the Entities contained by the participant.

A Listener is typically set up when the DomainParticipant is created (see Section 8.3.1). You can also set one up after creation time by using the set_listener() operation, as illustrated in Figure 8.5 on page 8-14. The get_listener() operation can be used to retrieve the current

DomainParticipantListener.

Figure 8.5 Setting up DomainParticipantListener

//MyDomainParticipantListener only handles PUBLICATION_MATCHED and

//SUBSCRIPTION_MATCHED status for DomainParticipant Entities class MyDomainParticipantListener :

public DDSDomainParticipantListener { public:

virtual void on_publication_matched(DDSDataWriter *writer,

const DDS_PublicationMatchedStatus &status); virtual void on_subscription_matched(DDSDataReader *reader, const DDS_SubscriptionMatchedStatus &status);

};

void MyDomainParticipantListener::on_publication_matched( DDSDataWriter *writer, const DDS_PublicationMatchedStatus &status)

{

const char *name = writer->get_topic()->get_name(); printf(“Number of matching DataReaders for Topic %s is %d\n”,

name, status.current_count);

};

void MyDomainParticipantListener::on_subscription_matched( DDSDataReader *reader,

const DDS_SubscriptionMatchedStatus &status)

{

const char *name = reader->get_topicdescription()->get_name(); printf(“Number of matching DataWriters for Topic %s is %d\n”,

name, status.current_count);

};

// Set up participant listener MyDomainParticipantListener* participant_listener =

new MyDomainParticipantListener();

if (participant_listener == NULL) { // ... handle error

}

// Create the participant with a listener

DDSDomainParticipant* participant = factory->create_participant( domain_id, participant_qos, participant_listener,

DDS_PUBLICATION_MATCHED_STATUS | DDS_SUBSCRIPTION_MATCHED_STATUS );

if (participant == NULL) { // ... handle error

}

If a Listener is set for a DomainParticipant, the Listener needs to exist as long as the DomainParticipant exists. It is unsafe to destroy the Listener while it is attached to a participant. However, you may remove the DomainParticipantListener from a DomainParticipant by calling set_listener() with a NULL value. Once the Listener has been removed from the participant, you may safely destroy it (see Types of Listeners (Section 4.4.1)).

8-14

Note: Due to a thread-safety issue, the destruction of a DomainParticipantListener from an enabled DomainParticipant should be avoided—even if the DomainParticipantListener has been removed from the DomainParticipant. (This limitation does not affect the Java API.)

Note: It is possible for multiple internal Connext threads to call the same method of a DomainParticipantListener simultaneously. You must write the methods of a DomainParticipantListener to be multithread safe and reentrant. The methods of the Listener of other Entities do not have this constraint and are guaranteed to have single threaded access.

See also:

Setting Up TopicListeners (Section 5.1.5)

Setting Up PublisherListeners (Section 6.2.5)

Setting Up DataWriterListeners (Section 6.3.4)

Setting Up SubscriberListeners (Section 7.2.6)

Setting Up DataReaderListeners (Section 7.3.4)

8.3.6Setting DomainParticipant QosPolicies

A DomainParticipant’s QosPolicies are used to configure discovery, database sizing, threads, information sent to other DomainParticipants, and the behavior of the DomainParticipant when acting as a factory for other Entities.

Note: set_qos() cannot always be used in a listener callback; see Restricted Operations in Listener Callbacks (Section 4.5.1).

The DDS_DomainParticipantQos structure has the following format:

struct DDS_DomainParticipantQos {

 

DDS_UserDataQosPolicy

user_data;

DDS_EntityFactoryQosPolicy

entity_factory;

DDS_WireProtocolQosPolicy

wire_protocol;

DDS_TransportBuiltinQosPolicy

transport_builtin;

DDS_TransportUnicastQosPolicy

default_unicast;

DDS_DiscoveryQosPolicy

discovery;

DDS_DomainParticipantResourceLimitsQosPolicy resource_limits;

DDS_EventQosPolicy

event;

DDS_ReceiverPoolQosPolicy

receiver_pool;

DDS_DatabaseQosPolicy

database;

DDS_DiscoveryConfigQosPolicy

discovery_config;

DDS_PropertyQosPolicy

property;

DDS_EntityNameQosPolicy

participant_name;

DDS_TransportMulticastMappingQosPolicy

multicast_mapping;

DDS_TypeSupportQosPolicy

type_support;

};

 

Table 8.4 summarizes the meaning of each policy (listed alphabetically). For information on why you would want to change a particular QosPolicy, see the section referenced in the table.

Table 8.4 DomainParticipant QosPolicies

QosPolicy

Description

 

 

Database

Various settings and resource limits used by Connext to control its

internal database. See Section 8.5.1.

 

 

 

 

Configures the mechanism used by Connext to automatically

Discovery

discover and connect with new remote applications. See

 

Section 8.5.2.

 

 

8-15

Table 8.4 DomainParticipant QosPolicies

QosPolicy

 

 

Description

 

 

 

 

 

 

 

 

 

 

Controls the amount of delay in discovering entities in the system

DiscoveryConfig

and the amount of discovery traffic in the network. See

 

Section 8.5.3.

 

 

 

 

 

 

 

 

 

 

Various settings that configure how DomainParticipants allocate and

DomainParticipantResourceLimits

use physical memory for internal resources, including the

 

maximum sizes of various properties. See Section 8.5.4.

 

 

 

EntityFactory

Controls whether or not child entities are created in the enabled

state. See Section 6.4.2.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

EntityName

Assigns a name to a DomainParticipant. See Section 6.5.9.

 

 

 

 

 

 

Event

Configures

the DomainParticipant’s internal

thread

that handles

timed events. See Section 8.5.5.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Stores name/value(string) pairs that can be used to configure

 

certain parameters of Connext that are not exposed through formal

Property

QoS policies. It can also be used to store and propagate application-

 

specific name/value pairs, which can be retrieved by user code

 

during discovery. See Section 6.5.17.

 

 

 

 

 

 

 

ReceiverPool

Configures threads used by Connext to receive and process data

from transports (for example, UDP sockets). See Section 8.5.6.

 

 

 

 

 

 

 

 

 

 

 

 

TransportBuiltin

Specifies

which

built-in

transport

plugins

are

used.

See

Section 8.5.7.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Specifies the automatic mapping between a list of topic expressions

TransportMulticastMapping

and multicast address that can be used by a DataReader to receive

 

data for a specific topic. See Section 8.5.8.

 

 

 

 

 

 

 

TransportUnicast

Specifies a subset of transports and port number that can be used by

an Entity to receive data. See Section 6.5.23.

 

 

 

 

 

 

 

 

 

 

 

 

Used to attach application-specific value(s) to a DataWriter or

TypeSupport

DataReader. These

values

are passed

to

the

serialization

or

deserialization routine of the associated

data

type.

See

 

 

Section 6.5.24.

 

 

 

 

 

 

 

 

 

 

Along with Topic Data QosPolicy and Group Data QosPolicy, used

UserData

to attach a buffer of bytes to Connext's discovery meta-data. See

 

Section 6.5.25.

 

 

 

 

 

 

 

 

 

WireProtocol

Specifies IDs used by the RTPS wire protocol to create globally

unique identifiers. See Section 8.5.9.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

8.3.6.1Configuring QoS Settings when the DomainParticipant is Created

As described in Creating a DomainParticipant (Section 8.3.1), there are different ways to create a DomainParticipant, depending on how you want to specify its QoS (with or without a QoS Profile).

In Figure 8.4 on page 8-12, we saw an example of how to create a DomainParticipant with default QosPolicies by using the special constant, DDS_PARTICIPANT_QOS_DEFAULT, which indicates that the default QoS values for a DomainParticipant should be used. The default DomainParticipant QoS values are configured in the DomainParticipantFactory; you can change them with set_default_participant_qos() or set_default_participant_qos_with_profile() (see

Section 8.2.2). Then any DomainParticipants created with the DomainParticipantFactory will use the new default values. As described in Section 4.1.7, this is a general pattern that

8-16

applies to the construction of all Entities.

To create a DomainParticipant with non-default QoS without using a QoS Profile, see the example code in Figure 8.6 on page 8-17. It uses the DomainParticipantFactory’s get_default_participant_qos() method to initialize a DDS_ParticipantQos structure. Then, the policies are modified from their default values before the structure is used in the create_participant() method.

You can also create a DomainParticipant and specify its QoS settings via a QoS Profile. To do so, you will call create_participant_with_profile(), as seen in Figure 8.7 on page 8-17.

If you want to use a QoS profile, but then make some changes to the QoS before creating the DomainParticipant, call get_participant_qos_from_profile() and create_participant() as seen in Figure 8.8 on page 8-18.

For more information, see Creating a DomainParticipant (Section 8.3.1) and Chapter 17: Configuring QoS with XML.

Figure 8.6 Creating a DomainParticipant with Modified QosPolicies (not from a profile)

DDS_DomainId_t domain_id = 10;

DDS_DomainParticipantQos participant_qos;1

//initialize participant_qos with default values factory->get_default_participant_qos(participant_qos);

//make QoS changes here

participant_qos.wire_protocol.participant_id = 2;

// Create the participant with modified qos DDSDomainParticipant* participant = factory->create_participant(

domain_id, participant_qos, NULL, DDS_STATUS_MASK_NONE);

if (participant == NULL) { // ... error

}

1. Note: In C, you must initialize the QoS structures before they are used, see Section 4.2.2.

Figure 8.7 Creating a DomainParticipant with a QoS Profile

DDS_DomainId_t domain_id = 10;

//MyDomainParticipantListener is user defined and

//extends DDSDomainParticipantListener

MyDomainParticipantListener* participant_listener

=new MyDomainParticipantListener(); // or = NULL

//Create the participant

DDSDomainParticipant* participant = factory->create_participant_with_profile(domain_id,

“MyDomainLibrary”, “MyDomainProfile”, participant_listener, DDS_STATUS_MASK_ALL);

if (participant == NULL) { // ... error

};

8-17

Figure 8.8 Getting QoS Values from a Profile, Changing QoS Values, Creating a

DomainParticipant with Modified QoS Values

DDS_DomainParticipantQos participant_qos; // Get domain participant QoS from profile

retcode = factory->get_participant_qos_from_profile( participant_qos1, “DomainParticipantProfileLibrary”, “DomainParticipantProfile”);

if (retcode != DDS_RETCODE_OK) { // handle error

}

// Makes QoS changes here participant_qos.entity_factory.autoenable_created_entities = DDS_BOOLEAN_FALSE;

// create participant with modified QoS

DDSDomainParticipant* participant = factory->create_participant(domain_id, participant_qos, NULL, DDS_STATUS_MASK_NONE);

if (participant == NULL) { // handle error

}

8.3.6.2Changing QoS Settings After the DomainParticipant Has Been Created

There are two ways to change an existing DomainParticipant’s QoS after it is has been created— again depending on whether or not you are using a QoS Profile.

To change QoS programmatically (that is, without using a QoS Profile), use get_qos() and set_qos(). See the example code in Figure 8.9. It retrieves the current values by calling the DomainParticipant’s get_qos() operation. Then it modifies the value and calls set_qos() to apply the new value. Note, however, that some QosPolicies cannot be changed after the DomainParticipant has been enabled—this restriction is noted in the descriptions of the individual QosPolicies.

Figure 8.9 Changing the QoS of an Existing Participant (without a QoS Profile)

DDS_DomainParticipantQos participant_qos;1

// Get current QoS.

//participant points to an existing DDSDomainParticipant.

if (participant->get_qos(participant_qos) != DDS_RETCODE_OK) { // handle error

}

// Make QoS changes participant_qos.entity_factory.autoenable_created_entities =

DDS_BOOLEAN_FALSE;

// Set the new QoS

if (participant->set_qos(participant_qos) != DDS_RETCODE_OK ) { // handle error

}

1. For the C API, you need to use DDS_ParticipantQos_INITIALIZER or DDS_ParticipantQos_initialize(). See Spe- cial QosPolicy Handling Considerations for C (Section 4.2.2)

You can also change a DomainParticipant’s (and all other Entities’) QoS by using a QoS Profile and calling set_qos_with_profile(). For an example, see Figure 8.10. For more information, see Chapter 17: Configuring QoS with XML.

8-18

Figure 8.10 Changing the QoS of an Existing Participant with a QoS Profile

retcode = participant->set_qos_with_profile( “ParticipantProfileLibrary”,”ParticipantProfile”);

if (retcode != DDS_RETCODE_OK) { // handle error

}

8.3.6.3Getting and Setting the DomainParticipant’s Default QoS Profile and Library

You can get the default QoS profile for the DomainParticipant with the get_default_profile() operation. You can also get the default library for the DomainParticipant, as well as the library that contains the DomainParticipant’s default profile (these are not necessarily the same library); these operations are called get_default_library() and get_default_library_profile(), respectively. These operations are for informational purposes only (that is, you do not need to use them as a precursor to setting a library or profile.) For more information, see Chapter 17: Configuring QoS with XML.

virtual const char * get_default_library ()

const char * get_default_profile ()

const char * get_default_profile_library ()

There are also operations for setting the DomainParticipant’s default library and profile:

DDS_ReturnCode_t set_default_library (const char * library_name)

DDS_ReturnCode_t set_default_profile (const char * library_name, const char * profile_name)

If the default profile/library is not set, the DomainParticipant inherits the default from the DomainParticipantFactory.

set_default_profile() specifies the profile that will be used as the default the next time a default DomainParticipant profile is needed during a call to one of this DomainParticipant’s operations. When calling a DomainParticipant operation that requires a profile_name parameter, you can use NULL to refer to the default profile. (This same information applies to setting a default library.)

set_default_profile() does not set the default QoS for entities created by the DomainParticipant; for this functionality, use the DomainParticipant’s set_default_<entity>_qos_with_profile() operation (you may pass in NULL after having called set_default_profile(), see Section 8.3.6.4).

set_default_profile() does not set the default QoS for newly created DomainParticipants; for this functionality, use the DomainParticipantFactory’s set_default_participant_qos_with_profile(), see Section 8.2.2).

8.3.6.4Getting and Setting Default QoS for Child Entities

The set_default_<entity>_qos() and set_default_<entity>_qos_with_profile() operations set the default QoS that will be used for newly created entities (where <entity> may be publisher, subscriber, datawriter, datareader, or topic). The new QoS settings will only be used if DDS_<entity>_QOS_DEFAULT is specified as the qos parameter when create_<entity>() is called. For example, for a Publisher, you can use either:

DDS_ReturnCode_t set_default_publisher_qos (

const DDS_PublisherQos &qos)

DDS_ReturnCode_t set_default_publisher_qos_with_profile (

const char *library_name,

8-19

const char *profile_name)

The following operation gets the default QoS that will be used for creating Publishers if DDS_PUBLISHER_QOS_DEFAULT is specified as the ‘qos’ parameter when create_publisher() is called:

DDS_ReturnCode_t get_default_publisher_qos (DDS_PublisherQos & qos)

There are similar operations for Subscribers, DataWriters, DataReaders and Topics. These operations, get_default_<entity>_qos(), get the QoS settings that were specified on the last successful call to set_default_<entity>_qos() or set_default_<entity>_qos_with_profile(), or if the call was never made, the default values listed in DDS_<entity>Qos. They may potentially allocate memory depending on the sequences contained in some QoS policies.

Note: It is not safe to set default QoS values for an entity while another thread may be simultaneously getting or setting them, or using the QOS_DEFAULT constant to create the entity.

8.3.7Looking up Topic Descriptions

The lookup_topicdescription() operation allows you to access a locally created

DDSTopicDescription based on the Topic’s name.

DDSTopicDescription* lookup_topicdescription

(const char *topic_name)

DDSTopicDescription is the base class for Topics, MultiTopics1 and ContentFilteredTopics. You can narrow the DDSTopicDescription returned from lookup_topicdescription() to a Topic or

ContentFilteredTopic as appropriate.

Unlike find_topic() (see Section 8.3.8), which logically returns a new Topic that must be independently deleted, this operation returns a reference to the original local object.

If no TopicDescription has been created yet with the given Topic name, this method will return a NULL value.

The DomainParticipant does not have to be enabled when you call lookup_topicdescription().

Note: It is not safe to create or delete a topic while another thread is calling lookup_topicdescription() for that same topic.

8.3.8Finding a Topic

The find_topic() operation finds an existing (or ready to exist) Topic, based on its name. This call can be used to block for a specified duration to wait for the Topic to be created.

DDSTopic* DDSDomainParticipant::find_topic (const char * topic_name, const DDS_Duration_t & timeout)

If the requested Topic already exists, it is returned. Otherwise, find_topic() waits until either another thread creates it, or returns when the specified timeout occurs.

find_topic() is useful when multiple threads are concurrently creating and looking up topics. In that case, one thread can call find_topic() and, if another thread has not yet created the topic being looked up, it can wait for some period of time for it to do so. In almost all other cases, it is more straightforward to call lookup_topicdescription() (see Section 8.3.7).

The DomainParticipant must be enabled when you call find_topic().

Note: Each DDSTopic obtained by find_topic() must also be deleted by calling the DomainParticipant’s delete_topic() operation (see Section 5.1.2).

1. Multitopics are not supported.

8-20

8.3.9Getting the Implicit Publisher or Subscriber

The get_implicit_publisher() operation allows you to access the DomainParticipant’s implicit Publisher. If one does not already exist, this operation creates an implicit Publisher.

There is a similar operation for implicit Subscribers:

DDSPublisher * get_implicit_publisher ()

DDSSubscriber * get_implicit_subscriber()

There can only be one implicit Publisher and one implicit Subscriber per DomainParticipant. They are created with default QoS values (DDS_PUBLISHER_QOS_DEFAULT) and no Listener. For more information, see Creating Publishers Explicitly vs. Implicitly (Section 6.2.1). You can use an implicit Publisher or implicit Subscriber just like an explicitly created one.

An implicit Publisher/Subscriber is deleted automatically when delete_contained_entities() is called. It can also be deleted by calling delete_publisher/subscriber() with the implicit

Publisher/Subscriber as a parameter.

When a DomainParticipant is deleted, if there are no attached DataReaders that belong to the implicit Subscriber or no attached DataWriters that belong to the implicit Publisher, any implicit Publisher/Subscriber will be deleted by the middleware implicitly.

Note: It is not safe to create an implicit Publisher/Subscriber while another thread may be simultaneously calling set_default_[publisher/subscriber]_qos().

The following example code shows how to get the implicit Publisher/Subscriber. (For simplicity, error handling is not shown.)

using namespace DDS;

...

Publisher * publisher = NULL; Subscriber * subscriber = NULL; PublisherQos publisher_qos; SubscriberQos subscriber_qos;

...

publisher = participant->get_implicit_publisher();

/* Change implicit publisher QoS */ publisher->get_qos(publisher_qos);

publisher_qos.partition.name.maximum(3); publisher_qos.partition.name.length(3); publisher_qos.partition.name[0] = DDS_String_dup("partition_A"); publisher_qos.partition.name[1] = DDS_String_dup("partition_B"); publisher_qos.partition.name[2] = DDS_String_dup("partition_C");

publisher->set_qos(publisher_qos);

/* Get implicit subscriber */

subscriber = participant->get_implicit_subscriber();

/* Change implicit subscriber QoS */ subscriber_qos.partition.name.maximum(3); subscriber _qos.partition.name.length(3);

subscriber _qos.partition.name[0] = DDS_String_dup("partition_A"); subscriber _qos.partition.name[1] = DDS_String_dup("partition_B"); subscriber _qos.partition.name[2] = DDS_String_dup("partition_C");

subscriber->set_qos(subscriber_qos);

8-21

8.3.10Asserting Liveliness

The assert_liveliness() operation manually asserts the liveliness of all the DataWriters created by this DomainParticipant that has LIVELINESS QosPolicy (Section 6.5.13) kind set to

MANUAL_BY_PARTICIPANT. When assert_liveliness() is called, then for those DataWriters who have their LIVELINESS set to MANUAL_BY_PARTICIPANT, Connext will send a packet to all matched DataReaders that indicates that the DataWriter is still alive.

However, the LIVELINESS contract of periodically sending liveliness packets to DataReaders is also fulfilled when the write(), assert_liveliness(), unregister_instance() and dispose() operations on a DataWriter itself is called. Those calls will also cause Connext to send packets that indicate the liveliness of the DataWriter. Therefore, it is necessary for the application to call assert_liveliness() on the DomainParticipant only if those operations on a DataWriter are not being invoked within the period specified by the LIVELINESS QosPolicy (Section 6.5.13)

8.3.11Learning about Discovered DomainParticipants

The get_discovered_participants() operation provides you with a list of DomainParticipants that have been discovered in the domain (except any that you have said to ignore via the ignore_participant() operation (see Section 16.4)).

Once you have a list of discovered DomainParticipants, you can get more information about them by calling the get_discovered_participant_data() operation. This operation can only be used on DomainParticipants that are in the same domain and have not been marked as ‘ignored.’ Otherwise, the operation will fail and return DDS_RETCODE_PRECONDITION_NOT_MET. The returned information is of type DDS_ParticipantBuiltinTopicData, described in Table 16.1 on page 16-2.

Note: The get_discovered_participant_data() operation does not retrieve the property information from the builtin-topic data structure. This information is available through the DataReaderListener’s on_data_available() callback (if a reader listener is installed on the ParticipantBuiltinTopicDataDataReader).

8.3.12Learning about Discovered Topics

The get_discovered_topics() operation provides you with a list of Topics that have been discovered in the domain (except any that you have said to ignore via the ignore_topic() operation (see Section 16.4)).

Once you have a list of discovered Topics, you can get more information about them by calling the get_discovered_topic_data() operation. This operation can only be used on Topics that have been created by a DomainParticipant in the same domain as the participant on which this operation is invoked and must not have been "ignored" by means of the DomainParticipant ignore_topic() operation. Otherwise, the operation will fail and return

DDS_RETCODE_PRECONDITION_NOT_MET. The returned information is of type

DDS_TopicBuiltinTopicData, described in Table 16.4 on page 16-6.

8.3.13Other DomainParticipant Operations

8.3.13.1Verifying Entity Containment

If you have a handle to an Entity, and want to see if that Entity was created from your

DomainParticipant (or any of its Publishers or Subscribers), use the contains_entity() operation, which returns a boolean.

An Entity’s instance handle may be obtained from built-in topic data (see Chapter 16: Built-In Topics), various statuses, or from the get_instance_handle() operation (see Section 4.1.3).

8-22

8.3.13.2Getting the Current Time

The get_current_time() operation returns the current time value from the same time-source (clock) that Connext uses to timestamp the data published by DataWriters (source_timestamp of the SampleInfo structure, see Section 7.4.6). The time-sources used by Connext do not have to be synchronized nor are they synchronized by Connext.

See also: Clock Selection (Section 8.6).

8.3.13.3Getting All Publishers and Subscribers

The get_publishers() and get_subscribers() operations will provide you with a list of the

DomainParticipant’s Publishers and Subscribers, respectively.

8.4DomainParticipantFactory QosPolicies

This section describes QosPolicies that are strictly for the DomainParticipantFactory (not the DomainParticipant). For a complete list of QosPolicies that apply to DomainParticipantFactory, see Table 8.2 on page 8-5.

LOGGING QosPolicy (DDS Extension) (Section 8.4.1)

PROFILE QosPolicy (DDS Extension) (Section 8.4.2)

SYSTEM_RESOURCE_LIMITS QoS Policy (DDS Extension) (Section 8.4.3)

8.4.1LOGGING QosPolicy (DDS Extension)

This QosPolicy configures the properties associated with the Connext logging facility.

This QosPolicy includes the members in Table 8.5. For defaults and valid ranges, please refer to the API Reference HTML documentation.

See also: Controlling Messages from Connext (Section 21.2) and Configuring Logging via XML (Section 21.2.2).

Table 8.5 DDS_LoggingQosPolicy

 

Type

Field Name

Description

 

 

 

 

 

 

 

 

 

NDDS_Config_LogVerbosity

verbosity

Specifies the verbosity at which Connext diagnostic

 

information will be logged.

 

 

 

 

 

 

 

 

NDDS_Config_LogCategory

category

Specifies the category for which logging needs to be

 

enabled.

 

 

 

 

 

 

 

 

NDDS_Config_LogPrintFormat

print_format

Specifies the format to be used to output the Connext

 

diagnostic information.

 

 

 

 

 

 

 

 

char *

output_file

Specifies the file to which the logged output is

 

redirected.

 

 

 

 

 

 

 

8.4.1.1

Example

 

 

DSDomainParticipantFactory *factory = DDSDomainParticipantFactory::get_instance();

DDS_DomainParticipantFactoryQos factoryQos; DDS_ReturnCode_t retcode = factory->get_qos(factoryQos); if (retcode != DDS_RETCODE_OK) {

// error

}

factoryQos.logging.output_file = DDS_String_dup(“myOutput.txt”);

8-23

factoryQos.logging.verbosity = NDDS_CONFIG_LOG_VERBOSITY_STATUS_LOCAL; factory->set_qos(factoryQos);

8.4.1.2Properties

This QosPolicy can be changed at any time.

Since it is only configuring logging, there are no compatibility restrictions for how it is set on the publishing and subscribing sides.

8.4.1.3Related QosPolicies

None

8.4.1.4Applicable Entities

DomainParticipantFactory (Section 8.2)

8.4.1.5System Resource Considerations

Because the output_file will be freed by Connext, you should use DDS_String_dup() to allocate the string.when providing an output_file.

8.4.2PROFILE QosPolicy (DDS Extension)

This QosPolicy determines the way that XML documents containing QoS profiles are loaded.

All QoS values for Entities can be configured with QoS profiles defined in XML documents. XML documents can be passed to Connext in string form, or more likely, through files found on a file system. This QoS configures how a DomainParticipantFactory loads the QoS profiles defined in XML. QoS profiles may be stored in this QoS as XML documents as a string. The location of XML files defining QoS profiles may be configured via this QoS. There are also default locations where the DomainParticipantFactory will look for files to load QoS profiles. You may disable any or all of these default locations using the Profile QoS. For more information about QoS profiles and libraries, please see Chapter 17: Configuring QoS with XML.

This QosPolicy includes the members in Table 8.6 on page 8-24. For the defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 8.6 DDS_ProfileQosPolicy

Type

Field Name

 

 

 

Description

 

 

 

 

 

 

 

 

Sequence of strings (empty by default) containing a XML

 

 

document to load.

 

 

 

 

 

 

 

string_profile

The concatenation of the strings in this sequence must be a

DDS_StringSeq

 

valid

XML document according to

the XML QoS profile

 

schema.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

A sequence of URL groups (empty by default) containing a set

 

url_profile

of XML documents to load.

 

 

 

 

 

 

 

See URL Groups (Section 17.11).

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

When

TRUE,

the

QoS

profiles

contained in

the

file

 

ignore_user_profile

USER_QOS_PROFILES.xml in the current working directory

 

 

will be ignored.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

DDS_Boolean

ignore_environment_

When

TRUE,

the

value

of

the

environment

variable

profile

NDDS_QOS_PROFILES will be ignored.

 

 

 

 

 

 

 

 

 

 

 

 

ignore_resource_

When

TRUE,

the QoS profiles

in the file $NDDSHOME/

 

resource/qos_profiles_5.0.xa/xml/QOS_PROFILES.xml

will

 

profile

 

be ignored.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

8-24

a.Replace the x in 5.0.x with the version number for the current release.

8.4.2.1Example

DDSDomainParticipantFactory *factory =

DDSDomainParticipantFactory::get_instance();

DDS_DomainParticipantFactoryQos factoryQos;

DDS_ReturnCode_t retcode = factory->get_qos(factoryQos); if (retcode != DDS_RETCODE_OK) {

// error

}

const char *url_profiles[2] = { "file://usr/local/default_dds.xml",

"file://usr/local/alternative_default_dds.xml" };

factoryQos.profile.url_profile.from_array(url_profiles, 2); factoryQos.profile.ignore_resource_profile = DDS_BOOLEAN_TRUE; factory->set_qos(factoryQos);

8.4.2.2Properties

This QosPolicy can be changed at any time.

Since it is only for the DomainParticipantFactory, there are no compatibility restrictions for how it is set on the publishing and subscribing sides.

8.4.2.3Related QosPolicies

None

8.4.2.4Applicable Entities

DomainParticipantFactory (Section 8.2)

8.4.2.5System Resource Considerations

Once the QoS profiles are loaded, the DomainParticipantFactory will keep one copy of each QoS in the QoS profiles in memory.

You can free the memory associated with the XML QoS profiles by calling the DomainParticipantFactory’s unload_profiles() operation.

8.4.3SYSTEM_RESOURCE_LIMITS QoS Policy (DDS Extension)

The SYSTEM_RESOURCE_LIMITS QosPolicy configures DomainParticipant-independent resources used by Connext. Its main use is to change the maximum number of DomainParticipants that can be created within a single process (address space).

It contains the single member as shown in Table 8.7. For the default and valid range, please refer to the API Reference HTML documentation.

Table 8.7 DDS_SystemResourceLimitsQosPolicy

Type

Field Name

Description

 

 

 

DDS_Long

max_objects_per_thread

Sizes the thread storage that is allocated on a per-thread basis

when the thread calls Connext APIs.

 

 

 

 

 

8-25

The only parameter that you can set, max_objects_per_thread, controls the size of thread- specific storage that is allocated by Connext for every thread that invokes a Connext API. This storage is used to cache objects that have to be created on a per-thread basis when a thread traverses different portions of Connext internal code.

Thus instead of dynamically creating and destroying the objects as a thread enters and leaves different parts of the code, Connext caches the objects by storing them in thread-specific storage. We assume that a thread will repeatedly call Connext APIs so that the objects cached will be needed again and again.

The number of objects that will be stored in the cache depends the number of APIs (sections of Connext code) that a thread invokes. It also depends on the number of different DomainParticipants with which the thread interacts. For a single DomainParticipant, the maximum number of objects that could be stored is a constant–independent of the number of Entities created in or by the participant. A safe number to use is 200 objects per

DomainParticipant.

A user thread that only interacts with a single DomainParticipant or the Entities thereof, would never have more than 200 objects stored in its cache. However, if the same thread invokes Connext APIs on other Entities of other DomainParticipants, the maximum number of objects that may be stored will increase with the number of participants involved.

The default setting of this resource should work for most user applications. However, if your application uses more than 4 DomainParticipants, you may need to increase the value of max_objects_per_thread.

8.4.3.1Example

Say an application uses 10 DomainParticipants. If a single thread was used to create all 10 DomainParticipants, or a single thread is used to call write() on DataWriters belonging to all 10 participants, it is possible to run out of thread-specific storage. Either the creation of the participant or the write() will fail.

In that case, you will need to increase the value of max_objects_per_thread.

8.4.3.2Properties

This QoS policy cannot be modified after the DomainParticipantFactory is used to create the first DomainParticipant in an application.

This QoS can be set differently in different applications.

8.4.3.3Related QoS Policies

There are no interactions with other QosPolicies.

8.4.3.4Applicable Entities

DomainParticipantFactory (Section 8.2)

8.4.3.5System Resource Considerations

Increasing the value of max_objects_per_thread will increase the amount of memory allocated by Connext for every thread that access Connext code. This includes internal Connext threads as well as user threads. Each object uses about 32 bytes of memory.

8-26

8.5DomainParticipant QosPolicies

This section describes the QosPolicies that are strictly for DomainParticipants (and no other types of Entities). For a complete list of QosPolicies that apply to DomainParticipant, see Table 8.4 on page 8-15.

DATABASE QosPolicy (DDS Extension) (Section 8.5.1)

DISCOVERY QosPolicy (DDS Extension) (Section 8.5.2)

DISCOVERY_CONFIG QosPolicy (DDS Extension) (Section 8.5.3)

DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4)

EVENT QosPolicy (DDS Extension) (Section 8.5.5)

RECEIVER_POOL QosPolicy (DDS Extension) (Section 8.5.6)

TRANSPORT_BUILTIN QosPolicy (DDS Extension) (Section 8.5.7)

TRANSPORT_MULTICAST_MAPPING QosPolicy (DDS Extension) (Section 8.5.8)

WIRE_PROTOCOL QosPolicy (DDS Extension) (Section 8.5.9)

8.5.1DATABASE QosPolicy (DDS Extension)

The Database QosPolicy configures how Connext manages its internal database, including how often it cleans up, the priority of the database thread, and limits on resources that may be allocated by the database. RTI uses an internal in-memory database to store information about entities created locally as well as remote entities found during the discovery process. This database uses a background thread to garbage-collect records related to deleted entities. When the DomainParticipant that maintains this database is deleted, it shuts down this thread..

It includes the members in Table 8.8. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 8.8 DDS_DatabaseQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

thread.mask

Thread settings for the database thread used by Connext to

DDS_

periodically remove deleted records from the database. The

thread.priority

values used for these settings are OS-dependent.

ThreadSettings_t

Note: thread.cpu_list and thread.cpu_rotation are not relevant in

 

thread.stack_size

 

 

this QoS policy.

 

 

 

DDS_Duration_t

shutdown_timeout

The maximum time that the DomainParticipant will wait for the

database thread to terminate when the participant is destroyed.

 

 

 

DDS_Duration_t

cleanup_period

The period at which the database thread wakes up to removed

deleted records.

 

 

 

 

 

DDS_Duration_t

shutdown_cleanup

The period at which the database thread wakes up to removed

 

_period

deleted records when the DomainParticipant is being destroyed.

 

 

The number of records that is initially created for the database.

DDS_Long

initial_records

These records hold information for both local and remote entities

 

 

that are dynamically created or discovered.

 

 

 

8-27

Table 8.8 DDS_DatabaseQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

This is a performance tuning parameter that optimizes the time it

 

 

takes to search the database for a record. A ‘Skip List’ is an

 

 

algorithm for maintaining a list that is faster to search than a

 

 

Binary Tree.

DDS_Long

max_skiplist_level

This value should be set to log2(N), where N is the maximum

number of elements that will be stored in a single list. The list that

 

 

stores the records for remote DataReaders or the one for remote

 

 

DataWriters tend to have the most entries. So, the number of

 

 

DataWriters or DataReaders in a system across all

 

 

DomainParticipants in a single domain, which ever is greater, can

 

 

be used to set this parameter.

 

 

 

 

 

This parameter sets the maximum number of entries in the weak

 

 

reference table. Weak references are used as a technique for

 

 

ensuring that unreferenced objects are deleted.

 

 

The actual number of weak references is permitted to grow from

 

 

the value set by initial_weak_references to this maximum.

DDS_Long

max_weak_

To prevent Connext from allocating memory for weak references

after initialization, you should set the initial and maximum weak

references

 

references to the same value.

 

 

 

 

However, it is difficult to calculate how many weak references an

 

 

application will use. To allow Connext to grow the weak reference

 

 

table as needed, and thus dynamically allocate memory, you

 

 

should set the value of this field to DDS_LENGTH_UNLIMITED,

 

 

the default setting.

 

 

 

 

 

The initial number of entries in the weak reference table.

 

 

See max_weak_references.

DDS_Long

initial_weak_

Connext may decide to use a larger initial value if

references

initial_weak_references is set too small. If you access this

 

 

 

parameter after a DomainParticipant has been created, you will see

 

 

the actual value used.

 

 

 

You may be interested in modifying the shutdown_timeout and shutdown_cleanup_period parameters to decrease the time it takes to delete a DomainParticipant when your application is shutting down.

The DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4) controls the memory allocation for elements stored in the database.

Real-time programmers will probably want to adjust the priorities of all of the threads created by Connext relative to each other as well as relative to non-Connext threads in their applications. Chapter 19: Connext Threading Model, EVENT QosPolicy (DDS Extension) (Section 8.5.5), and RECEIVER_POOL QosPolicy (DDS Extension) (Section 8.5.6) discuss the other threads that are created by Connext.

A record in the database can be deleted only when no threads are using it. Connext uses a thread that periodically checks the database if records that have been marked for deletion can be removed. This period is set by cleanup_period. When a DomainParticipant is being destroyed, the thread will wake up faster at the shutdown_cleanup_period as other threads delete and release records in preparation for shutting down.

On Windows and VxWorks systems, the thread that is destroying the DomainParticipant may block up to shutdown_timeout seconds while waiting for the database thread to finish removing all records and terminating. On other operating systems, the thread destroying the DomainParticipant will block as long as required for the database thread to terminate.

The default values for those and the rest of the parameters in this QosPolicy should be sufficient for most applications.

8-28

8.5.1.1Example

The priority of the database thread should be set to the lowest priority among all threads in a real-time system. Although, the database thread should not be permitted to starve, the work that it performs is non-time-critical.

8.5.1.2Properties

This QosPolicy cannot be modified after the DomainParticipant is created. It can be set differently on the publishing and subscribing sides.

8.5.1.3Related QosPolicies

DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4)

EVENT QosPolicy (DDS Extension) (Section 8.5.5)

RECEIVER_POOL QosPolicy (DDS Extension) (Section 8.5.6)

8.5.1.4Applicable Entities

DomainParticipants (Section 8.3)

8.5.1.5System Resource Considerations

Setting the thread parameters correctly on a real-time operating system is usually critical to the proper overall functionality of the applications on that system. Larger values for the thread.stack_size parameter will use up more memory.

Smaller values for the cleanup_period and shutdown_cleanup_period will cause the database thread to wake up more frequently using more CPU.

Connext is permitted to use up more memory for larger values of max_skiplist_level and max_weak_references. Whether or not more memory is actually used depends on actual operating conditions.

8.5.2DISCOVERY QosPolicy (DDS Extension)

The DISCOVERY QoS configures how DomainParticipants discover each other on the network. It identifies where on the network this application can potentially discover other applications with which to communicate. The middleware will periodically send network packets to these locations, announcing itself to any remote applications that may be present, and will listen for announcements from those applications. The discovery process is described in detail in Chapter 14: Discovery.

This QosPolicy includes the members in Table 8.9. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 8.9 DDS_DiscoveryQosPolicy

Type

Field Name

 

 

Description

 

 

 

 

DDS_StringSeq

enabled_transports

Transports available for use by the discovery process.

See Section 8.5.2.1.

 

 

 

 

 

 

 

 

 

 

 

Unicast locators (address/indices) of potential

DDS_StringSeq

initial_peers

participants with which this DomainParticipant will

attempt

to

establish

communications.

See

 

 

 

 

Section 8.5.2.2.

 

 

 

 

 

 

 

 

 

 

8-29

Table 8.9 DDS_DiscoveryQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

List of multicast addresses on which Discovery-related

DDS_StringSeq

multicast_receive_addresses

messages can be received by the DomainParticipant. See

 

 

Section 8.5.2.4.

 

 

 

DDS_Long

metatraffic_transport_priority

Transport priority to be used for sending Discovery

messages. See Section 8.5.2.5.

 

 

 

 

 

DDS_Boolean

accept_unknown_peers

Whether to accept a participant discovered via unicast

that is not in the initial_peers list. See Section 8.5.2.6.

 

 

 

 

 

8.5.2.1Transports Used for Discovery

The enabled_transports field allows you to specify the set of installed and enabled transports that can be used to discover other DomainParticipants. This field is a sequence of strings where each string specifies an alias of a registered (and thus installed and enabled) transport. Please see the API Reference HTML documentation (select Modules, Connext API Reference, Pluggable Transports) for more information.

8.5.2.2Setting the ‘Initial Peers’ List

When a DomainParticipant is created, it needs to find other participants in the same domain— this is known as the ‘discovery process’ which is discussed in Chapter 14: Discovery. One way to do so is to use this QosPolicy to specify a list of potential participants. This is the role of the parameter initial_peers. The strings containing peer descriptors are stored in the initial_peers string sequence. The format of a string discussed in Peer Descriptor Format (Section 14.2.1).

The peers stored in initial_peers are merely potential peers—there is no requirement that the peer DomainParticipants are actually up and running or even will eventually exist. The Connext discovery process will try to contact all potential peer participants in the list periodically using unicast transports (as configured by the DISCOVERY_CONFIG QosPolicy (DDS Extension) (Section 8.5.3)).

The initial_peers parameter can be modified in source code or it can be initialized from an environment variable, NDDS_DISCOVERY_PEERS or from a text file, see Configuring the Peers List Used in Discovery (Section 14.2).

Note: IPv4 multicast addresses must have a prefix

When using the UDPv6 transport: if there are any IPv4 multicast addresses in the peers list, make sure they have "udpv4://" in front of them.

For example:

setenv NDDS_DISCOVERY_PEERS "udpv4://localhost,udpv4://239.255.0.1,shmem://"

or, to add IPv6 loopback and an IPv6 multicast address:

setenv NDDS_DISCOVERY_PEERS "udpv4://localhost,udpv4://239.255.0.1, shmem://,udpv6://::1,udpv6://ff05::239.255.0.1"

8.5.2.3Adding and Removing Peers List Entries

The DomainParticipant’s add_peer() operation adds a peer description to the internal peer list that was initialized by the initial_peer field of the DISCOVERY QosPolicy.

DDS_ReturnCode_t DDSDomainParticipant::add_peer (const char* peer_desc)

The peer_desc string must be formatted as specified in Peer Descriptor Format (Section 14.2.1).

You can call this operation any time after the DomainParticipant has been enabled. An attempt will be made to contact the new peer immediately.

8-30

Adding peers with this operation has no effect on the initial_peers list. After a DomainParticipant has been created, the contents of the initial_peers field merely shows what the internal peer list was initialized to be. Therefore, initial_peers may not reflect the actual potential peer list used by a DomainParticipant. Furthermore, if you call get_qos(), the returned list of peers will not include the added peer—get_qos() will only show you what is set in the initial_peers list.

A peer added with add_peer() is not considered to be “unknown.” (That is, you may have accept_unknown_peers (Section 8.5.2.6) set to FALSE and still use add_peer().)

You can remove an entry from the list with remove_peer().

You can ignore data from a participant by using the ignore_participant() operation described in

Section 16.4.

8.5.2.4Configuring Multicast Receive Addresses

The multicast_receive_addresses field in the DISCOVERY QosPolicy is a sequence of strings that specifies a set of multicast group addresses on which the DomainParticipant will listen for discovery meta-traffic. Each string must have a valid multicast address in either IPv4 dot notation or IPv6 presentation format. Please look at publicly available documentation of the IPv4 and IPv6 standards for the definition and valid address ranges for multicast.

The multicast_receive_addresses field can be initialized from multicast addresses that appear in the NDDS_DISCOVERY_PEERS environment variable or text file, see Configuring the Peers List Used in Discovery (Section 14.2). A multicast address found in the environment variable or text file will be added both to the initial_peers and multicast_receive_addresses fields. Note that the addresses in initial_peers are ones in which the DomainParticipant will send discovery meta-traffic, and the ones in multicast_receive_addresses are used for receiving discovery meta- traffic.

If NDDS_DISCOVERY_PEERS does not contain a multicast address, then multicast_receive_addresses is cleared and the RTI discovery process will not listen for discovery messages via multicast.

If NDDS_DISCOVERY_PEERS contains one or more multicast addresses, the addresses are stored in multicast_receive_addresses, starting at element 0. They will be stored in the order in which they appear in NDDS_DISCOVERY_PEERS.

Note: Currently, Connext will only listen for discovery traffic on the first multicast address (element 0) in multicast_receive_addresses.

If you want to send discovery meta-traffic on a different set of multicast addresses than you want to receive discovery meta-traffic, set initial_peers and multicast_receive_addresses via the QosPolicy API.

8.5.2.5Meta-Traffic Transport Priority

The metatraffic_transport_priority field is used to specify the transport priority to be used for sending all discovery meta-traffic. See the TRANSPORT_PRIORITY QosPolicy (Section 6.5.21) for details on how transport priorities may be used.

Currently, the builtin transports provided by Connext will ignore the value set in this field.

8.5.2.6Controlling Acceptance of Unknown Peers

The accept_unknown_peers field controls whether or not a DomainParticipant is allowed to communicate with other DomainParticipants found via unicast transport that are not in its peers list (which is the combination of the initial_peers list and any peers added with the add_peer() operation described in Section 8.5.2.3).

Suppose Participant A is included in Participant B’s initial peers list, but Participant B is not in Participant A’s list. When Participant B contacts Participant A by sending it a unicast discovery packet, then Participant A has a choice:

8-31

If accept_unknown_peers is DDS_BOOLEAN_TRUE, then Participant A will reply to Participant B, and communications will be established.

If accept_unknown_peers is DDS_BOOLEAN_FALSE, then Participant A will ignore Participant B, and A and B will never talk.

Note that Participants do not exchange peer lists. So if Participant A knows about Participant B, and Participant B knows about Participant C, Participant A will not discover Participant C.

Note: If accept_unknown_peers is false and shared memory is disabled, applications on the same node will not communicate if only ‘localhost’ is specified in the peer list. If shared memory is disabled or ‘shmem://’ is not specified in the peer list, if you want to communicate with other applications on the same node through the loopback interface, you must put the actual node address or hostname in NDDS_DISCOVERY_PEERS.

8.5.2.7Example

You will always use this policy to set the participant_id when you want to run more than one DomainParticipant in the same domain on the same host.

The easiest way to set the initial peers list is to use the NDDS_DISCOVERY_PEERS environment variable. However, should you want asymmetric multicast addresses for sending or receiving meta-traffic, you will need to use this QosPolicy directly.

A reason to use asymmetric multicast addresses is to take advantage of the efficiency provided by using multicast, while at the same time preventing all participants from discovering each other. For example, suppose you have a system in which you have a single server node and a hundred client nodes. The client nodes do not publish or subscribe to each other’s data and thus never need to know about each others existence.

If we did not use multicast, we would have to populate the server application’s peer list with 100 peer descriptors for each of the client nodes. Each client application would only need to have the server application in its peer list. The maintenance of the list is unwieldy, especially if nodes are constantly reconfigured and addresses changed. In addition, the server will send out discovery packets on a per client basis since the peer list essentially holds 100 unicast addresses.

Instead, if we used a single multicast address in the NDDS_DISCOVERY_PEERS environment variable, the server and all of the clients would discover each other. Certainly, the list is easier to maintain, but the total amount of traffic has actually increased since the clients are now exchanging packets with each other uselessly.

To keep the list maintainable, as well as to minimize discovery traffic, we can have the server send out packets on a multicast address by modifying its initial_peer field. The clients would have their multicast_receive_addresses field set to the same address used by the server. The initial_peers of the clients would only need the single unicast peer descriptor of the server as before.

Now, the server can send a single packet that will be received by all of the clients, but the clients will not discover each other because they never send out a multicast packet themselves.

8.5.2.8Properties

This QosPolicy cannot be modified after the DomainParticipant is created. It can be set differently on the publishing and subscribing sides.

8.5.2.9Related QosPolicies

DISCOVERY_CONFIG QosPolicy (DDS Extension) (Section 8.5.3)

TRANSPORT_BUILTIN QosPolicy (DDS Extension) (Section 8.5.7)

8-32

8.5.2.10Applicable Entities

DomainParticipants (Section 8.3)

8.5.2.11System Resource Considerations

For every entry in the initial_peers list, Connext will periodically send a discovery packet to see if that participant exists. If the list has many potential participants that are never started, then CPU and network bandwidth may be wasted in sending out packets that will never be received.

8.5.3DISCOVERY_CONFIG QosPolicy (DDS Extension)

The DISCOVERY_CONFIG QosPolicy is used to tune the discovery process. It controls how often to send discovery packets, how to determine when participants are alive or dead, and resources used by the discovery mechanism.

The amount of network traffic required by the discovery process can vary widely based on how your application has chosen to configure the middleware's network addressing (e.g. unicast vs. multicast, multicast TTL, etc.), the size of the system, whether all applications are started at the same time or whether start times are staggered, and other factors. Your application can use this policy to make trade-offs between discovery completion time and network bandwidth utilization. In addition, you can introduce random back-off periods into the discovery process to decrease the probability of network contention when many applications start simultaneously.

This QosPolicy includes the members in Table 8.10. Many of these members are described in

Chapter 14: Discovery. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 8.10 DDS_DiscoveryConfigQosPolicy

Type

Field Name

 

Description

 

 

 

 

 

 

 

 

The time period after which other

DDS_Duration_t

participant_liveliness_

DomainParticipants

can

consider

this

one

lease_duration

dead if they do not receive a liveliness packet

 

 

 

from this DomainParticipant.

 

 

 

 

 

 

 

 

 

 

 

 

 

participant_liveliness_

The

period

of

time

at

which

this

DDS_Duration_t

DomainParticipant

will

send

out

packets

assert_period

 

asserting that it is alive.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Controls the DomainParticipant's behavior for

 

remote_participant_

purging records of remote participants (and

DDS_RemoteParticipantPurgeKind

their

contained

entities) with

which

purge_kind

 

discovery communication has been lost. See

 

 

 

 

Section 8.5.3.2.

 

 

 

 

 

 

 

 

 

 

 

The maximum amount of time between

DDS_Duration_t

max_liveliness_loss_

when a remote entity stops maintaining its

detection_period

liveliness and when the matched local entity

 

 

 

realizes that fact.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Sets

how

many

initial

liveliness

DDS_Long

initial_participant_

announcements

the DomainParticipant

will

announcements

send when it is first enabled, or after

 

 

 

discovering a new remote participant.

 

 

 

 

 

 

 

 

 

 

 

8-33

Table 8.10 DDS_DiscoveryConfigQosPolicy

Type

Field Name

 

 

Description

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

DDS_Duration_t

min_initial_participant_

Sets the

minimum

and

maximum

times

announcement_period

between liveliness announcements.

 

 

 

 

 

When a participant is first enabled, or after

 

 

 

 

discovering a new remote participant,

 

 

Connext

 

 

 

 

 

 

sends

 

 

initial_paricipant_annoucements number of

 

max_initial_participant_

discovery messages. These messages are sent

DDS_Duration_t

with a sleep period between them that is a

announcement_period

 

random

 

duration

 

between

 

 

 

 

 

 

min_initial_participant_announcement_peri

 

 

od

 

 

 

 

 

 

and

 

 

max_initial_participant_announcement_peri

 

 

od.

 

 

 

 

 

 

 

 

 

 

 

 

Configures the resource for the built-in

DDS_BuiltinTopicReaderResourceLimits_t

participant_reader_

DataReaders used to access discovery

(see Table 8.11 on page 8-36)

resource_limits

information;

see

Section 8.5.3.1

and

 

 

Chapter 16: Built-In Topics.

 

 

 

 

 

 

 

 

DDS_RtpsReliableReaderProtocol_t

publication_reader

Configures

the

RTPS

reliable protocol

(see Table 7.20 on page 7-52)

parameters for a built-in publication reader.

 

 

 

 

 

 

Configures the resource for the built-in

DDS_BuiltinTopicReaderResourceLimits_t

publication_reader_

DataReaders used to access discovery

(see Table 8.11 on page 8-36)

resource_limits

information;

see

Section 8.5.3.1

and

 

 

Chapter 16: Built-In Topics.

 

 

 

 

 

 

 

Configures the RTPS reliable protocol

 

 

parameters for a built-in subscription reader.

DDS_RtpsReliableReaderProtocol_t

subscription_reader

Built-in

subscription

readers

receive

(see Table 7.20 on page 7-52)

discovery

 

information

reliably

from

 

 

 

 

DomainParticipants

that were

dynamically

 

 

discovered (see Chapter 14: Discovery).

 

 

 

 

 

Configures the resource for the built-in

DDS_BuiltinTopicReaderResourceLimits_t

subscription_reader_

DataReaders used to access discovery

(see Table 8.11 on page 8-36)

resource_limits

information;

see

Section 8.5.3.1

and

 

 

Chapter 16: Built-In Topics.

 

 

 

 

 

 

 

Configures the RTPS reliable protocol

 

 

parameters for the writer side of a reliable

DDS_RtpsReliableWriterProtocol_t

 

connection.

 

 

 

 

 

 

publication_writer

Built-in DataWriters send reliable discovery

(see Table 6.36 on page 6-81)

 

information to DomainParticipants that were

 

 

 

 

dynamically

discovered

(see

Chapter 14:

 

 

Discovery).

 

 

 

 

 

 

 

 

 

 

 

Configures writer data-lifecycle settings for a

DDS_WriterDataLifecycleQosPolicy

publication_writer_data_

built-in

 

publication

 

writer.

(DDS_WriterDataLifecycleQosPolicy::

 

(see Table 6.68 on page 6-130)

lifecycle

autodispose_unregistered_instances

will

 

 

 

 

always be TRUE.)

 

 

 

 

 

 

 

 

 

 

Configures the RTPS reliable protocol

 

 

parameters for the writer side of a reliable

DDS_RtpsReliableWriterProtocol_t

 

connection.

 

 

 

 

 

 

subscription_writer

Built-in DataWriters send reliable discovery

(see Table 6.36 on page 6-81)

 

information to DomainParticipants that were

 

 

 

 

dynamically

discovered

(see

Chapter 14:

 

 

Discovery).

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

8-34

Table 8.10 DDS_DiscoveryConfigQosPolicy

Type

Field Name

 

Description

 

 

 

 

 

 

 

 

 

 

Configures writer data-lifecycle settings for a

DDS_WriterDataLifecycleQosPolicy

subscription_writer_data

built-in

subscription

writer.

(DDS_WriterDataLifecycleQosPolicy::autodi

(see Table 6.68 on page 6-130)

_lifecycle

spose_unregistered_instances will always

 

 

 

 

be TRUE.)

 

 

 

 

 

 

 

 

 

The kind mask for selecting built-in

 

 

discovery plugins:

 

 

 

 

 

Simple Discovery Protocol:

 

 

 

 

DDS_DISCOVERYCONFIG_BUILTIN_S

DDS_DiscoveryConfigBuiltinPluginKind

builtin_discovery_

DP

 

 

 

 

Mask

plugins

Enterprise Discovery Service:

 

 

 

 

DDS_DISCOVERYCONFIG_

 

 

 

 

BUILTIN_EDS

 

 

 

 

 

(Requires a separate component, RTI

 

 

Enterprise Discovery Service.)

 

 

 

 

 

DDS_RtpsReliableReaderProtocol_t

participant_message_

RTPS protocol-related configuration settings

(see Table 7.20 on page 7-52)

reader

for a built-in participant message reader.

 

 

 

 

DDS_RtpsReliableWriterProtocol_t

participant_message_

RTPS protocol-related configuration settings

(see Table 6.36 on page 6-81)

writer

for a built-in participant message writer.

 

 

 

 

DDS_PublishModeQosPolicy

publication_writer_

Determines whether the Discovery built-in

publication

DataWriter

publishes

data

(see Table 6.57 on page 6-115)

publish_mode

synchronously or asynchronously and how.

 

 

 

 

 

DDS_PublishModeQosPolicy

subscription_writer_

Determines whether the Discovery built-in

subscription

DataWriter

publishes

data

(see Table 6.57 on page 6-115)

publish_mode

synchronously or asynchronously and how.

 

 

 

 

 

 

 

 

DDS_AsynchronousPublisherQosPolicy

 

Asynchronous publishing

settings

for

the

asynchronous_publisher

Discovery Publisher and all entities that are

(see Table 6.17 on page 6-54)

 

created by it.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

A DomainParticipant needs to send a message periodically to other DomainParticipants to let the other participants know that it is still alive. These liveliness messages are sent to all peers in the peer list that was initialized by the initial_peers parameter of the DISCOVERY QosPolicy (DDS Extension) (Section 8.5.2). Peer participants on the peer list may or may not be alive themselves. The peer DomainParticipants that already know about this DomainParticipant will use the participant_liveliness_lease_duration provided by this participant to declare the participant dead, if they have not received a liveliness message for the specified time.

The participant_liveliness_assert_period is the periodic rate at which this DomainParticipant will be sending liveliness messages. Since these liveliness messages are not sent reliably and can get dropped by the transport, it is important to set:

participant_liveliness_assert_period < participant_liveliness_lease_duration/N

where N is the number of liveliness messages that other DomainParticipants must miss before they decide that this DomainParticipant is dead.

DomainParticipants that receive a liveliness message from a participant that they did not know about previously will have “discovered” the participant. When one DomainParticipant discovers another, the discoverer will immediately send its own liveliness packets back. initial_participant_announcements controls how many of these initial liveliness messages are sent, and max_initial_participant_announcement_period controls the time period in between each message.

After the initial set of liveliness messages are sent, the DomainParticipant will return to sending liveliness packets to all peers in its peer list at the rate governed by participant_liveliness_assert_period.

8-35

For more information on the discovery process, see Chapter 14: Discovery.

8.5.3.1Resource Limits for Builtin-Topic DataReaders

The DDS_BuiltinTopicReaderResourceLimits_t structure is shown in Table 8.11. This structure contains several fields that are used to configure the resource limits of the builtin-topic DataReaders used to receive discovery meta-traffic from other DomainParticipants.

Table 8.11 DDS_BuiltinTopicReaderResourceLimits_t

Type

Field Name

Description

 

 

 

 

initial_samples

Initial number of meta-traffic data samples that can be stored by

 

a builtin-topic DataReader.

 

 

 

 

 

 

max_samples

Maximum number of meta-traffic data samples that can be

 

stored by a builtin-topic DataReader.

 

 

 

 

 

 

initial_infos

Initial number of DDS_SampleInfo structures allocated for the

 

builtin-topic DataReader.

 

 

 

 

 

 

 

Maximum number of DDS_SampleInfo structures that can be

 

max_infos

allocated for the built-in topic DataReader.

DDS_Long

 

max_infos must be >= max_samples

 

 

 

 

 

Initial number of times in which memory can be concurrently

 

initial_outstanding_reads

loaned via read/take calls on the builtin-topic DataReader

 

 

without being returned with return_loan().

 

 

 

 

 

Maximum number of times in which memory can be

 

max_outstanding_reads

concurrently loaned via read/take calls on the builtin-topic

 

 

DataReader without being returned with return_loan().

 

 

 

 

max_samples_per_read

Maximum number of samples that can be read/taken on a same

 

built-in topic DataReader.

 

 

 

 

 

 

 

Determines whether the builtin-topic DataReader can receive

DDS_Boolean

disable_fragmentation_support

fragmented samples.

 

 

When fragmentation support is not needed, disabling

 

 

fragmentation support will save some memory resources.

 

 

 

8-36

Table 8.11 DDS_BuiltinTopicReaderResourceLimits_t

Type

Field Name

 

 

 

Description

 

 

 

 

 

 

 

 

The maximum number of samples for which the builtin-topic

 

 

DataReader may store fragments at a given point in time.

 

 

At any given time, a builtin-topic DataReader may store

 

 

fragments for up to max_fragmented_samples samples while

 

 

waiting for the remaining fragments. These samples need not

 

 

have consecutive sequence numbers and may have been sent by

 

 

different builtin-topic DataWriters. Once all fragments of a

 

 

sample have been received, the sample is treated as a regular

 

 

sample and becomes subject to standard QoS settings, such as

 

max_fragmented_samples

ResourceLimitsQosPolicy’s max_samples.

 

Connext will drop fragments if the max_fragmented_samples

 

 

 

 

limit has been reached.

 

 

For best-effort communication, Connext will accept a fragment

 

 

for a new sample, but drop the oldest fragmented sample from

DDS_Long

 

the same remote DataWriter.

 

For reliable communication, Connext will drop fragments for

 

 

 

 

any new samples until all fragments for at least one older

 

 

sample from that writer have been received.

 

 

Only applies if disable_fragmentation_support is FALSE.

 

 

 

 

 

The initial number of samples for which a builtin-topic

 

initial_fragmented_samples

DataReader may store fragments.

 

 

Only applies if disable_fragmentation_support is FALSE.

 

 

 

 

 

The maximum number of samples per remote writer for which a

 

max_fragmented_samples_per

builtin-topic DataReader may store fragments.

 

Logical

limit

so a

single remote writer cannot consume all

 

_remote_writer

available resources.

 

 

 

 

 

 

Only applies if disable_fragmentation_support is FALSE.

 

 

 

 

max_fragments_per_sample

Maximum number of fragments for a single sample.

 

Only applies if disable_fragmentation_support is FALSE.

 

 

 

 

 

 

 

Determines whether or not the builtin-topic DataReader will

 

 

preallocate storage for storing fragmented samples.

 

 

By default, Connext allocates memory up-front for storing

 

 

fragments for up to DataReaderResourceLimitsQosPolicy’s

 

 

initial_fragmented_samples samples. This memory may grow

 

 

up

to

the

DataReaderResourceLimitsQosPolicy’s

 

 

max_fragmented_samples if needed.

 

 

If dynamically_allocate_fragmented_samples is TRUE,

 

 

Connext will not allocate memory up-front; instead, it will

 

 

allocate memory from the heap upon receiving the first

DDS_Boolean

dynamically_allocate_

fragment of a new sample. The amount of memory allocated

 

fragmented_samples

equals the amount of memory needed to store all fragments in

 

 

the sample. Once all fragments of a sample have been received,

 

 

the sample is deserialized and stored in the regular receive

 

 

queue. Then the dynamically allocated memory is freed.

 

 

This QoS setting may be useful for large, but variable-sized data

 

 

types where up-front memory allocation for multiple samples

 

 

based on the maximum possible sample size may be expensive.

 

 

The main disadvantage of not pre-allocating memory is that one

 

 

can no longer guarantee that Connext will have sufficient

 

 

resources at run time.

 

 

Only applies if disable_fragmentation_support is FALSE.

 

 

 

 

 

 

There are builtin-topics for exchanging data about DomainParticipants, for publications (Publisher/DataWriter combination) and for subscriptions (Subscriber/DataReader combination).

8-37

The DataReaders for the publication and subscription builtin-topics are reliable. The DataReader for the participant builtin-topic is best effort.

You can set listeners on these DataReaders that are created automatically when a DomainParticipant is created. With these listeners, your code can be notified when remote

DomainParticipants, Publishers/DataWriters, and Subscriber/DataReaders are discovered. You can always check the receive queues of those DataReaders for the same information about discovered entities at any time. Please see Chapter 16: Built-In Topics for more details.

The initial_samples and max_samples, and related initial_infos and max_infos, fields size the amount of declaration messages can be stored in each builtin-topic DataReader.

8.5.3.2Controlling Purging of Remote Participants

When discovery communication with a remote participant has been lost, the local participant must make a decision about whether to continue attempting to communicate with that participant and its contained entities. The remote_participant_purge_kind is used to select the desired behavior.

This does not pertain to the situation in which a remote participant has been gracefully deleted and notification of that deletion has been successfully received by its peers. In that case, the local participant will immediately stop attempting to communicate with those entities and will remove the associated remote entity records from its internal database.

The remote_participant_purge_kind can be set to the following values:

DDS_LIVELINESS_BASED_REMOTE_PARTICIPANT_PURGE

This value causes Connext to keep the state of a remote participant and its contained entities for as long as the participant maintains its liveliness contract (as specified by its participant_liveliness_lease_duration in the DISCOVERY_CONFIG QosPolicy (DDS Extension) (Section 8.5.3)).

A participant will maintain its own liveliness to any remote participant via inter- participant liveliness traffic (see LIVELINESS QosPolicy (Section 6.5.13)).

The default Simple Discovery Protocol described in Chapter 14: Discovery automatically maintains this liveliness, whereas other discovery mechanisms may or may not.

DDS_NO_REMOTE_PARTICIPANT_PURGE

With this value, Connext will never purge the records of a remote participant with which discovery communication has been lost.

If the remote participant is later rediscovered, the records that remain in the database will be re-used.

If the remote participant is not rediscovered, the records will continue to take up space in the database for as long as the local participant remains in existence.

In most cases, you will not need to change this value from its default, DDS_LIVELINESS_BASED_REMOTE_PARTICIPANT_PURGE.

However, DDS_NO_REMOTE_PARTICIPANT_PURGE may be a good choice if the following conditions apply:

Discovery communication with a remote participant may be lost while data communication remains intact. This will not be the typical case if discovery takes place

over the Simple Discovery Protocol, but may occur if you are using RTI Enterprise Discovery Service. 1

1.RTI Enterprise Discovery Service is an optional package that provides participant-matching services for Connext applications.

8-38

Extensive and prolonged lack of discovery communication between participants is not expected to be common, either because loss of the participant will be rare, or because participants may be lost sporadically but will typically return again.

Maintaining inter-participant liveliness is problematic, perhaps because a participant has no writers with the appropriate LIVELINESS QosPolicy (Section 6.5.13) kind.

8.5.3.3Controlling the Reliable Protocol Used by Builtin-Topic DataWriters/DataReaders

The connection between the DataWriters and DataReaders for the publication and subscription builtin-topics are reliable. The publication_writer, subscription_writer, publication_reader, and subscription_reader parameters of the DISCOVERY_CONFIG QosPolicy (DDS Extension) (Section 8.5.3) configure the reliable messaging protocol used by Connext for those topics. Connext’s reliable messaging protocol is discussed in Chapter 10: Reliable Communications.

See also:

DATA_WRITER_PROTOCOL QosPolicy (DDS Extension) (Section 6.5.3)

DATA_READER_PROTOCOL QosPolicy (DDS Extension) (Section 7.6.1).

8.5.3.4Example

Users will be most interested in setting the participant_liveliness_lease_duration and participant_liveliness_assert_period values for their DomainParticipants. Basically, the lease duration governs how fast an application realizes another application dies unexpectedly. The shorter the periods, the quicker a DomainParticipant can determine that a remote participant is dead and act accordingly by declaring all of the remote DataWriters and DataReaders of that participant dead as well.

However, you should realize that the shorter the period the more liveliness packets will sent by the DomainParticipant. How many packets is also determined by the number of peers in the peer list of the participant–whether or not the peers on the list are actually alive.

8.5.3.5Properties

This QosPolicy cannot be modified after the DomainParticipant is created. It can be set differently on the publishing and subscribing sides.

8.5.3.6Related QosPolicies

DISCOVERY QosPolicy (DDS Extension) (Section 8.5.2)

DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 8.5.4)

WIRE_PROTOCOL QosPolicy (DDS Extension) (Section 8.5.9)

DATA_WRITER_PROTOCOL QosPolicy (DDS Extension) (Section 6.5.3)

DATA_READER_PROTOCOL QosPolicy (DDS Extension) (Section 7.6.1)

DATA_READER_RESOURCE_LIMITS QosPolicy (DDS Extension) (Section 7.6.2)

8.5.3.7Applicable Entities

DomainParticipants (Section 8.3)

8.5.3.8System Resource Considerations

Setting smaller values for time periods can increase the CPU and network bandwidth usage. Setting larger values for maximum limits can increase the maximum memory that Connext may allocate for a DomainParticipant while increasing the initial values will increase the initial memory allocated for a DomainParticipant.

8-39

8.5.4DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy (DDS Extension)

The DOMAIN_PARTICIPANT_RESOURCE_LIMITS QosPolicy includes various settings that configure how DomainParticipants allocate and use physical memory for internal resources, including the maximum sizes of various properties.

This QosPolicy sets maximum size limits on variable-length parameters used by the participant and its contained Entities. It also controls the initial and maximum sizes of data structures used by the participant to store information about locally-created and remotely-discovered entities (such as DataWriters/DataReaders), as well as parameters used by the internal database to size the hash tables used by the data structures.

By default, a DomainParticipant is allowed to dynamically allocate memory as needed as users create local Entities such as DataWriters and DataReaders or as the participant discovers new applications to store their information. By setting fixed values for the maximum parameters in this QosPolicy, you can bound the memory that can be allocated by a DomainParticipant. In addition, by setting the initial values to the maximum values, you can prevent DomainParticipants from allocating memory after the initialization period.

The maximum sizes of several variable-length parameters—such as the number of partitions that can be stored in the PARTITION QosPolicy (Section 6.4.5), the maximum length of data store in the USER_DATA QosPolicy (Section 6.5.25) and GROUP_DATA QosPolicy (Section 6.4.4), and many others—can be changed from their defaults using this QoS. However, it is important that all DomainParticipants that need to communicate with each other use the same set of maximum values. Otherwise, when these parameters are propagated from one DomainParticipant to another, a DomainParticipant with a smaller maximum length may reject the parameter resulting in an error.

This QosPolicy includes the members in Table 8.12. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 8.12 DDS_DomainParticipantResourceLimitsQosPolicy

Type

Field Name

Description

 

 

 

 

local_writer_allocation

 

 

 

 

 

local_reader_allocation

 

 

 

 

 

local_publisher_allocation

 

 

 

 

 

local_subscriber_allocation

 

 

 

Each allocation structure configures how many

 

local_topic_allocation

 

 

objects of each type, <object>_allocation, will be

 

remote_writer_allocation

 

allocated by the DomainParticipant.

 

 

 

remote_reader_allocation

See Configuring Resource Limits for Asynchronous

 

 

DDS_Allocation-

remote_participant_allocation

DataWriters (Section 8.5.4.1).

Settings_t

matching_writer_reader_pair_allocation

DDS_AllocationSettings_t

(see description

 

{

matching_reader_writer_pair_allocation

column)

 

DDS_Long initial_count;

ignored_entity_allocation

 

DDS_Long max_count;

 

 

 

content_filtered_topic_allocation

 

DDS_Long

 

 

 

content_filter_allocation

incremental_count;

 

 

};

 

read_condition_allocation

 

 

 

 

query_condition_allocation

 

 

 

 

 

outstanding_asynchronous_sample_

 

 

allocation

 

 

 

 

 

flow_controller_allocation

 

 

 

 

8-40

Table 8.12 DDS_DomainParticipantResourceLimitsQosPolicy

Type

Field Name

 

Description

 

 

 

 

 

 

 

 

 

local_writer_hash_buckets

 

 

 

 

 

 

 

local_reader_hash_buckets

 

 

 

 

 

 

 

local_publisher_hash_buckets

 

 

 

 

 

 

 

local_subscriber_hash_buckets

 

 

 

 

 

 

 

local_topic_hash_buckets

 

 

 

 

 

 

 

remote_writer_hash_buckets

 

 

 

 

 

 

remote_reader_hash_buckets

Used to configure the hash tables used for database

DDS_Long

remote_participant_hash_buckets

searches. If these numbers are too large then memory

 

is wasted. If these number are too small, searching for

 

matching_writer_reader_pair_

 

an object will be less efficient.

 

hash_buckets

 

 

 

 

 

 

 

 

matching_reader_writer_pair_

 

 

 

hash_buckets

 

 

 

 

 

 

 

ignored_entity_hash_buckets

 

 

 

 

 

 

 

content_filtered_topic_hash_buckets

 

 

 

 

 

 

 

content_filter_hash_buckets

 

 

 

 

 

 

 

flow_controller_hash_buckets

 

 

 

 

 

 

 

Configures the maximum number of destinations

 

 

that a message can be addressed in a single network

DDS_Long

max_gather_destinations

send operation. Can improve efficiency if the

 

 

underlying transport support can send to multiple

 

 

destinations.

 

 

 

 

 

participant_user_data_max_length

Controls

the maximum lengths of USER_DATA

 

 

 

topic_data_max_length

 

QosPolicy (Section 6.5.25), TOPIC_DATA QosPolicy

 

 

DDS_Long

publisher_group_data_max_length

(Section

5.2.1) and GROUP_DATA QosPolicy

 

(Section 6.4.4) for different entities.

subscriber_group_data_max_length

 

 

Must be configured to be the same values on all

 

 

 

writer_user_data_max_length

 

DomainParticipants in the same domain.

 

 

 

reader_user_data_max_length

 

 

 

 

 

 

 

 

Controls the maximum number of partitions that can

 

 

be assigned to a Publisher or Subscriber with the

DDS_Long

max_partitions

PARTITION QosPolicy (Section 6.4.5).

 

 

Must be configured to be the same value on all

 

 

DomainParticipants in the same domain.

 

 

 

 

 

Controls the maximum number of combined

 

 

characters among all partition names in the

DDS_Long

max_partition_cumulative_characters

PARTITION QosPolicy (Section 6.4.5).

 

 

Must be configured to be the same value on all

 

 

DomainParticipants in the same domain.

 

 

 

 

 

Maximum size of serialized string for type code.

DDS_Long

type_code_max_serialized_length

If your data type has an especially complex type

code, you may need to increase this value. See Using

 

 

Generated Types without Connext (Standalone)

 

 

(Section 3.7).

 

 

 

 

8-41

Table 8.12 DDS_DomainParticipantResourceLimitsQosPolicy

Type

Field Name

 

 

Description

 

 

 

 

 

 

 

 

 

 

Maximum length, in bytes, that the buffer to serialize

 

 

TypeObject can consume.

 

 

 

 

 

This parameter limits the size of the TypeObject that a

 

 

DomainParticipant is

able to

propagate.

Since

 

 

TypeObjects contain all of the information of a data

DDS_Long

type_object_max_serialized_length

structure, including the strings that define the names

 

 

of the members of a structure, complex data-

 

 

structures can result in TypeObjects larger than the

 

 

default maximum. This field allows you to specify a

 

 

larger value.

 

 

 

 

 

 

 

Cannot be unlimited.

 

 

 

 

 

 

 

 

 

Maximum number of bytes that a deserialized

DDS_Long

type_object_max_deserialized_length

TypeObject can consume.

 

 

 

This parameter limits the size of the TypeObject that a

 

 

 

 

DomainParticipant is able to store.

 

 

 

 

 

 

 

Threshold, in bytes, for dynamic memory allocation

 

 

for the deserialized TypeObject. Above it, the

DDS_Long

deserialized_type_object_dynamic_

memory for a TypeObject is allocated dynamically.

allocation_threshold

Below it, the memory is obtained from a pool of

 

 

 

fixed-size buffers. The size of the buffers is equal to

 

 

this threshold.

 

 

 

 

 

 

 

 

 

 

 

 

DDS_Long

contentfilter_property_max_length

Maximum

length

of

all

data related to

ContentFilteredTopics (Section 5.4).

 

 

 

 

 

 

 

 

 

Maximum number of channels that can be specified

DDS_Long

channel_seq_max_length

in a DataWriter’s MULTI_CHANNEL QosPolicy

 

 

(DDS Extension) (Section 6.5.14).

 

 

 

 

 

 

 

Maximum length of a channel filter_expression in a

DDS_Long

channel_filter_expression_max_length

DataWriter’s

MULTI_CHANNEL QosPolicy

(DDS

 

 

Extension) (Section 6.5.14).

 

 

 

 

 

 

 

 

Maximum number of properties ((name, value) pairs)

 

participant_property_list_max_length

that can

be

stored

in

the

DomainParticipant’s

 

PROPERTY QosPolicy (DDS Extension) (Section

 

 

 

 

6.5.17).

 

 

 

 

 

 

 

 

 

 

 

Maximum cumulative length (in bytes, including the

 

participant_property_string_max_length

null terminating characters) of all the (name, value)

 

 

pairs in a DomainParticipant’s Property QosPolicy.

 

 

 

 

 

Maximum number of properties ((name, value) pairs)

 

writer_property_list_max_length

that can be stored in a DataWriter’s Property

DDS_Long

 

QosPolicy.

 

 

 

 

 

 

 

 

Maximum cumulative length (in bytes, including the

 

writer_property_string_max_length

null terminating characters) of all the (name, value)

 

 

pairs in a DataWriter’s Property QosPolicy.

 

 

 

 

 

 

Maximum number of properties ((name, value) pairs)

 

reader_property_list_max_length

that can be stored in a DataReader’s Property

 

 

QosPolicy.

 

 

 

 

 

 

 

 

 

 

 

Maximum cumulative length (in bytes, including the

 

reader_property_string_max_length

null terminating characters) of all the (name, value)

 

 

pairs in a DataReader’s Property QosPolicy.

 

 

 

 

 

 

 

 

 

 

8-42

Table 8.12 DDS_DomainParticipantResourceLimitsQosPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

 

Maximum number of endpoint groups allowed in an

 

max_endpoint_groups

DATA_READER_PROTOCOL QosPolicy (DDS

 

 

Extension) (Section 7.6.1) .

 

 

 

DDS_Long

 

Maximum number of combined role_name

 

characters allowed in all endpoint groups in an

 

max_endpoint_group_cumulative_

AvailabilityQosPolicy. The maximum number of

 

characters

combined characters should account for a

 

 

terminating NULL ('') character for each role_name

 

 

string.

 

 

 

Most of the parameters for this QosPolicy are described in the Description column of the table. However, you may need to refer to the sections listed in the column to fully understand the context in which the parameter is used.

An important parameter in this QosPolicy that is often changed by users is the type_code_max_serialized_length. This parameter limits the size of the type code that a DomainParticipant is able to store and propagate for user data types. Type codes can be used by external applications to understand user data types without having the data type predefined in compiled form. However, since type codes contain all of the information of a data structure including the strings that define the names of the members of a structure, complex data structures can result in type codes larger than the default maximum of 2048 bytes. Thus it is common for users to set this parameter to a larger value. However, as with all parameters in this QosPolicy defining maximum sizes for variable-length elements, all DomainParticipants should set the same value for type_code_max_serialized_length.

The <object type>_hash_buckets configure the hash-table data structure that is used to efficiently search the database. The optimal number of buckets depend on the actual number of objects that will be stored in the hash table. So if you know how many DataWriters will be created in a DomainParticipant, you may change the value of local_writer_hash_buckets to balance memory usage against search efficiency. A smaller value will use up less memory, but a larger value will make database lookups for the object more efficient.

If you modify any of the <entity type>_data_max_length, max_partitions, or max_partition_cummulative_characters parameters, then you must make sure that they are modified to be the same value for all DomainParticipants in the same domain for all applications. If they are different and an application sends data that is larger than another application is configure to hold, then the two Entities, whether a matching DataWriter/DataReader pair or even two DomainParticipants will fail to connect.

8.5.4.1Configuring Resource Limits for Asynchronous DataWriters

When using an asynchronous Publisher, if a call to write() is blocked due to a resource limit, the block will last until the timeout period expires, which will prevent others from freeing the resource. To avoid this situation, make sure that the DomainParticipant’s resource_limits.outstanding_asynchronous_sample_allocation is always greater than the sum of all asynchronous DataWritersresource_limits.max_samples (see RESOURCE_LIMITS QosPolicy (Section 6.5.20)).

8.5.4.2Configuring Memory Allocation

The <object type>_allocation configures the number of <object type>’s that can be stored in the internal Connext database. For example, local_writer_allocation configures how many local

DataWriters can be created for the DomainParticipant.

The DDS_AllocationSettings_t structure sets the initial and maximum number of each object type that can be stored. Memory is allocated for the storage of the objects, thus initial_count will determine how much memory is initially allocated, and max_count will determine the maximum amount of memory that Connext is allowed to allocate. The incremental_count is

8-43

used to allocate more memory in chunks when the number of objects created exceed the initial_count.

You should modify these parameters only if you want to decrease the initial memory used by Connext when a DomainParticipant is created or increase the maximum number of local and remote Entities that can be stored in a DomainParticipant.

How Connext is allowed to allocate memory for a DomainParticipant after initialization depends on how you set these parameters.

1.Static memory allocation

No memory is allocated by Connext after creation. Set initial_count = max_count. The incremental_count should be set to 0.

Advantage: All memory allocation is done when creating the DomainParticipant; no dynamic allocation during run-time. You know immediately if you have enough memory to run in that configuration.

Disadvantage: Requires a fairly static system and/or good estimates on the number of Entities in the distributed system. Connext will fail to execute properly once the number of Entities exceed the configure bounds.

2.Dynamic, bounded allocation

Set initial_count to configure the initial amount of memory to be allocated. Set max_count to the maximum allowable upper bound (see the API Reference HTML documentation).

Advantage: Initial memory usage may be lower and memory is allocated as needed and only if needed.

Disadvantage: Connext may allocate memory dynamically which may have an impact on performance.

If you allow Connext to allocate memory dynamically, you can either:

Use fixed-size increments (set incremental_count to the desired fixed size). Advantage: well known amount of memory allocated each time. Disadvantage: may require more frequent allocations.

Double the amount of extra memory allocated each time memory is needed (set incremental_count to -1).

Advantage: requires fewer allocations.

Disadvantage: may allocate considerably more memory than is really needed.

8.5.4.3Example

For most applications, the default values for this QosPolicy may be sufficient. However, if an application uses the PARTITION, USER_DATA, TOPIC_DATA, or GROUP_DATA QosPolicies, the default maximum sizes of the data associated with those policies may need to be adjusted as required by the application. As noted previously, you must make sure that all DomainParticipants in the same domain use the same sets of values or it is possible that Connext will not successfully connect two Entities.

8.5.4.4Properties

This QosPolicy cannot be modified after the DomainParticipant is created. It can be set differently on the publishing and subscribing sides.

8-44

8.5.4.5Related QosPolicies

DATABASE QosPolicy (DDS Extension) (Section 8.5.1)

DISCOVERY_CONFIG QosPolicy (DDS Extension) (Section 8.5.3)

MULTI_CHANNEL QosPolicy (DDS Extension) (Section 6.5.14)

USER_DATA QosPolicy (Section 6.5.25)

TOPIC_DATA QosPolicy (Section 5.2.1)

GROUP_DATA QosPolicy (Section 6.4.4)

PARTITION QosPolicy (Section 6.4.5)

PROPERTY QosPolicy (DDS Extension) (Section 6.5.17)

8.5.4.6Applicable Entities

DomainParticipants (Section 8.3)

8.5.4.7System Resource Considerations

Memory and CPU usage are directly affected by the values set for parameters of this QosPolicy. See the detailed descriptions above for specifics.

8.5.5EVENT QosPolicy (DDS Extension)

The EVENT QosPolicy configures the internal Connext Event thread.

This QoS allows the you to configure thread properties such as priority level and stack size. You can also configure the maximum number of events that can be posted to the event thread. It contains the members in Table 8.13. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 8.13 DDS_EventQoSPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

thread.mask

Thread settings for the event thread used by Connext to wake up for a

DDS_Thread

timed event and possibly execute listener callbacks. The values used

thread.priority

for these settings are OS-dependent.

Settings_t

thread.stack_size

Note: thread.cpu_list and thread.cpu_rotation are not relevant in this

 

 

 

QoS policy.

 

 

 

DDS_Long

initial_count

Initial number of events that can be stored simultaneously.

 

 

 

DDS_Long

max_count

Maximum number of events that can be stored simultaneously.

 

 

 

The Event thread is used to wake up and execute timed events posted to the event queue. In a DomainParticipant, different Entities may have constraints that have to be checked at periodic intervals or at specific times. If the constraint is violated, a callback function may need to be executed. Timed events include checking for timeouts and deadlines, and executing internal and user timeout or exception handling routines/callbacks. A combination of a time, constraint, and callback can be considered to be an event. For more information, see Event Thread (Section 19.2).

For example, a DataReader may have a constraint that requires data to be received within a period of time specified by the DEADLINE QosPolicy (Section 6.5.5). For that DataReader, an event is stored by the Event thread so that it will wake up periodically to check to see if data has arrived in time. If not, the Event thread will execute the on_requested_deadline_missed() Listener callback of the DataReader (if it was installed and enabled).

A reliable connection between a DataWriter and DataReader will also post events for sending heartbeats used in the reliable protocol discussed in Chapter 10: Reliable Communications.

8-45

This QoS configures the parameters associated with thread creation as well as the number of events that can be simultaneously stored by the Event thread.

8.5.5.1Example

In a real-time operating system, the priority of the Event thread should be set relative to the priority of the events that it must handle. For example, you may want the Event thread to have a high priority if the deadlines and callbacks that it handles are time or safety critical. It may be critical that the data of a particular DataReader arrives on time or if not, alternative action is taken with minimal latency.

If you create many Entities in a DomainParticipant with QosPolicies that will post events that check deadlines, liveliness or send heartbeats, then you may need to increase the maximum number of events that can be stored by the Event thread.

If your application is sending a lot of reliable data, you should increase the event thread priority to be higher than the sending thread priority.

8.5.5.2Properties

This QosPolicy cannot be modified after the DomainParticipant is created. It can be set differently on the publishing and subscribing sides.

8.5.5.3Related QosPolicies

DATABASE QosPolicy (DDS Extension) (Section 8.5.1)

RECEIVER_POOL QosPolicy (DDS Extension) (Section 8.5.6)

8.5.5.4Applicable Entities

DomainParticipants (Section 8.3)

8.5.5.5System Resource Considerations

Increasing initial_count and max_count will increase initial and maximum memory used for storing events.

Setting the thread parameters correctly on a real-time operating system is usually critical to the proper overall functionality of the applications on that system. Larger values for the thread.stack_size parameter will use up more memory.

By default, a DomainParticipant will dynamically allocate memory as needed for events posted to the event thread. However, by setting an maximum value or setting the initial and maximum value to be the same, you can either bound the amount of memory allocated for the event thread or prevent a DomainParticipant from dynamically allocating memory for the event thread after initialization.

8.5.6RECEIVER_POOL QosPolicy (DDS Extension)

The RECEIVER_POOL QosPolicy configures the internal Connext thread used to process the data received from a transport. The Receive thread is described in detail in Section 19.3.

This QosPolicy contains the members in Table 8.14. For defaults and valid ranges, please refer to the API Reference HTML documentation.

This QosPolicy sets the thread properties, like priority level and stack size, for the threads used to receive and process data from transports. Connext uses a separate receive thread per port per transport plugin. To force Connext to use a separate thread to process the data for a DataReader, you should set a unique port for the TRANSPORT_UNICAST QosPolicy (DDS Extension)

8-46

Table 8.14 DDS_ReceiverPoolQoSPolicy

Type

Field Name

Description

 

 

 

 

 

 

 

thread.mask

Thread settings for the receive thread(s) used by

 

thread.priority

struct

Connext to process data received from a transport. The

thread.stack_size

values used for these settings are OS-dependent.

DDS_ThreadSettings_t

hread.cpu_list

See also: Controlling CPU Core Affinity for RTI Threads

 

 

thread.cpu_rotation

(Section 19.5).

 

 

 

 

 

DDS_Long

buffer_size

Size of the receive buffer in bytes.

 

 

 

DDS_Long

buffer_alignment

Byte-alignment of the receive buffer.

 

 

 

(Section 6.5.23) or TRANSPORT_MULTICAST QosPolicy (DDS Extension) (Section 7.6.5) for the

DataReader.

Connext creates at least one thread for every transport that is installed and enabled for use by the DomainParticipant for receiving data. These threads are used to process data samples received for the participant’s DataReaders, as well as messages used by Connext itself in support of the application discovery process discussed in Chapter 14: Discovery.

The user application may configure Connext to create many more threads for receiving data sent via multicast or even to dedicate a thread to process the data samples of a single DataReader received on a particular transport. This QosPolicy is used in the creation of all receive threads.

In many applications, users change the configuration of the builtin-transport message_size_max property to increase the size of the largest data packet that can be sent or received through the transport. Typically, users change the UDPv4 transport plugin's message_size_max to 65536 (64 K), which is the largest packet that can be sent/received via UDP. The ReceiverPool QosPolicy’s buffer_size should be set to at least the same value as the maximum message_size_max parameter across all of the transports being used that does not support zero-copy. (A transport that supports zero-copy will not use the receive buffer. The only built-in transport that supports zero-copy is the UDPv4 transport on VxWorks platforms.) If you are using the default configuration of the built-in transports, you should not need to change this buffer size.

In addition, if your application only uses transports that support zero-copy, then you do not need to modify the value of buffer_size, even if the message_size_max of the transport is changed. Transports that support zero-copy do not copy their data into the buffer provided by the receive thread. Instead, they provide the receive thread data in a buffer allocated by the transport itself. The only built-in transport that supports zero-copy is the UDPv4 transport on VxWorks platforms.

8.5.6.1Example

When new data arrives on a transport, the receive thread may invoke the on_data_available() of the Listener callback of a DataReader. Thus, you may want to adjust the priority of the receive threads with respect to the other threads in the application as appropriate for the proper operation of the system.

8.5.6.2Properties

This QosPolicy cannot be modified after the DomainParticipant is created. It can be set differently on the publishing and subscribing sides.

8.5.6.3Related QosPolicies

DATABASE QosPolicy (DDS Extension) (Section 8.5.1)

EVENT QosPolicy (DDS Extension) (Section 8.5.5)

8-47

8.5.6.4Applicable Entities

DomainParticipants (Section 8.3)

8.5.6.5System Resource Considerations

Increasing the buffer_size will increase memory used by a receive thread.

Setting the thread parameters correctly on a real-time operating system is usually critical to the proper overall functionality of the applications on that system. Larger values for the thread.stack_size parameter will use up more memory.

8.5.7TRANSPORT_BUILTIN QosPolicy (DDS Extension)

Connext comes with three different transport plugins built into the core libraries (for most supported target platforms). These are plugins for UDPv4, shared memory, and UDPv6.

This QosPolicy allows you to control which built-in transport plugins are used by a DomainParticipant. By default, only the UDPv4 and shared memory plugins are enabled (for most platforms; on some platforms, the shared memory plugin is not available). You can disable one or all of the builtin transports.

In some cases, users will disable the shared memory transport when they do not want applications to use shared memory to communicate when running on the same node.

It contains the member in Table 8.15. For the default and valid values, please refer to the API Reference HTML documentation.

Table 8.15 DDS_TransportBuiltinQosPolicy

Type

Field Name

Description

 

 

 

DDS_TransportBuiltinKindMask

mask

A mask with bits that indicate which built-in

transports will be installed.

 

 

 

 

 

Please see the API Reference HTML documentation (select Modules, Connext API Reference, Pluggable Transports, Using Transport Plugins and Built-in Transport Plugins) for more information.

See also: “Note:” on page 8-30.

8.5.7.1Example

See Section 8.5.7.5 for an example of why you may want to use this QosPolicy.

In addition, customers may wish to install and use their own custom transport plugins instead of any of the builtin transports. In that case, this QosPolicy may be used to disable all builtin transports.

8.5.7.2Properties

This QosPolicy cannot be modified after the DomainParticipant is created. It can be set differently on the publishing and subscribing sides.

8.5.7.3Related QosPolicies

TRANSPORT_SELECTION QosPolicy (DDS Extension) (Section 6.5.22)

TRANSPORT_UNICAST QosPolicy (DDS Extension) (Section 6.5.23)

TRANSPORT_MULTICAST QosPolicy (DDS Extension) (Section 7.6.5)

8-48

8.5.7.4Applicable Entities

DomainParticipants (Section 8.3)

8.5.7.5System Resource Considerations

You can save memory and other system resources if you disable the built-in transports that your application will not use. For example, if you only run a single application with a single DomainParticipant on each machine in your network, then you can disable the shared memory transport since your applications will never use it to send or receive messages.

8.5.8TRANSPORT_MULTICAST_MAPPING QosPolicy (DDS Extension)

The multicast address on which a DataReader wants to receive its data can be explicitly configured using the TRANSPORT_MULTICAST QosPolicy (DDS Extension) (Section 7.6.5). However in systems with many multicast addresses, managing the multicast configuration can become cumbersome. The TransportMulticastMapping QosPolicy is designed to make configuration and assignment of the DataReader's multicast addresses more manageable. When using this QosPolicy, the middleware will automatically assign a multicast receive address for a DataReader from a range by using configurable mapping rules.

DataReaders can be assigned a single multicast receive address using the rules defined in this QosPolicy on the DomainParticipant. This multicast receive address is exchanged during simple discovery in the same manner used when the multicast receive address is defined explicitly. No additional configuration on the writer side is needed.

Mapping within a range is done through a mapping function. The middleware provides a default hash (md5) mapping function. This interface is also pluggable, so you can specify a custom mapping function to minimize collisions.

Notes:

This QosPolicy is only available when using the C or C++ API on a platform that supports multicast on a UDPv4 or UDPv6 transport.

To use this QosPolicy, you must set the kind in the TRANSPORT_MULTICAST QosPolicy (DDS Extension) (Section 7.6.5) to AUTOMATIC.

This QosPolicy contains the member in Table 8.16.

Table 8.16 DDS_TransportMulticastMappingQosPolicy

 

Type

Field Name

Description

 

 

 

 

 

 

 

 

 

DDS_TransportMapping

value

A sequence of multicast communication settings, each of

 

SettingsSeq

which has the format shown in Table 8.17.

 

 

 

 

 

 

Table 8.17 DDS_TransportMulticastSettings_t

 

 

 

 

 

 

Type

Field Name

Description

 

 

 

 

 

 

 

A string containing a comma-separated list of IP

 

 

 

addresses or IP address ranges to be used to receive

 

char *

addresses

multicast traffic for the entity with a topic that matches

 

 

 

the topic_expression.

 

 

 

See Formatting Rules for Addresses (Section 8.5.8.1).

 

 

 

 

 

char *

topic_expression

A regular expression used to map topic names to

 

corresponding addresses.

 

 

 

 

 

 

 

 

DDS_TransportMulticast

mapping_function

Optional. Defines a user-provided pluggable mapping

 

MappingFunction_t

function. See Table 8.18.

 

 

 

 

 

 

8-49

Table 8.18 DDS_TransportMulticastMappingFunction_t

Type

Field Name

Description

 

 

 

 

 

 

 

 

Specifies a dynamic library that contains a mapping function.

char *

dll

You may specify a relative or absolute path.

If the name is specified as "foo", the library name on Linux systems will be

 

 

 

 

libfoo.so; on Windows systems it will be foo.dll.

 

 

 

 

 

Specifies the name of a mapping function in the library specified in the above

 

 

dll.

 

 

The function must implement the following interface:

char *

function_name

int function(const char* topic_name,

int numberOfAddresses);

 

 

The function must return an integer that indicates the index of the address to

 

 

use for the given topic_name. For example, if the first address in the list should

 

 

be used, it must return 0; if the second address in the list should be used, it

 

 

must return 1, etc.

 

 

 

8.5.8.1Formatting Rules for Addresses

The string must contain IPv4 or IPv6 addresses separated by commas. For example: "239.255.100.1,239.255.100.2,239.255.100.3"

You may specify ranges of addresses by enclosing the start and end addresses in square brackets. For example: "[239.255.100.1,239.255.100.3]".

You may combine the two approaches. For example: "239.255.200.1,[239.255.100.1,239.255.100.3], 239.255.200.3"

IPv4 addresses must be specified in Dot-decimal notation.

IPv6 addresses must be specified using 8 groups of 16-bit hexadecimal values separated by colons. For example: FF00:0000:0000:0000:0202:B3FF:FE1E:8329.

Leading zeroes can be skipped. For example: FF00:0:0:0:202:B3FF:FE1E:8329.

You may replace a consecutive number of zeroes with a double colon, but only once within an address. For example: FF00::202:B3FF:FE1E:8329.

8.5.8.2Example

This QoS policy configures the multicast ranges and mapping rules at the DomainParticipant level. You can configure a large set of multicast addresses on the DomainParticipant.

In addition, you can configure a mapping between topic names and multicast addresses. For example, topic "A" can be assigned to address 239.255.1.1 and topic "B" can be assigned to address 239.255.1.2.

This configuration is quite flexible. For example, you can specify mappings between a subset of topics to a range of multicast addresses. For example, topics "X", "Y" and Z" can be mapped to [239.255.1.1, 239.255.1.255], or using regular expressions, "X*" and "B-Z" can be mapped to a sub- range of addresses.

8.5.8.3Properties

This QosPolicy cannot be modified after the DomainParticipant is created.

8.5.8.4Related QosPolicies

TRANSPORT_MULTICAST QosPolicy (DDS Extension) (Section 7.6.5)

8.5.8.5Applicable Entities

DomainParticipants (Section 8.3)

8-50

8.5.8.6System Resource Considerations

See Section 7.6.5.5.

8.5.9WIRE_PROTOCOL QosPolicy (DDS Extension)

The WIRE_PROTOCOL QosPolicy configures some global Real-Time Publish Subscribe (RTPS) protocol-related properties for the DomainParticipant. The RTPS OMG-standard, interoperability protocol is used by Connext to format and interpret messages between DomainParticipants.

It includes the members in Table 8.19. For defaults and valid ranges, please refer to the API Reference HTML documentation. (The default values contain the correctly initialized wire protocol attributes. They should not be modified without an understanding of the underlying Real-Time Publish Subscribe (RTPS) wire protocol.)

Table 8.19 DDS_WireProtocolQosPolicy

Type

Field Name

 

Description

 

 

 

 

 

 

 

 

 

 

Unique identifier for participants that belong

DDS_Long

participant_id

to the same domain on the same host. See

 

 

Section 8.5.9.1.

 

 

 

 

 

 

 

 

rtps_host_id

A machine/OS-specific host ID, unique in the

 

domain. See Section 8.5.9.2.

 

 

 

 

 

 

 

 

 

 

 

 

 

rtps_app_id

A participant-specific ID,

unique

within

the

 

scope of the rtps_host_id. See Section 8.5.9.2.

DDS_UnsignedLong

 

 

 

 

 

 

 

 

 

An

instance-specific

ID

of

the

 

 

 

rtps_instance_id

DomainParticipant

that,

together

with

the

 

rtps_app_id, is unique within the scope of the

 

 

 

 

rtps_host_id. See Section 8.5.9.2.

 

 

 

 

 

 

 

 

rtps_well_known

Determines the

well-known multicast

and

DDS_RtpsWellKnownPorts_t

unicast ports for discovery and user traffic. See

_ports

 

Section 8.5.9.3.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

rtps_reserved_ports

Specifies which

well-known multicast

and

DDS_RtpsReservedPortKindMask

unicast ports to reserve when enabling the

_mask

 

 

DomainParticipant.

 

 

 

DDS_WireProtocolQosPolicyAuto

rtps_auto_id_kind

Kind of auto mechanism used to calculate the

Kind

 

GUID prefix.

 

 

 

 

Note that DATA_WRITER_PROTOCOL QosPolicy (DDS Extension) (Section 6.5.3) and DATA_READER_PROTOCOL QosPolicy (DDS Extension) (Section 7.6.1) configure RTPS and reliability properties on a per DataWriter and DataReader basis.

8.5.9.1Choosing Participant IDs

When you create a DomainParticipant, you must specify a domain ID, which identifies the communication channel across the whole system. Each DomainParticipant in the same domain on the same host also needs a unique integer, known as the participant_id.

The participant_id uniquely identifies a DomainParticipant from other DomainParticipants in the same domain on the same host. You can use the same participant_id value for DomainParticipants in the same domain but running on different hosts.

The participant_id is also used to calculate the default unicast user-traffic and the unicast meta- traffic port numbers, as described in Ports Used for Discovery (Section 14.5). If you only have one DomainParticipant in the same domain on the same host, you will not need to modify this value.

You can either allow Connext to select a participant ID automatically (by setting participant_id to -1), or choose a specific participant ID (by setting participant_id to the desired value).

8-51

Automatic Participant ID Selection

The default value of participant_id is -1, which means Connext will select a participant ID for you.

Connext will pick the smallest participant ID, based on the unicast ports available on the transports enabled for discovery, based on the unicast and/or multicast ports available on the transports enabled for discovery and/or user traffic.

The rtps_reserved_ports_mask field determines which ports to check when picking the next available participant ID. The reserved ports are calculated based on the formula specified in Inbound Ports for Meta-Traffic (Section 14.5.1) an Inbound Ports for User Traffic (Section 14.5.2). By default, Connext will reserve the meta-traffic unicast port, the meta-traffic multicast port, and the user traffic unicast port.

Connext will attempt to resolve an automatic port ID either when a DomainParticipant is enabled, or when a DataReader or a DataWriter is created. Therefore, all the transports enabled for discovery must have been registered by this time. Otherwise, the discovery transports registered after resolving the automatic port index may produce port conflicts when the DomainParticipant is enabled.

To see what value Connext has selected, either:

Change the verbosity level of the NDDS_CONFIG_LOG_CATEGORY_API category to NDDS_CONFIG_LOG_VERBOSITY_STATUS_LOCAL (see Controlling Messages from Connext (Section 21.2)).

Call get_qos() and look at the participant_id value in the WIRE_PROTOCOL QosPolicy (DDS Extension) (Section 8.5.9) after the DomainParticipant is enabled.

Manual Participant ID Selection

If you do have multiple DomainParticipants on the same host, you should use consecutively numbered participant indices start from 0. This will make it easier to specify the discovery peers using the initial_peers parameter of this QosPolicy or the NDDS_DISCOVERY_PEERS environment variable. See Configuring the Peers List Used in Discovery (Section 14.2) for more information.

Do not use random participant indices since this would make DISCOVERY incredibly difficult to configure. In addition, the participant_id has a maximum value of 120 (and will be less for domain IDs other than 0) when using an IP-based transport since the participant_id is used to create the port number (see Ports Used for Discovery (Section 14.5)), and for IP, a port number cannot be larger than 65536.

For details, see Ports Used for Discovery (Section 14.5).

8.5.9.2Host, App, and Instance IDs

The rtps_host_id, rtps_app_id, and rtps_instance_id values are used by the RTPS protocol to allow Connext to distinguish messages received from different DomainParticipants. Their combined values must be globally unique across all existing DomainParticipants in the same domain. In addition, if an application dies unexpectedly and restarted, the IDs used by the new instance of DomainParticipants should be different than the ones used by the previous instances. A change in these values allows other DomainParticipants to know that they are communicating with a new instance of an application, and not the previous instance.

If the value of rtps_host_id is set to DDS_RTPS_AUTO_ID, the IPv4 address of the host is used as the host ID. If the host does not have an IPv4 address, then you should set this value to uniquely distinguish the host from other nodes in the system.

If the value of rtps_app_id is set to DDS_RTPS_AUTO_ID, the process (or task) ID is used. There can be at most 256 distinct participants in a shared address space (process) with a unique rtps_app_id.

If the value of rtps_instance_id is set to DDS_RTPS_AUTO_ID, a counter is assigned that is incremented per new participant. Thus, together with rtps_app_id, there can be at most 2^64

8-52

distinct participants in a shared address space with a unique RTPS Globally Unique Identifier (GUID).

8.5.9.3Ports Used for Discovery

The rtps_well_known_ports structure allows you to configure the ports that are used for discovery of inbound meta-traffic (discovery data internal to Connext) and user traffic (from your application).

It includes the members in Table 8.20. For defaults and valid ranges, please refer to the API Reference HTML documentation.

Table 8.20 DDS_RtpsWellKnownPorts_t

Type

Field Name

Description

 

 

 

 

 

The base port offset. All mapped well-known ports are

 

port_base

offset by this value. Resulting ports must be within the

 

 

range imposed by the underlying transport.

 

 

 

 

domain_id_gain

Tunable gain parameters. See Ports Used for

DDS_Long

participant_id_gain

Discovery (Section 14.5).

 

 

 

builtin_multicast_port_offset

Additional offset for meta-traffic port. See Inbound Ports

 

builtin_unicast_port_offset

for Meta-Traffic (Section 14.5.1).

 

 

 

 

user_multicast_port_offset

Additional offset for user traffic port. See Inbound Ports

 

user_unicast_port_offset

for User Traffic (Section 14.5.2).

 

 

 

8.5.9.4Controlling How the GUID is Set (rtps_auto_id_kind)

In order for the discovery process to work correctly, each DomainParticipant must have a unique identifier. This QoS policy specifies how that identifier should be generated.

RTPS defines a 96-bit prefix to this identifier; each DomainParticipant must have a unique value of this prefix relative to all other participants in its domain. In order to make it easier to control how this 96-bit value is generated, Connext divides it into three integers: a host ID, the value of which is based on the identity of the machine on which the participant is executing, an application ID (whose value is based on the process or task in which the participant is contained), and an instance ID which identifies the participant itself.

This QoS policy provides you with a choice of algorithms for generating these values automatically. In case none of these algorithms suit your needs, you may also choose to specify some or all of them yourself.

The following three fields compose the GUID prefix and by default are set to DDS_RTPS_AUTO_ID. The meaning of this flag depends on the value assigned to rtps_auto_id_kind.

rtps_host_id

rtps_app_id

rtps_instance_id

Depending on the rtps_auto_id_kind value, there are two different scenarios:

Scenario 1:

In the default and most common scenario, rtps_auto_id_kind is set to DDS_RTPS_AUTO_ID_FROM_IP. Doing so, each field is interpreted as follows:

rtps_host_id: the 32 bit value of the IPv4 of the first up and running interface of the host machine is assigned

rtps_app_id: the process (or task) ID is assigned

8-53

rtps_instance_id: A counter is assigned that is incremented per new participant

Note: If the IP address assigned to the interface is not unique within the network (for instance, if it is not configured), then is it possible that the GUID (specifically, the rtps_host_id portion) may also not be unique.

Scenario 2:

In this situation, Connext provides a different value for rtps_auto_id_kind: DDS_RTPS_AUTO_ID_FROM_MAC. As the name suggests, this alternative mechanism uses the MAC address instead of the IPv4 address. Since the MAC address size is up to 64 bits, the logical mapping of the host information, the application ID, and the instance identifiers has to change.

Note to Solaris Users: To use DDS_RTPS_AUTO_ID_FROM_MAC, you must run the Connext application while logged in as ‘root.’

Using DDS_RTPS_AUTO_ID_FROM_MAC, the default value of each field is interpreted as follows:

rtps_host_id: the first 32 bits of the MAC address of the first up and running interface of the host machine are assigned

rtps_app_id: the last 32 bits of the MAC address of the first up and running interface of the host machine are assigned

rtps_instance_id: this field is split into two different parts. The process (or task) ID is assigned to the first 24 bits. A counter is assigned to the last 8 bits. This counter is incremented per new participant. In both scenarios, you can change the value of each field independently.

If DDS_RTPS_AUTO_ID_FROM_MAC is used, the rtps_instance_id has been logically split into two parts: 24 bits for the process/task ID and 8 bits for the per new participant counter. To give to users the ability to manually set the two parts independently, a bit field mechanism has been introduced for the rtps_instance_id field when it is used in combination with DDS_RTPS_AUTO_ID_FROM_MAC. If one of the two parts is set to 0, only this part will be handled by Connext and you will be able to handle the other one manually.

Some examples are provided to better explain the behavior of this QoSPolicy in case you want to change the default behavior with DDS_RTPS_AUTO_ID_FROM_MAC.

The first step is to get the DomainParticipant QoS from the DomainParticipantFactory:

DDS_DomainParticipantFactory_get_default_participant_qos( DDS_DomainParticipantFactory_get_instance(), &participant_qos);

Next, change the WireProtocolQosPolicy using one of the following options.

Then create the DomainParticipant as usual using the modified QoS structure instead of the default one.

Option 1. Use DDS_RTPS_AUTO_ID_FROM_MAC to explicitly set just the application/task identifier portion of the rtps_instance_id field:

participant_qos.wire_protocol.rtps_auto_id_kind = DDS_RTPS_AUTO_ID_FROM_MAC; participant_qos.wire_protocol.rtps_host_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_app_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_instance_id =

(/* App ID */ (12 << 8) |

/* Instance ID*/ (DDS_RTPS_AUTO_ID));

Option 2. Only set the per participant counter and let Connext handle the application/task identifier:

8-54

participant_qos.wire_protocol.rtps_auto_id_kind = DDS_RTPS_AUTO_ID_FROM_MAC; participant_qos.wire_protocol.rtps_host_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_app_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_instance_id =

(/* App ID */ (DDS_RTPS_AUTO_ID) | /* Instance ID*/ (12));

Option 3. Set the entire rtps_instance_id field yourself:

participant_qos.wire_protocol.rtps_auto_id_kind = DDS_RTPS_AUTO_ID_FROM_MAC; participant_qos.wire_protocol.rtps_host_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_app_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_instance_id =

( /* App ID */ (12 << 8)) | /* Instance ID */ (9) )

Note: If you are using DDS_RTPS_AUTO_ID_FROM_MAC as rtps_auto_id_kind and you decide to manually handle the rtps_instance_id field, you must ensure that both parts are non- zero (otherwise Connext will take responsibility for them).

RTI recommends that you always specify the two parts separately in order to avoid errors.

Option 4. Let Connext handle the entire rtps_instance_id field:

participant_qos.wire_protocol.rtps_auto_id_kind = DDS_RTPS_AUTO_ID_FROM_MAC; participant_qos.wire_protocol.rtps_host_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_app_id = DDS_RTPS_AUTO_ID; participant_qos.wire_protocol.rtps_instance_id = DDS_RTPS_AUTO_ID;

Note: If you are using DDS_RTPS_AUTO_ID_FROM_MAC as rtps_auto_id_kind and you decide to manually set the rtps_instance_id field, you must ensure that both parts are non-zero (otherwise Connext will take responsibility for them).

RTI recommends that you always specify the two parts separately in order to clearly show the difference.

8.5.9.5Example

On many real-time operating systems, and even on some non-real-time operating systems, when a node is rebooted, and applications are automatically started, process ids are deterministically assigned. That is, when the system restarts or if an application dies and is restarted, the application will be reassigned the same process or task ID.

This means that Connext’s automatic algorithm for creating unique rtps_app_id’s will produce the same value between sequential instances of the same application. This will confuse the other DomainParticipants on the network into thinking that they are communicating with the previous instance of the application instead of a new instance. Errors usually resulting in a failure to communicate will ensue.

Thus for applications running on nodes that may be rebooted without letting the application shutdown appropriately (destroying the DomainParticipant), especially on nodes running real- time operating systems like VxWorks or LynxOS, you will want to set the rtps_app_id manually. We suggest that a strictly incrementing counter is stored either on a file system or in non-volatile RAM is used for the rtps_app_id.

Whatever method you use, you should make sure that the rtps_app_id is unique across all DomainParticipants running on a host as well as DomainParticipants that were recently running on the host. After a period configured through the DISCOVERY_CONFIG QosPolicy existing applications will eventually flush old DomainParticipants that did not properly shutdown from their databases. When that is done, then rtps_app_id may be reused.

8-55

8.5.9.6Properties

This QosPolicy cannot be modified after the DomainParticipant is created.

If manually set, it must be set differently for every DomainParticipant in the same domain across all applications. The value of rtps_app_id should also change between different invocations of the same application (for example, when an application is restarted).

8.5.9.7Related QosPolicies

DISCOVERY_CONFIG QosPolicy (DDS Extension) (Section 8.5.3)

8.5.9.8Applicable Entities

DomainParticipants (Section 8.3)

8.5.9.9System Resource Considerations

The use of this policy does not significantly impact the use of resources.

8.6Clock Selection

Connext uses clocks to measure time and generate timestamps.

The middleware uses two clocks: an internal clock and an external clock.

The internal clock measures time and handles all timing in the middleware.

The external clock is used solely to generate timestamps (such as the source timestamp and the reception timestamp), in addition to providing the time given by the DomainParticipant’s get_current_time() operation (see Section 8.3.13.2).

8.6.1Available Clocks

Two clock implementations are generally available: the real-time clock and the monotonic clock.

The real-time clock provides the real time of the system. This clock may generally be monotonic, but may not be guaranteed to be so. It is adjustable and may be subject to small and large changes in time. The time obtained from this clock is generally a meaningful time, in that it is the amount of time from a known epoch. For the purposes of clock selection, this clock can be referenced by the names "realtime" or "system"—both names map to the same real-time clock.

The monotonic clock provides times that are monotonic from a clock that is not adjustable. This clock is not subject to changes in the system or realtime clock, which may be adjusted by the user or via time synchronization protocols. However, this clock’s time generally starts from an arbitrary point in time, such as system start-up. Note that the monotonic clock is not available for all architectures. Please see the Platform Notes for the architectures on which it is supported. For the purposes of clock selection, this clock can be referenced by the name "monotonic".

8.6.2Clock Selection Strategy

To configure the clock selection, use the DomainParticipant’s PROPERTY QosPolicy (DDS Extension) (Section 6.5.17). Table 8.21 lists the supported properties.

By default, both the internal and external clocks use the realtime clock.

If you want your application to be robust to changes in the system time, you may use the monotonic clock as the internal clock, and leave the system clock as the external clock. However,

8-56

Table 8.21 Clock Selection Properties

Property

Description

 

 

 

 

 

Comma-delimited list of clocks to use for the external clock, in the order of

dds.clock.external_clock

preference.

 

Valid clock names are “realtime”, “system”, or “monotonic”.

 

 

 

Comma-delimited list of clocks to use for the internal clock, in the order of

dds.clock.internal_clock

preference.

 

Valid clock names are “realtime”, “system”, or “monotonic”.

 

 

note that this may slightly diminish performance, in that both the send and receive paths may need to get times from both clocks.

Since the monotonic clock is not available on all architectures, you may want to specify "monotonic, realtime" for the internal_clock property (see Table 8.21). By doing so, the middleware will attempt to use the monotonic clock if it is available, and will fall back to the realtime clock if the monotonic clock is not available.

If you want the application to be robust to changes in the system time, you are not relying on source timestamps, and you want to avoid obtaining times from both clocks, you may use the monotonic clock for both the internal and external clocks.

8.7System Properties

Connext uses the DomainParticipant’s PropertyQosPolicy to maintain a set of properties that provide system information, such as the hostname.

Unless the default the DDS_DomainParticipantQos structure (see Setting DomainParticipant QosPolicies (Section 8.3.6)) is overwritten, the system properties are automatically set in the DDS_DomainParticipantQos structure that is obtained by calling the DomainParticipantFactory’s get_default_participant_qos() operation or by using the constant DDS_PARTICIPANT_QOS_DEFAULT.

System properties are also automatically set in the DDS_DomainParticipantQos structure loaded from an XML QoS profile unless you disable property inheritance using the attribute inherit in the XML tag <property>.

By default, the system properties are propagated to other DomainParticipants in the system and can be accessed through the property field in the Participant Built-in Topic’s Data Type (DDS_ParticipantBuiltinTopicData) (see Table 16.1 on page 16-2).

You can disable propagation of individual properties by setting the property’s propagate flag to FALSE or by removing the property using the PropertyQosPolicyHelper operation, remove_property() (see Table 6.56, "PropertyQoSPolicyHelper Operations" on page 6-114).

The number of system properties that are initialized for a DomainParticipant is platform specific. In this release, the hostname is only supported on Linux and Windows platforms. The process_id is supported on all platforms. These properties will only be created if Connext can obtain the information for them; see Table 8.22, "System Properties" on page 8-58.

System properties are affected by the DomainParticipantResourceLimitsQosPolicy’s participant_property_list_max_length and participant_property_string_max_length.

8-57

Table 8.22 System Properties

Property Name

Description

 

 

 

 

dds.sys_info.hostname

Hostname

 

 

dds.sys_info.process_id

Process ID

 

 

8-58

Chapter 9 Building Applications

This chapter provides instructions on how to build Connext applications for the following platforms:

UNIX-Based Platforms (Section 9.3) (including Solaris™, Red Hat® and Yellow Dog™ Linux, QNX®, and LynxOS® systems)

Windows Platforms (Section 9.4)

Java Platforms (Section 9.5)

While you can create applications for other operating systems, the platforms presented in this chapter are a good starting point. We recommend that you first build and test your application on one of these systems.

Instructions for other supported target platforms are provided in the Platform Notes.

To build a non-Java application using Connext, you must specify the following items:

NDDSHOME environment variable

Connext header files

Connext libraries to link

Compatible system libraries

Compiler options

To build Java applications using Connext, you must specify the following items:

NDDSHOME environment variable

Connext JAR file

Compatible Java virtual machine (JVM)

Compiler options

This chapter describes the basic steps you will take to build an application on the above- mentioned platforms. Specific details, such as exactly which libraries to link, compiler flags, etc. are in the Platform Notes.

9.1Running on a Computer Not Connected to a Network

If you want to run Connext applications on the same computer, and that computer is not connected to a network, you must set NDDS_DISCOVERY_PEERS so that it will only use shared memory. For example:

9-1

set NDDS_DISCOVERY_PEERS=4@shmem://

(The number 4 is only an example. This is the maximum participant ID.)

9.2Connext Header Files — All Architectures

You must include the appropriate Connext header files, which are listed in Table 9.1. The header files that need to be included depend on the API being used.

Table 9.1 Header Files to Include for Connext (All Architectures)

Connext API

Header Files

 

 

 

 

C

#include “ndds/ndds_c.h”

 

 

C++

#include “ndds/ndds_cpp.h”

 

 

C++/CLI, C#, Java

none

 

 

For the compiler to find the included files, the path to the appropriate include directories must be provided. Table 9.2 lists the appropriate include path for use with the compiler. The exact path depends on where you installed Connext. For example, it may be C:\Program Files\RTI\ndds.5.0.x\include or /opt/rti/ndds.5.0.x/include (where x stands for the version

Table 9.2 Include Paths for Compilation (All Architectures)

Connext API

Include Path Directories

 

 

 

 

C and C++

<your Connext installation directory>/include

<your Connext installation directory>/include/ndds

 

 

 

C++/CLI, C#, Java

none

 

 

number of the current release).

$(NDDSHOME) should be set to the installation directory of Connext 5.0.x, where x stands for the version number of the current release.

The header files that define the data types you want to use within the application also need to be included. For example, Table 9.3 lists the files to be include for type “Foo” (these are the filenames generated by rtiddsgen, described in Chapter 3).

Table 9.3 Header Files to Include for Data Types (All Architectures)

Connext API

User Data Type Header Files

 

 

 

 

C and C++

#include “Foo.h”

#include “FooSupport.h”

 

 

 

C++/CLI, C#, Java

none

 

 

9.3UNIX-Based Platforms

Before building a Connext application for a UNIX-based platform (including Solaris, Red Hat and Yellow Dog Linux, QNX, and LynxOS systems), make sure that:

A supported version of your architecture is installed. See the Platform Notes for supported architectures.

9-2

Connext 5.0.x is installed (where x stands for the version number of the current release). For installation instructions, refer to Section 2.1.1 in the Getting Started Guide.

A “make” tool is installed. RTI recommends GNU Make. If you do not have it, you may be able to download it from your operating system vendor. Learn more at www.gnu.org/software/make/ or download from ftpmirror.gnu.org/make as source code.

The NDDSHOME environment variable is set to the root directory of the Connext installation (such as /opt/rti/ndds5.0.x, where x stands for the version number of the current release). To confirm, type this at a command prompt:

echo $NDDSHOME

env | grep NDDSHOME

If it is not set or is set incorrectly, type:

setenv NDDSHOME <correct directory>

To compile a Connext application of any complexity, either modify the auto-generated makefile created by running rtiddsgen or write your own makefile.

9.3.1Required Libraries

All required system and Connext libraries are listed in the Platform Notes.

You must choose between dynamic (shared) and static libraries. Do not mix the different types of libraries during linking. The benefit of linking against the dynamic libraries is that your final executables’ sizes will be significantly smaller. You will also use less memory when you are running several Connext applications on the same node. However, shared libraries require more set-up and maintenance during upgrades and installations.

To see if dynamic libraries are supported for your target architecture, see the Platform Notes1.

9.3.2Compiler Flags

See the Platform Notes for information on compiler flags.

9.4Windows Platforms

Before building an application for a Microsoft Windows® platform, make sure that:

Supported versions of Windows and Visual C++ or Visual Studio .NET are installed. See Section 10 in the Platform Notes.

Connext 5.0.x is installed (where x stands for the version number of the current release). For installation instructions, refer to the Section 2.1.2 in the Getting Started Guide.

The NDDSHOME environment variable is set to the root directory of the Connext installation (such as C:\Program Files\RTI\ndds5.0.x, where x stands for the version number of the current release). To confirm, type this at a command prompt:

echo %NDDSHOME%

Use the dynamic MFC Library (not static).

1.In the Platform Notes, see the “Building Instructions...” table for your target architecture.

9-3

To avoid communication problems in your Connext application, use the dynamic MFC library, not the static version. (If you use the static version, your Connext application may stop receiving samples once the Windows sockets are initialized.)

To compile a Connext application of any complexity, use a project file in Microsoft Visual Studio. The project settings are described below. Section 10 in the Getting Started Guide contains additional information.

9.4.1Using Microsoft Visual C++ 6.0

1.From the menu bar, select Project, Settings...

2.Select the multi-threaded DLL project setting by following these steps:

a.Select the C/C++ tab.

b.From the Category pull-down menu, select Code Generation.

c.From the Use run-time library category, select one of the options from Table 9.4.

Table 9.4 Runtime Library Settings for Visual Studio .NET & Visual Studio .NET 2003

If you are using this Library Format...

Set the ‘Use run-time library’ field to...

 

 

Release version of static libraries

Multi-threaded

 

 

Debug version of static libraries

Debug Multi-threaded

 

 

Release version of dynamic libraries

Multi-threaded DLL

 

 

Debug version of dynamic libraries

Debug Multi-threaded DLL

 

 

3.Link in the Connext and system libraries:

a.See Section 10 in the Platform Notes for a list of required libraries. You have a choice of whether to link with Connext’s static or dynamic libraries. Decide whether or not you want debugging symbols included.

b.Select the Link tab on the Project Settings Window.

c.From the Category: pull-down menu, select the Input option.

d.Add the appropriate Connext and system libraries to the beginning of the Object/ Library modules list. Be sure to use a space as a delimiter between libraries, not a comma. (Note that some of the system libraries may already be in the list.)

e.Specify the path to the libraries in the Additional library path field by adding the path for your specific architecture. For example:

c:\rti\ndds.5.0.x\lib\i86Win32VC60

Your path may differ, depending on where you installed Connext. Replace the x in 5.0.x with the version number for the current release.

4.Specify the path to Connext’s header files:

a.Select the C/C++ tab.

b.From the Category pull-down menu, select the Preprocessor option.

c.In the Additional include directories field, add paths to the “include” and “include\ndds“ directories. For example:

c:\rti\ndds.5.0.x\include\

c:\rti\ndds.5.0.x\include\ndds

Your paths may differ, depending on where you installed Connext. Replace the x in 5.0.x with the version number for the current release.

5. Specify the compiler flags:

9-4

a.Select the C/C++ tab.

b.From the Category pull-down menu, select the Preprocessor option.

c.In the Preprocessor definitions field, add the compiler flags listed in Table 10.2, “Building Instructions for Windows Host Architectures,” on page 3-62. You will see the compiler flag appear in the Project Options field.

9.4.2Using Visual Studio .NET, Visual Studio .NET 2003, or Visual Studio 2005

1.Select the multi-threaded project setting:

a.From the Project menu, select Properties.

b.Select the C/C++ folder.

c.Select Code Generation.

d.Set the Runtime Library field to one of the options from Table 9.5.

Table 9.5 Runtime Library Settings for Visual Studio .NET, Visual Studio .NET 2003, Visual Studio 2005

If You are using this Library Format...

Set the Runtime Library field to...

 

 

 

 

Release version of static libraries

Multi-threaded (/MT)

 

 

Debug version of static libraries

Multi-threaded Debug (/MTd)

 

 

Release version of dynamic libraries

Multi-threaded DLL (/MD)

 

 

Debug version of dynamic libraries

Multi-threaded Debug DLL (/MDd)

 

 

2.Link against the Connext libraries:

a.Select the Linker folder on the Project, Properties dialog box.

b.Select the Input properties.

c.See Section 10 in the Platform Notes for a list of required libraries. You have a choice of whether to link with Connext’s static or dynamic libraries. Decide whether or not you want debugging symbols on. In either case, be sure to use a space as a delimiter between libraries, not a comma. Add the libraries to the beginning of the Additional

Dependencies field.

d.Select the General properties.

e.Add one of the following to the Additional library path field:

$(NDDSHOME)\lib\i86Win32VC70 (for Visual Studio .NET)

$(NDDSHOME)\lib\i86Win32VS2003 (for Visual Studio .NET 2003)

$(NDDSHOME)\lib\i86Win32VS2005 (for Visual Studio .NET 2005)

3.Specify the path to Connext’s header file:

a.Select the C/C++ folder.

b.Select the General properties.

c.In the Additional include directories: field, add paths to the “include” and “include\ndds” directories. For example:

c:\rti\ndds.5.0.x\include\

c:\rti\ndds.5.0.x\include\ndds

Your paths may differ, depending on where you installed Connext.

9-5

9.5Java Platforms

Before building an application for a Windows or UNIX Java platform, make sure that:

Connext 5.0.x is installed (where x stands for the version number of the current release). For installation instructions, refer to Chapter 2 in the Getting Started Guide.

A supported version of the Java 2 software development kit (J2SDK) is installed. See the Platform Notes.

9.5.1Java Libraries

Connext requires that certain Java archive (JAR) files be on your classpath when running Connext applications. See the Platform Notes for more details.

9.5.2Native Libraries

Connext for Java is implemented using Java Native Interface (JNI), so it is necessary to provide your Connext distributed applications access to certain native shared libraries. See the Platform Notes for more details.

9-6

Index, Part 2

Symbols

@copy rtiddsgen directive 3-57 @key rtiddsgen directive 3-56

@resolve-name rtiddsgen directive 3-58 @top-level rtiddsgen directive 3-60 $NDDSHOME 3-80

A

absolute_generation_rank (DDS_SampleInfo) 7-46, 7-48 accept_unknown_peers 8-30 to 8-31

access_scope (Presentation QoS) 6-67 to 6-68 ACKNACK messages 6-15, 6-33 acknowledgment_kind (Reliability QoS) 6-118 acknowledgments 6-15, 6-33

ALIVE instance state 7-47 allocation of memory 7-54

DataReaders 7-59 app ID 8-52

app_ack_period (DDS_RtpsReliableReaderProtocol_t) 7-52 application acknowledgment 6-33

as_Entity() 6-14, 7-15 assert_liveliness() 6-53, 6-105, 8-22 asynchronous data 7-2

autodispose_unregistered_instances (WriterDataLifeCycle QoS) 6-130

automatic participant ID 8-52

autoregister_instances (DataWriterResouceLimits QoS) 6- 89

B

batching small samples 6-54, 6-75 begin_coherent_changes() 6-33, 6-68 BEST_EFFORT (Reliable QoS) 6-118 blocking threads 6-89

building applications 9-1 to 9-3 builtin data types

definition 3-6

See also data types.

See also user data types. built-in transports 8-48

builtin_discovery_plugins (DiscoveryConfig QoS) 8-35 BuiltinTopicReaderResourceLimits 8-36

C

cleanup_period 8-27 clear() 6-12, 7-12 clock selection 8-56

coalescing samples 6-77 coherent sets 6-32

coherent_access (Presentation QoS) 6-67 to 6-68 collaborative DataWriters 6-72

command-line options for rtiddsgen 3-80 compatibility between QoS 6-46, 7-33 compile (ContentFilteredTopic function) 5-27 compiling applications 9-1

concurrent threads 6-89 Conditions 4-26

example code 4-30 contains_entity() 8-22 content filter 5-25

syntax for 5-16 ContentFilteredTopics 6-89

compile function 5-27 creating 5-12

custom filters 5-16, 5-24 deleting 5-14

evaluate function 5-28 filter syntax 5-16 finalize function 5-28 introduction 5-10

setting filter expressions 5-14 writer_attach function 5-29 writer_detach 5-29

copy_from_topic_qos() 6-12, 6-51, 7-12, 7-36 copy() 6-12, 7-12

create_datawriter() 6-29 create_publisher() 6-5 create_topic() 5-3

D

data samples. See samples. data types

supported 3-3, 3-6

DATA_AVAILABLE status 4-14, 7-16, 7-24 DATA_ON_READERS status 4-14, 7-16 DATA_READER_CACHE status 7-24 DATA_READER_PROTOCOL status 7-24 DATA_WRITER_CACHE status 6-22 DATA_WRITER_PROTOCOL status 6-22 Database QoS 8-27

DataReaderProtocol QoS 7-50 DataReaderResourceLimits QoS 7-54 DataReaders

checking status for 7-22 copying QoS for 7-36 copying Topic QoS 7-12 creating/deleting 7-19 finding matching writers 7-36 Listeners for 7-21

memory allocation 7-59 operations on 7-17 QoS for 7-32

status for 7-23 DataWriterProtocol QoS 6-79 DataWriterResourceLimits QoS 6-89 DataWriters

copying Topic QoS 6-12, 6-51, 7-12 creating/deleting 6-18

definition 6-2, 7-3

finding matching readers 6-52

Listener’s relationship to Publishers’ 6-13 Listeners for 6-20

operations on 6-16

ordering samples from multiple 6-93 preventing starvation 7-58

QoS for 6-43, 6-71 resource limits for 6-89 samples per 7-57

saving samples for later use 6-95 status for 6-15, 6-21 to 6-22 writing data 6-29

DDS_BuiltinTopicReaderResourceLimits_t 8-36 DDS_DATAREADER_QOS_DEFAULT 7-19 DDS_DATAREADER_QOS_USE_TOPIC 7-36 DDS_DataReaderQos structure 7-32 DDS_DATAWRITER_QOS_USE_TOPIC_QOS 6-51 DDS_ReliableWriterCacheEventCount 6-27 DDS_RtpsReliableReaderProtocol_t 7-51 DDS_RtpsReliableWriterProtocol_t 6-81 DDS_SubscriberQos structure 7-8 DDS_TransportMulticastSetting_t 7-63

deadline

status for missing 6-25, 7-28 Deadline QoS 6-91

interaction with TimeBasedFilter QoS 7-61 delete_contained_entities() 6-7, 7-7, 7-21, 8-12 depth (History QoS) 6-100

destination timestamp 6-93 DestinationOrder QoS 6-93 direct_communication (Durability QoS) 6-96

Index-1

disable_fragmentation_support(DataReaderResourceLimits QoS) 7-55

disable_positive_acks (DataReaderProtocol QoS) 7-51 disable_positive_acks (DataWriterProtocol QoS) 6-80 disable_positive_acks_decrease_sample_keep_duration_fac

tor (RtpsReliableWriterProtocol_t) 6-83 disable_positive_acks_enable_adaptive_sample_keep_dura

tion (RtpsReliableWriterProtocol_t) 6-83 disable_positive_acks_increase_sample_keep_duration_fact

or (RtpsReliableWriterProtocol_t) 6-83 disable_positive_acks_max_sample_keep_duration

(RtpsReliableWriterProtocol_t) 6-83 disable_positive_acks_min_sample_keep_duration

(RtpsReliableWriterProtocol_t) 6-83 Discovery

accessing Topics 8-22

finding remote DomainParticipants 8-22 discovery

ports used 8-53 Discovery QoS 8-29 DiscoveryConfig QoS 8-33 dispose() 6-43, 6-131

vs. unregister_instance() 6-42 disposed_generation_count (DDS_SampleInfo) 7-46, 7-48 domain ID 8-13, 8-51

DomainParticipantFactory example code 8-3 operations on 8-3 purpose of 8-3

QoS for 8-4, 8-6

DomainParticipantResourceLimits QoS 8-40 DomainParticipants

accessing discovered 8-22 creating 8-11

definition 8-1, 8-7 deleting 8-12 discovery of 8-35 domain IDs 8-13, 8-51

example code 6-6, 6-47, 7-34, 8-12, 8-14, 8-17

Listener of last resort 6-13, 7-14 Listeners for 8-13

operations on 8-7 QoS for 8-15

domains definition 8-1 multiple 8-1

vs. partitions 6-62 dropped samples status 7-29 Durability QoS 6-95, 6-97

durable subscriptions 6-39 to 6-40, 6-73 dynamic memory 8-44

dynamically_allocate_fragmented_samples(DataReaderRes ourceLimits QoS) 7-56

E

enable() 4-3

enabled_transports 6-124, 8-29 to 8-30 enabling entities 6-56

recursiveness 4-3 end_coherent_changes() 6-33, 6-68 EntityFactory QoS 4-3, 6-56 evaluate 5-28

Event QoS 8-45

ExclusiveArea QoS 6-54, 6-58, 6-115 when to change 6-58

expects_inline_qos (DataReaderProtocol QoS) 7-51 expression parameters 5-14

external clock 8-56

F

factory class 4-2

fast_heartbeat_period (RtpsReliableWriterProtocol_t) 6-81 filter expression syntax 5-16

filter expressions 5-11, 5-14

finalize 5-28 finalize_instance() 8-6 finalizeX() 3-39 find_topic() 8-20 FlowControllers

creating and deleting 6-140 external trigger 6-142

flushing batched samples 6-32, 6-54, 6-76 to 6-77 FooDataReader

definition 7-38 operations on 7-17 to 7-18

FooDataWriter definition 6-29 operations on 6-16

FooSeq 7-45

G

generating code See rtiddsgen.

generation_rank (DDS_SampleInfo) 7-46, 7-48 to 7-49 get_datareader_cache_status() 7-22 get_datareader_protocol_status() 7-22 get_datareaders() 7-15

get_datawriter_cache_status() 6-21 get_datawriter_protocol_status() 6-21 get_deadline_missed_status() 6-25 get_default_datawriter_qos() 6-12, 7-12 get_discovered_participant_data() 8-22 get_discovered_participants() 8-22 get_discovered_topic_data() 8-22 get_discovered_topics() 8-22 get_domain_id() 8-13 get_instance_handle() 4-4, 8-22 get_key_value() 6-43, 7-37 get_listener() 4-5

get_liveliness_changed_status() 7-22, 7-28 get_liveliness_lost_status() 6-21, 6-25 get_matched_publication_data() 7-36 get_matched_publication_datareader_protocol_status() 7-

22

get_matched_publications() 7-36 to 7-37 get_matched_subscription_data() 6-52 get_matched_subscription_datawriter_protocol_status_by_

locator() 6-21 get_matched_subscription_datawriter_protocol_status() 6-

21 get_matched_subscription_locators() 6-52 get_matched_subscriptions() 6-52

get_offered_deadline_missed_status() 6-21 get_offered_incompatible_qos_status() 6-21, 6-26 get_participant() 6-14, 7-15 get_publication_match_status() 6-21

get_qos() 4-6, 6-46 get_reliable_reader_activity_changed_status() 6-21 get_reliable_writer_cache_changed_status() 6-21 get_requested_deadline_missed_status() 7-23, 7-28 get_requested_incompatible_qos_status() 7-23, 7-29 get_sample_lost_status() 7-22, 7-30 get_sample_rejected_status() 7-23, 7-31 get_status_changes() 4-5, 4-13 to 4-14, 6-21, 7-23 get_statuscondition() 4-34, 7-23 get_subscription_match_status() 7-23, 7-31 get_trigger_value() 4-26

getting data 7-2 to 7-3, 7-21, 7-24, 7-38, 7-45

GroupData QoS 6-59

GUID (Globally Unique ID) 6-110, 8-53

H

hash table 3-56, 6-81, 6-121, 8-41, 8-43

heartbeat_period (RtpsReliableWriterProtocol_t) 6-81, 6-84 heartbeat_suppression_duration

(DDS_RtpsReliableReaderProtocol_t) 7-52 heartbeats

response delays 7-52

Index-2

heartbeats_per_max_samples (RtpsReliableWriterProtocol_t) 6-82

high_watermark (RtpsReliableWriterProtocol_t) 6-81 historical data 6-95, 7-23

History QoS 6-100

effect of ResourceLimits QoS 6-101 history_depth (DurabilityService QoS) 6-98 history_kind (DurabilityService QoS) 6-98 host ID 8-52

I

IDL 3-37

including other files 3-55 supported types 3-41, 3-45, 3-48 unsupported types 3-38

ignore_publication() 7-37 ignore_publisher() 6-60, 6-129 ignore_subscription() 6-53 ignore_topic() 8-22

implicit Publishers 6-5, 7-6 inactivate_nonprogressing_readers

(RtpsReliableWriterProtocol_t) 6-82 incompatible QoS

status for 6-26 info units 7-54

initial and maximum values in QoS 7-57, 7-59 initial_batches (DataWriterResouceLimits QoS) 6-89 initial_concurrent_blocking_threads

(DataWriterResourceLimits QoS) 6-89 initial_fragmented_samples(DataReaderResourceLimits

QoS) 7-55

initial_infos (DataReaderResourceLimits QoS) 7-54 initial_instances (ResourceLimits QoS) 6-121 initial_outstanding_reads (DataReaderResourceLimits

QoS) 7-55

initial_participant_announcements (DiscoveryConfig QoS) 8-33

initial_peers 8-29 adding to 8-30 initial_records 8-27

initial_remote_virtual_writers (DataReaderResourceLimits QoS) 7-56

initial_remote_virtual_writers_per_instance(DataReaderRe sourceLimits QoS) 7-56

initial_remote_writers (DataReaderResourceLimits QoS) 7- 54

initial_remote_writers_per_instance (DataReaderResourceLimits QoS) 7-54

initial_samples (ResourceLimits QoS) 6-121 initial_virtual_writers (DataWriterResouceLimits QoS) 6-

89 initial_weak_references 8-28 instance handle 4-4 instance ID 8-52

instance state 7-47

interaction with Ownership QoS 7-47 instance states 6-43

instance_handle (DDS_SampleInfo) 7-46 instance_hash_buckets (ResourceLimits QoS) 6-121 instance_replacement (DataWriterResouceLimits QoS) 6-89 instance_state (DDS_SampleInfo) 7-46

instances registration 6-41

registration example 6-42

Interface Description Language. See IDL internal clock 8-56

K

keep duration 6-85

key hash 3-56, 6-81, 6-121, 8-41, 8-43 keys

definition 6-41 getting value of 6-43 in IDL file 3-56

managing data instances 6-41 registering instances 6-41 rtiddsgen 3-56

L

last_reason (SAMPLE_REJECTED status) 7-30 late_joiner_heartbeat_period

(RtpsReliableWriterProtocol_t) 6-81 latency 7-54

lease_duration (Liveliness QoS) 6-104 LENGTH_UNLIMITED 8-28 Listeners

basic steps 7-2

creating and deleting 4-20 definition 6-13

example code 6-14, 7-14, 7-22, 8-14 for DataReaders 7-21

for DataWriters 6-20

for DomainParticipants 8-13 for Publishers 6-13

for Topics 5-7

last resort 6-13, 7-14, 8-13 operations allowed in 4-22 precedence of 6-13, 6-20, 7-14 purpose of 4-13

relationship of PublisherListener and DataWriterListener 6-13

removing 8-14 listening for data 7-2

liveliness assertion during write() 6-31 LIVELINESS_CHANGED status 6-28, 7-27 LIVELINESS_LOST status 6-25

locators (TransportUnicast QoS) 6-126 long double 3-53 to 3-54 lookup_datareader() 6-14, 7-15 lookup_instance() 6-43, 7-37 lookup_participant() 8-6 lookup_topicdescription() 8-20 to 8-21 lost samples 7-29

low_watermark (RtpsReliableWriterProtocol_t) 6-81 low-bandwidth connections 7-62

M

matching writers and readers 6-26, 6-52, 7-27, 7-36 status for 7-31

max_batches (DataWriterResouceLimits QoS) 6-89 max_blocking_time (Reliability QoS) 6-90, 6-118 max_bytes_per_nack_response

(RtpsReliableWriterProtocol_t) 6-83 max_concurrent_blocking_threads

(DataWriterResourceLimits QoS) 6-89 max_data_bytes (Batch QoS) 6-75 max_flush_delay (Batch QoS) 6-75

max_fragmented_samples_per_remote_writer(DataReader ResourceLimits QoS) 7-55

max_fragmented_samples(DataReaderResourceLimits QoS) 7-55

max_fragments_per_sample(DataReaderResourceLimits QoS) 7-55

max_heartbeat_response_delay (RtpsReliableReaderProtocol_t) 7-52

max_heartbeat_response_delay(DDS_RtpsReliableReaderP rotocol_t) 7-52

max_heartbeat_retries (RtpsReliableWriterProtocol_t) 6-82 max_infos (DataReaderResourceLimits QoS) 7-54 max_instances (DurabilityService QoS) 6-98 max_instances (ResourceLimits QoS) 6-121, 7-58 max_liveliness_loss_detection_period (DiscoveryConfig

QoS) 8-33 max_nack_response_delay

(RtpsReliableWriterProtocol_t) 6-82 max_outstanding_reads (DataReaderResourceLimits

QoS) 7-55

Index-3

max_query_condition_filters (DataReaderResourceLimits QoS) 7-57

max_remote_reader_filters (DataWriterResouceLimits QoS) 6-89

max_remote_virtual_writers DataReaderResourceLimits QoS) 7-56

max_remote_virtual_writers_per_instance(DataReaderReso urceLimits QoS) 7-56

max_remote_writers (DataReaderResourceLimits QoS) 7- 54

max_remote_writers_ per_sample (DataReaderResourceLimits QoS) 7-57

max_remote_writers_per_instance (DataReaderResourceLimits QoS) 7-54, 7-57

max_samples (Batch QoS) 6-75 max_samples (DurabilityService QoS) 6-98

max_samples (ResourceLimits QoS) 6-27, 6-121 max_samples_per_instance (DurabilityService QoS) 6-98 max_samples_per_instance (ResourceLimits QoS) 6-121 max_samples_per_read(DataReaderResourceLimits

QoS) 7-55 max_samples_per_remote_writer

(DataReaderResourceLimits QoS) 7-54, 7-57 to 7-58 max_send_window_size (RtpsReliableWriterProtocol_t) 6-

83 max_skiplist_level 8-28

max_total_instances (DataReaderResourceLimits QoS) 7- 56, 7-58

max_virtual_writers (DataWriterResouceLimits QoS) 6-89 max_weak_references 8-28

maximizing throughput 7-54 memory

allocation 3-39, 7-54, 7-59, 8-43 clearing 6-12, 7-12

copying 7-12 returning 8-6 meta-traffic 8-30

metatraffic_transport_priority 8-30 to 8-31 min_heartbeat_response_delay

(RtpsReliableReaderProtocol_t) 7-52 min_nack_response_delay

(RtpsReliableWriterProtocol_t) 6-82 min_send_window_size (RtpsReliableWriterProtocol_t) 6-

83

minimizing latency 7-54 minimum_separation

reasons for changing 7-62

minimum_separation (TimeBasedFilter QoS) 7-61 to 7-62 missed deadline status 6-25, 7-28

missing samples status 7-29 module (IDL type) 3-44, 3-47, 3-53 monotonic clock 8-56

multicast

addresses 7-63, 8-31 example code 7-64 locators 7-63

ports 7-63 TransportMulticast QoS 7-62

multicast_receive_addresses 8-30 to 8-31

N

nack_period (DDS_RtpsReliableReaderProtocol_t) 7-52 nack_suppression_duration

(RtpsReliableWriterProtocol_t) 6-83 namespace (rtiddsgen option) 3-82 NEW view state 7-47

new_remote_participant_announcement_period (DiscoveryConfig QoS) 8-34

no_writers_generation_count (DDS_SampleInfo) 7-46, 7-48 NOT_ALIVE_DISPOSED instance state 7-47 NOT_ALIVE_NO_WRITERS instance state 6-43, 7-47 NOT_NEW view state 7-47

NOT_READ sample state 7-47 notification of new data 7-21

O

offered QoS 6-46 OFFERED_DEADLINE_MISSED status 6-25 OFFERED_INCOMPATIBLE_QOS status 6-26 on_data_available() 7-21, 7-24 on_data_on_readers() 7-16 on_instance_replaced() 6-21 on_liveliness_changed() 7-21, 7-27 on_liveliness_lost() 6-21, 6-25 on_offered_deadline_missed() 6-21, 6-25

example 6-14 on_offered_incompatible_qos() 6-21, 6-26 on_publication_matched() 6-21 on_reliable_reader_activity_changed() 6-21 on_reliable_writer_cache_changed() 6-21 on_requested_deadline_missed() 7-21, 7-28 on_requested_incompatible_qos() 7-21, 7-29 on_sample_lost() 7-21, 7-30 on_sample_rejected() 7-21, 7-31 on_subscription_matched() 7-21, 7-31 order of samples 6-93

ordered_access (Presentation QoS) 6-67 effect of 6-69

original_publication_virtual_guid (DDS_SampleInfo) 7-46 original_publication_virtual_sequence_number

(DDS_SampleInfo) 7-46 ownership of data 7-39

effect of unregistering 6-42 Ownership QoS

effect of sharing 7-58 effect on instance state 7-47 preventing starvation 7-58

OwnershipStrength QoS 6-112

P

participant ID 8-51 to 8-52 participant_id (WireProtocol QoS) 8-51

participant_liveliness_assert_period (DiscoveryConfig QoS) 8-33

participant_liveliness_assert_period (DisocveryConfig QoS) 8-35, 8-39

participant_liveliness_lease_duration (DiscoveryConfig QoS) 8-33

participant_message_reader (DiscoveryConfig QoS) 8-35 participant_message_writer (DiscoveryConfig QoS) 8-35 Partition QoS 6-62

example 6-64

example of changing 6-65 impact on memory 6-66

partitions definition 6-62

rules for matching names 6-63 vs. domains 6-62

wildcards 6-63 peers list

adding to 8-30 performance

improving with registration 6-41 period (Deadline QoS) 6-91

plain communication status 4-14, 7-16 plugin_data 6-128

pointer (IDL type) 3-42, 3-49 polling for data 7-2 to 7-3 port numbers 8-51

ports 8-53

preprocessor directives 3-55, 3-83 Presentation QoS 6-67 preventing starvation 7-58 prioritized samples 6-136 promiscuous mode 7-65

propagate_dispose_of_unregistered_instances (DataReaderProtocol QoS) 7-51

Property QoS 6-112, 8-24 publication_handle (DDS_SampleInfo) 7-46 PUBLICATION_MATCHED status 6-26

Index-4

publication_reader_ resource_limits 8-34 publication_squence_number (DDS_SampleInfo) 7-46 publication_writer (DiscoveryConfig QoS) 8-34 publication_writer_data_lifecycle (DiscoveryConfig

QoS) 8-34

publication_writer_publish_mode (DiscoveryConfig QoS) 8-35

Publishers creating 6-5 definition 6-2

deleting 6-7, 8-12 example Listener 6-14 implicit 6-5, 7-6

Listener’s relationship to DataWriters’ Listener 6-13 Listeners for 6-13

operations on 5-14, 6-4, 6-133 QoS for 6-7, 6-53

setting QoS for 6-7 pulled samples 6-22

push_on_write (DataWriterProtocol QoS) 6-80 when to change 6-87

pushed samples 6-22

Q

QoS

compatibility 6-26, 6-46, 7-33

Database 8-27 DataReaderProtocol 7-50 DataReaderResourceLimits 7-54 DataReaders 7-32 DataWriterProtocol 6-79 DataWriterResourceLimits 6-89 Deadline 6-91 DestinationOrder 6-93 Discovery 8-29 DiscoveryConfig 8-33

DomainParticipantResourceLimits 8-40 Durability 6-95, 6-97

EntityFactory 6-56 Event 8-45

ExclusiveArea 6-54, 6-58, 6-115 for DataWriters 6-43, 6-71

for DomainParticipantFactory 8-4, 8-6 for DomainParticipants 8-15

for Publishers 6-53 for Topics 5-8 GroupData 6-59 History 6-100 how to set 4-6 offered 6-46

OwnershipStrength 6-112 Partition 6-62

Property 6-112, 8-24

Publishers 6-7 ReceiverPool 8-46 Reliability 6-117 requested 6-46 ResourceLimits 6-120 rules for setting 4-6 Subscribers 7-8, 7-49 summary table 4-9 TimeBasedFilter 7-60 TransportBuiltin 8-48 TransportMulticast 7-62 TransportPriority 6-123 TransportSelection 6-124 TransportUnicast 6-125 UserData 6-128

using defaults 7-19 using Topic’s 7-36 WireProtocol 8-51

QoS. See Also individual QoS policy names.

R

read communication status 4-14, 7-16, 7-24 READ sample state 7-47

read_instance() 7-37, 7-42 to 7-44 read_next_instance() 7-42 read_next_sample() 7-41

read() vs. take() 7-39 reading data 7-38 realtime clock 8-56 receive queue

size 6-121 receive thread 8-46

receive_address (DDS_TransportMulticastSetting_t) 7-63 receive_port (DDS_TransportMulticastSetting_t) 7-63 receive_port (TransportUnicast QoS) 6-126 receive_window_size

(DDS_RtpsReliableReaderProtocol_t) 7-52 ReceiverPool QoS 8-46

receiving data 7-21, 7-24, 7-38, 7-45 basic steps 7-2 to 7-3

reception_timestamp (DDS_SampleInfo) 7-46 refilter (History QoS) 6-100 register_instance() 6-41, 6-43

rejected samples 7-29 to 7-30 Reliability QoS 6-117

effect on bandwidth 6-120 reliable delivery 6-117

RELIABLE_READER_ACTIVITY_CHANGED status 6-28 RELIABLE_WRITER_CACHE_CHANGED status 6-27 remote_participant_purge_kind (DiscoveryConfig QoS) 8-

33

replace_empty_instances (DataWriterResouceLimits QoS) 6-89

requested QoS 6-46 REQUESTED_DEADLINE_MISSED status 7-28 REQUESTED_INCOMPATIBLE_QOS status 7-28 required subscriptions 6-39 to 6-40

resource configuration 7-54 resource limits 7-54 ResourceLimits QoS 6-120

effect on History QoS 6-101 response delays 7-52

round_trip_time (DDS_RtpsReliableReaderProtocol_t) 7-52 rtiddsgen

@copy directive 3-57 @key directive 3-56

@resolve-name directive 3-58 @top-level directive 3-60 command-line options 3-80 directives 3-55

generated files 3-78 to 3-79

IDL conversions 3-41, 3-45, 3-48 including IDL files 3-55 support types 3-41, 3-45, 3-48 syntax 3-80

RTPS protocol 8-51

rtps_app_id (WireProtocol QoS) 8-51 rtps_auto_id_kind (WireProtocol QoS) 8-51 rtps_host_id (WireProtocol QoS) 8-51 rtps_instance_id (WireProtocol QoS) 8-51 rtps_object_id (DataReaderProtocol QoS) 7-50 rtps_object_id (DataWriterProtocol QoS) 6-80 rtps_reliable_reader (DataReaderProtocol QoS) 7-51 rtps_reliable_writer (DataWriterProtocol QoS) 6-81 rtps_reserved_ports_mask (WireProtocol QoS) 8-51 rtps_well_known_ports (WireProtocol QoS) 8-51

RxO 6-46

S

sample state 7-47 SAMPLE_LOST status 7-29

sample_rank (DDS_SampleInfo) 7-48 to 7-49 sample_rank (SampleInfo) 7-46 SAMPLE_REJECTED status

reason codes 7-29 to 7-30

Index-5

sample_state (DDS_SampleInfo) 7-46 SampleInfo structure 7-46

samples

coherent sets 6-32 count of lost 7-29

how many per DataWriter 7-57 lost 7-29

notification of arrival 7-24 order of delivery 6-93 ownership of data 7-39

reasons for rejection 7-29 to 7-30 saving for later use 6-95 structure of 7-46 unacknowledged 6-27

writing 6-29 samples_per_app_ack

(DDS_RtpsReliableReaderProtocol_t) 7-52 samples_per_virtual_heartbeat

RtpsReliableWriterProtocol_t) 6-81 send queue

size 6-100, 6-121 unblocking when full 6-90

send_window_decrease_factor (RtpsReliableWriterProtocol_t) 6-83

send_window_increase_factor (RtpsReliableWriterProtocol_t) 6-84

send_window_update_period (RtpsReliableWriterProtocol_t) 6-84

sending data. See writing data. sequence data type 3-39, 7-45 sequence number 7-46 sequences (defined) 7-45

service_cleanup_delay (DurabilityService QoS) 6-98 set_default_datawriter_qos() 4-7 set_enabled_statuses() 4-34

set_listener() 4-5 set_qos() 4-6, 6-46 shared ownership

effect of max_samples_per_remote_writer 7-58 shutdown_cleanup_period 8-27 shutdown_timeout 8-27

skip list 8-28

source timestamp 6-93

source_timestamp (DDS_SampleInfo) 7-46 source_timestamp_resolution (Batch QoS) 6-76 SQL syntax 5-16

starvation 7-58

static memory allocation 8-44 status changes 7-23

statuses

changes in 4-14 DATA_AVAILABLE 4-14, 7-16, 7-24 DATA_ON_READERS 4-14, 7-16 DATA_READER_CACHE 7-24 DATA_READER_PROTOCOL 7-24 DATA_WRITER_CACHE 6-22 DATA_WRITER_PROTOCOL 6-22 for DataReaders 7-22 to 7-23

for DataWriters 6-15, 6-21 to 6-22 for Subscribers 7-16 LIVELINESS_CHANGED 7-27 LIVELINESS_LOST 6-25

OFFERED_DEADLINE_MISSED 6-25

OFFERED_INCOMPATIBLE_QOS 6-26 plain communication status 4-14 PUBLICATION_MATCHED 6-26

read communication status 4-14 RELIABLE_READER_ACTIVITY_CHANGED 6-28 RELIABLE_WRITER_CACHE_CHANGED 6-27 REQUESTED_DEADLINE_MISSED 7-28 REQUESTED_INCOMPATIBLE_QOS 7-28 SAMPLE_LOST 7-29 SUBSCRIPTION_MATCHED 7-31

string data type 3-4 Subscribers

creating 7-6

definition 7-3 operations on 7-5

QoS for 7-8, 7-49 statuses for 7-16

SUBSCRIPTION_MATCHED status 7-31 subscription_reader (DiscoveryConfig QoS) 8-34 subscription_reader_resource_limits (DiscoveryConfig

QoS) 8-34

subscription_writer (DiscoveryConfig QoS) 8-34 subscription_writer_data_lifecycle (DiscoveryConfig

QoS) 8-35 subscriptions

notification timing 7-61 supported data types 3-3, 3-6

T

take_instance() 7-37 take() vs. read() 7-39 taking data 7-38

thread_safe_write (Batch QoS) 6-76 threads 6-89

receive 8-46

shared/exclusive areas for 6-54, 6-58, 6-115 unblocking 6-90

throughput 7-54 TimeBasedFilter QoS 7-60

interaction with Deadline QoS 7-61 timestamp 6-29, 6-93

timestamp resolution 6-76, 6-78 timestamp tolerance 6-93 timestamps 8-56

topic_name definition 5-3

Topics

accessing discovered 8-22 copying QoS 6-12, 7-12 creating 5-3

example code 6-9, 6-47 to 6-48, 7-9, 7-35, 8-17 to 8-18

Listeners for 5-7 operations on 5-2 purpose of 5-1 purpose of QoS 5-8

QoS for 5-5, 5-8 waiting for creation 8-20

TRANSIENT_LOCAL (Durability QoS) 6-95 to 6-96 transport plug-ins

for meta-traffic 8-30 TransportBuiltin QoS 8-48 TransportMulticast QoS 7-62 TransportPriority QoS 6-123

transports (TransportMulticast QoS) 7-63 transports (TransportUnicast QoS) 6-126 TransportSelection QoS 6-124 TransportUnicast QoS 6-125 trigger_value 4-26, 4-34 type_code_max_serialized_length

(DomainParticipantsResourceLimits QoS) 8-43 type_name

definition 5-3 typedef construct 3-54

U

unacknowledged samples 6-27 unicast 6-125 unregister_instance() 6-42

vs. dispose() 6-42 unregister() 6-131 unregistering instances

instance ownership after 6-42 unsigned types 3-54

use_shared_exclusive_area (ExclusiveArea QoS) 6-58 user data types

definition 3-3

See also data types.

Index-6

UserData QoS 6-128

V

valid_data (DDS_SampleInfo) 7-46 view state 7-47

view_state (DDS_SampleInfo) 7-46 virtual GUID 7-46

virtual heartbeats 6-81, 6-87 virtual sequence number 7-46 virtual writers 6-89, 7-31, 7-56

virtual_guid (DataReaderProtocol QoS) 7-50 virtual_guid (DataWriterProtocol QoS) 6-80

virtual_heartbeat_period (RtpsReliableWriterProtocol_t) 6- 81

VOLATILE (Durability QoS) 6-95 to 6-96

W

wait_for_acknowledgments() 6-15, 6-33 wait_for_historical_data() 7-23

waiting for data 7-2 WaitSets 4-26

creating and deleting 4-26 example code 4-30 operations on 4-28 properties for 4-26 purpose of 4-26

wchar 3-54

weak references 8-28 well_known_ports 8-53 wildcard partition names 6-63 WireProtocol QoS 8-51 write_w_timestamp() 6-29 writer_attach 5-29 writer_detach 5-29

writing data 6-29 basic steps 6-1

example with registration 6-42 liveliness assertion 6-31 registration of instance 6-41

Index-7