Available Documentation

To get you up and running as quickly as possible, we have divided the RTI® Connext™ (formerly, RTI Data Distribution Service) documentation into several parts.

❏Getting Started Guide (RTI_CoreLibrariesAndUtilities_GettingStarted.pdf)—This document describes how to install Connext. It also lays out the core value and concepts behind the product and takes you step-by-step through the creation of a simple example application. Developers should read this document first.

If you want to use the Connext Extensible Types feature, please read:

• Addendum for Extensible Types (RTI_CoreLibrariesAndUtilities_GettingStarted _ExtensibleTypesAddendum.pdf) Extensible Types allow you to define data types in a more flexible way. Your data types can evolve over time—without giving up portability, interoperability, or the expressiveness of the DDS type system.

If you are using Connext on an embedded platform or with a database, you will find additional documents that specifically address these configurations:

•Getting Started Guide Addendum for Embedded Systems (RTI_CoreLibrariesAndUtilities_GettingStarted _EmbeddedSystemsAddendum.pdf)

•Addendum for Database Setup (RTI_CoreLibrariesAndUtilities_GettingStarted _DatabaseAddendum.pdf).

❏What’s New (RTI_CoreLibrariesAndUtilities_WhatsNew.pdf)—This document describes changes and enhancements in the current version of Connext. Those upgrading from a previous version should read this document first.

❏Release Notes and Platform Notes (RTI_CoreLibrariesAndUtilities_ReleaseNotes.pdf and RTI_CoreLibrariesAndUtilities_PlatformNotes.pdf)—These documents provide system requirements, compatibility, and other platform-specific information about the product, including specific information required to build your applications using RTI, such as compiler flags and libraries.

❏Core Libraries and Utilities User’s Manual (RTI_CoreLibrariesAndUtilities _UsersManual_[1-4].pdf)—This multi-part document describes the features of the product and how to use them. It is organized around the structure of the Connext APIs and certain common high-level tasks.

❏API Reference Documentation (ReadMe.html, RTI_CoreLibrariesAndUtilities _ApiReference<Language>.pdf)—This extensively cross-referenced documentation, available both in HTML and printable PDF formats for all supported programming languages, is your in-depth reference to every operation and configuration parameter in the middleware. Even experienced Connext developers will often consult this information.

iii

The Programming How To's provide a good place to begin learning the APIs. These are hyperlinked code snippets to the full API documentation. From the ReadMe.html file, select one of the supported programming languages, then scroll down to the Programming How To’s. Start by reviewing the Publication Example and Subscription Example, which provide step-by step examples of how to send and receive data with

Connext.

Many readers will also want to look at additional documentation available online. In particular, RTI recommends the following:

❏The RTI Customer Portal, https://support.rti.com, provides access to RTI software, documentation, and support. It also allows you to log support cases. Furthermore, the portal provides detailed solutions and a free public knowledge base. To access the software, documentation or log support cases, the RTI Customer Portal requires a username and password. You will receive this in the email confirming your purchase. If you do not have this email, please contact license@rti.com. Resetting your login password can be done directly at the RTI Customer Portal.

❏Examples—Accessible from http://www.rti.com/examples. This page contains example code snippets on how to use individual features, examples illustrating specific use cases, as well as:

•Example Performance Test (available for C++, Java and .NET1)—This example application includes code and configuration files for testing and optimizing the performance of a simple Connext application on your system. The program will test both throughput and latency under a wide variety of middleware configurations. It also includes documentation on tuning the middleware and the underlying operating system. You can also review the data from several performance benchmarks here: http://www.rti.com/products/dds/benchmarks-cpp-linux.html.

❏Whitepapers and other articles—Available from http://www.rti.com/resources/.

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

iv

Contents, Part 1

		Available Documentation	iii
		Welcome to RTI Connext	vi
		Conventions	vi
		Extensions to the DDS Standard	vi
		Environment Variables	vi
		Names of Supported Platforms	vi
		Additional Resources	vii
1	Overview		1-1
	1.1	What is Connext?	1-1
	1.2	What is Middleware?	1-2
	1.3	Network Communications Models	1-2
	1.4	Features of Connext	1-4
2	Data-Centric Publish-Subscribe Communications		2-1
	2.1	What is DCPS?	2-1
		2.1.1 DCPS for Real-Time Requirements	2-2
	2.2	Data Types, Topics, Keys, Instances, and Samples	2-3
		2.2.1 Data Topics — What is the Data Called?	2-3
		2.2.2 Samples, Instances, and Keys	2-4
	2.3	DataWriters/Publishers and DataReaders/Subscribers	2-5
	2.4	Domains and DomainParticipants	2-7
	2.5	Quality of Service (QoS)	2-8
		2.5.1 Controlling Behavior with Quality of Service (QoS) Policies	2-8
	2.6	Application Discovery	2-9

v

Welcome to RTI Connext

RTI Connext solutions provide a flexible data distribution infrastructure for integrating data sources of all types. At its core is the world's leading ultra-high performance, distributed networking DataBus™. It connects data within applications as well as across devices, systems and networks. Connext also delivers large data sets with microsecond performance and granular quality-of-service control. Connext is a standards-based, open architecture that connects devices from deeply embedded real-time platforms to enterprise servers across a variety of networks.

Conventions

The terminology and example code in this manual assume you are using C++ without namespace support.

C, C++/CLI, C#, and Java APIs are also available; they are fully described in the API Reference HTML documentation.

Namespace support in C++, C++/CLI, and C# is also available; see the API Reference HTML documentation (from the Modules page, select Using DDS:: Namespace) for details.

Extensions to the DDS Standard

Connext implements the DDS Standard published by the OMG. It also includes features that are extensions to DDS. These include additional Quality of Service parameters, function calls, structure fields, etc.

Extensions also include product-specific APIs that complement the DDS API. These include APIs to create and use transport plug-ins, and APIs to control the verbosity and logging capabilities. These APIs are prefixed with NDDS, such as

NDDSTransportSupport::register_transport().

Environment Variables

Connext documentation refers to pathnames that have been customized during installation. NDDSHOME refers to the installation directory of Connext.

Names of Supported Platforms

Connext runs on several different target platforms. To support this vast array of platforms, Connext separates the executable, library, and object files for each platform into individual directories.

vi

Each platform name has four parts: hardware architecture, operating system, operating system version and compiler. For example, i86Linux2.4gcc3.2 is the directory that contains files specific to Linux® version 2.4 for the Intel processor, compiled with gcc version 3.2.

For a full list of supported platforms, see the Platform Notes.

Additional Resources

The details of each API (such as function parameters, return values, etc.) and examples are in the API Reference HTML documentation. In case of discrepancies between the information in this document and the API Reference HTML documentation, the latter should be considered more up-to-date.

vii

Chapter 1 Overview

RTI Connext (formerly, RTI Data Distribution Service) is network middleware for distributed real- time applications. Connext simplifies application development, deployment and maintenance and provides fast, predictable distribution of time-critical data over a variety of transport networks.

With Connext, you can:

❏Perform complex one-to-many and many-to-many network communications.

❏Customize application operation to meet various real-time, reliability, and quality-of- service goals.

❏Provide application-transparent fault tolerance and application robustness.

❏Use a variety of transports.

This chapter introduces basic concepts of middleware and common communication models, and describes how Connext’s feature-set addresses the needs of real-time systems.

1.1What is Connext?

Connext is network middleware for real-time distributed applications. It provides the communications service programmers need to distribute time-critical data between embedded and/or enterprise devices or nodes. Connext uses the publish-subscribe communications model to make data distribution efficient and robust.

Connext implements the Data-Centric Publish-Subscribe (DCPS) API within the OMG’s Data Distribution Service (DDS) for Real-Time Systems. DDS is the first standard developed for the needs of real-time systems. DCPS provides an efficient way to transfer data in a distributed system.

With Connext, systems designers and programmers start with a fault-tolerant and flexible communications infrastructure that will work over a wide variety of computer hardware, operating systems, languages, and networking transport protocols. Connext is highly configurable so programmers can adapt it to meet the application’s specific communication requirements.

1-1

1.2What is Middleware?

Middleware is a software layer between an application and the operating system. Network middleware isolates the application from the details of the underlying computer architecture, operating system and network stack (see Figure 1.1). Network middleware simplifies the development of distributed systems by allowing applications to send and receive information without having to program using lower-level protocols such as sockets and TCP or UDP/IP.

Figure 1.1 Network Middleware

Connext is middleware that insulates applications from the raw operating-system network stack.

Publish-subscribe middleware Connext is based on a publish-subscribe communications model. Publish-subscribe (PS) middleware provides a simple and intuitive way to distribute data. It decouples the software that creates and sends data—the data publishers—from the software that receives and uses the data—the data subscribers. Publishers simply declare their intent to send and then publish the data. Subscribers declare their intent to receive, then the data is automatically delivered by the middleware.

Despite the simplicity of the model, PS middleware can handle complex patterns of information flow. The use of PS middleware results in simpler, more modular distributed applications. Perhaps most importantly, PS middleware can automatically handle all network chores, including connections, failures, and network changes, eliminating the need for user applications to program of all those special cases. What experienced network middleware developers know is that handling special cases accounts for over 80% of the effort and code.

1.3Network Communications Models

The communications model underlying the network middleware is the most important factor in how applications communicate. The communications model impacts the performance, the ease to accomplish different communication transactions, the nature of detecting errors, and the robustness to different error conditions. Unfortunately, there is no “one size fits all” approach to distributed applications. Different communications models are better suited to handle different classes of application domains.

This section describes three main types of network communications models:

❏Point-to-point

❏Client-server

❏Publish-subscribe

1-2

Point-to-point model Point-to-point is the simplest form of communication, as illustrated in Figure 1.2. The telephone is an example of an everyday point-to-point communications device. To use a telephone, you must know the address (phone number) of the other party. Once a connection is established, you can have a reasonably high-bandwidth conversation. However, the telephone does not work as well if you have to talk to many people at the same time. The telephone is essentially one-to-one communication.

TCP is a point-to-point network protocol designed in the 1970s. While it provides reliable, high- bandwidth communication, TCP is cumbersome for systems with many communicating nodes.

Figure 1.2 Point-to-Point

A

B

Point-to-point is one-to-one communications.

Client-server model To address the scalability issues of the Point-to-Point model, developers turned to the Client-Server model. Client-server networks designate one special server node that connects simultaneously to many client nodes, as illustrated in Figure 1.3. Client-server is a "many-to-one" architecture. Ordering pizza over the phone is an example of client-server communication. Clients must know the phone number of the pizza parlor to place an order. The parlor can handle many orders without knowing ahead of time where people (clients) are located. After the order (request), the parlor asks the client where the response (pizza) should be sent. In the client-server model, each response is tied to a prior request. As a result, the response can be tailored to each request. In other words, each client makes a request (order) and each reply (pizza) is made for one specific client in mind.

The client-server network architecture works best when information is centralized, such as in databases, transaction processing systems, and file servers. However, if information is being generated at multiple nodes, a client-server architecture requires that all information are sent to the server for later redistribution to the clients. This approach is inefficient and precludes deterministic communications, since the client does not know when new information is available. The time between when the information is available on the server, and when the client asks and receives it adds a variable latency to the system.

Figure 1.3 Client-Server

Server

Client

Client

request

reply

Client

Client

Client-server is many-to-one communications.

Publish-subscribe model In the publish-subscribe communications model, computer applications (nodes) “subscribe” to data they need and “publish” data they want to share. Messages pass directly between the publisher and the subscribers, rather than moving into and out of a centralized server. Most time-sensitive information intended to reach many people is sent by a publish-subscribe system. Examples of publish-subscribe systems in everyday life include television, magazines, and newspapers.

1-3

Publish-subscribe communication architectures are good for distributing large quantities of time-sensitive information efficiently, even in the presence of unreliable delivery mechanisms. This direct and simultaneous communication among a variety of nodes makes publish- subscribe network architecture the best choice for systems with complex time-critical data flows.

While the publish-subscribe model provides system architects with many advantages, it may not be the best choice for all types of communications, including:

❏File-based transfers (alternate solution: FTP)

❏Remote Method Invocation (alternate solutions: CORBA, COM, SOAP)

❏Connection-based architectures (alternate solution: TCP/IP)

❏Synchronous transfers (alternate solution: CORBA)

Figure 1.4 Publish-Subscribe

Subscriber

Publisher

Subscriber

Publisher Subscriber

Publish-subscribe is many-to-many communications.

1.4Features of Connext

Connext supports mechanisms that go beyond the basic publish-subscribe model. The key benefit is that applications that use Connext for their communications are entirely decoupled. Very little of their design time has to be spent on how to handle their mutual interactions. In particular, the applications never need information about the other participating applications, including their existence or locations. Connext automatically handles all aspects of message delivery, without requiring any intervention from the user applications, including:

❏determining who should receive the messages,

❏where recipients are located,

❏what happens if messages cannot be delivered.

This is made possible by how Connext allows the user to specify Quality of Service (QoS) parameters as a way to configure automatic-discovery mechanisms and specify the behavior used when sending and receiving messages. The mechanisms are configured up-front and require no further effort on the user's part. By exchanging messages in a completely anonymous manner, Connext greatly simplifies distributed application design and encourages modular, well-structured programs.

Furthermore, Connext includes the following features, which are designed to meet the needs of distributed real-time applications:

❏Data-centric publish-subscribe communications Simplifies distributed application programming and provides time-critical data flow with minimal latency.

•Clear semantics for managing multiple sources of the same data.

•Efficient data transfer, customizable Quality of Service, and error notification.

•Guaranteed periodic samples, with maximum rate set by subscriptions.

1-4

•Notification by a callback routine on data arrival to minimize latency.

•Notification when data does not arrive by an expected deadline.

•Ability to send the same message to multiple computers efficiently.

❏User-definable data types Enables you to tailor the format of the information being sent to each application.

❏Reliable messaging Enables subscribing applications to specify reliable delivery of samples.

❏Multiple Communication Networks Multiple independent communication networks (domains) each using Connext can be used over the same physical network. Applications are only able to participate in the domains to which they belong. Individual applications can be configured to participate in multiple domains.

❏Symmetric architecture Makes your application robust:

•No central server or privileged nodes, so the system is robust to node failures.

•Subscriptions and publications can be dynamically added and removed from the system at any time.

❏Pluggable Transports Framework Includes the ability to define new transport plug-ins and run over them. Connext comes with a standard UDP/IP pluggable transport and a shared memory transport. It can be configured to operate over a variety of transport mechanisms, including backplanes, switched fabrics, and new networking technologies.

❏Multiple Built-in Transports Includes UDP/IP and shared memory transports.

❏Multi-language support Includes APIs for the C, C++, C++/CLI, C#, and Java™ programming languages.

❏Multi-platform support Includes support for flavors of UNIX® (Linux® and Solaris™), real-time operating systems (INTEGRITY®, VxWorks®, QNX®, and LynxOS®), and Windows® (2000, 2003, CE, Vista, and XP). (Consult the Platform Notes to see which platforms are supported in this release.)

❏Compliance with Standards

•API complies with the DCPS layer of the OMG’s DDS specification.

•Data types comply with OMG Interface Definition Language™ (IDL).

•Data packet format complies with the International Engineering Consortium’s (IEC’s) publicly available specification for the RTPS wire protocol.

1-5

Chapter 2 Data-Centric Publish-Subscribe

Communications

This chapter describes the formal communications model used by Connext: the Data-Centric Publish-Subscribe (DCPS) standard. DCPS is a formalization (through a standardized API) and extension of the publish-subscribe communications model presented in Section 1.3.

This chapter includes the following sections:

❏What is DCPS? (Section 2.1)

❏Data Types, Topics, Keys, Instances, and Samples (Section 2.2)

❏DataWriters/Publishers and DataReaders/Subscribers (Section 2.3)

❏Domains and DomainParticipants (Section 2.4)

❏Quality of Service (QoS) (Section 2.5)

❏Application Discovery (Section 2.6)

2.1What is DCPS?

DCPS is the portion of the OMG DDS (Data Distribution Service) Standard that addresses data- centric publish-subscribe communications. The DDS standard defines a language-independent model of publish-subscribe communications that has standardized mappings into various implementation languages. Connext offers C, C++, C++/CLI, C#, and Java versions of the DCPS API.

The publish-subscribe approach to distributed communications is a generic mechanism that can be employed by many different types of applications. The DCPS model described in this chapter extends the publish-subscribe model to address the specific needs of real-time, data-critical applications. As you’ll see, it provides several mechanisms that allow application developers to control how communications works and how the middleware handles resource limitations and error conditions.

The “data-centric” portion of the term DCPS describes the fundamental concept supported by the design of the API. In data-centric communications, the focus is on the distribution of data between communicating applications. A data-centric system is comprised of data publishers and data subscribers. The communications are based on passing data of known types in named streams from publishers to subscribers.

In contrast, in object-centric communications the fundamental concept is the interface between the applications. An interface is comprised of a set of methods of known types (number and

2-1

types of method arguments). An object-centric system is comprised of interface servers and interface clients, and communications are based on clients invoking methods on named interfaces that are serviced by the corresponding server.

Data and object-centric communications are complementary paradigms in a distributed system. Applications may require both. However, real-time communications often fit a data-centric model more naturally.

2.1.1DCPS for Real-Time Requirements

DCPS, and specifically the Connext implementation, is well suited for real-time applications. For instance, real-time applications often require the following features:

Efficiency Real-time systems require efficient data collection and delivery. Only minimal delays should be introduced into the critical data-transfer path. Publish-subscribe is more efficient than client-server in both latency and bandwidth for periodic data exchange.

Publish-subscribe greatly reduces the overhead required to send data over the network compared to a client-server architecture. Occasional subscription requests, at low bandwidth, replace numerous high-bandwidth client requests. Latency is also reduced, since the outgoing request message time is eliminated. As soon as a new publication data sample becomes available, it is sent to the corresponding subscriptions.

Determinism Real-time applications often care about the determinism of delivering periodic data as well as the latency of delivering event data. Once buffers are introduced into a data stream to support reliable connections, new data may be held undelivered for a unpredictable amount of time while waiting for confirmation that old data was received. Since publish-subscribe does not inherently require reliable connections, implementations, like Connext, can provide configurable trade-offs between the deterministic delivery of new data and the reliable delivery of all data.

Flexible delivery bandwidth Typical real-time systems include both real-time and non-real-time nodes. The bandwidth requirements for these nodes—even for the same data—are quite different. For example, an application may be sending data samples faster than a non-real- time application is capable of handling. However, a real-time application may want the same data as fast as it is produced. DCPS allows subscribers to the same data to set individual limits on how fast data should be delivered each subscriber. This is similar to how some people get a newspaper every day while others can subscribe to only the Sunday paper.

Thread awareness Real-time communications must work without slowing the thread that sends data samples. On the receiving side, some data streams should have higher priority so that new data for those streams are processed before lower priority streams.

Connext provides user-level configuration of its internal threads that process incoming data. Users may configure Connext so that different threads are created with different priorities to process received data of different data streams.

Fault-tolerant operation Real-time applications are often in control of systems that are required to run in the presence of component failures. Often, those systems are safety critical or carry financial penalties for loss of service. The applications running those systems are usually designed to be fault-tolerant using redundant hardware and software. Backup applications are often “hot” and interconnected to primary systems so that they can take over as soon as a failure is detected. Publish-subscribe is capable of supporting many-to- many connectivity with redundant DataWriters and DataReaders. This feature is ideal for constructing fault-tolerant or high-availability applications with redundant nodes and robust fault detection and handling services.

DCPS, and thus Connext, was designed and implemented specifically to address the requirements above through configuration parameters known as QosPolicies defined by the DCPS standard (see QosPolicies (Section 4.2)). The following section introduces basic DCPS terminology and concepts.

2-2

2.2Data Types, Topics, Keys, Instances, and Samples

In data-centric communications, the applications participating in the communication need to share a common view of the types of data being passed around.

Within different programming languages there are several ‘primitive’ data types that all users of that language naturally share (integers, floating point numbers, characters, booleans, etc.). However, in any non-trivial software system, specialized data types are constructed out of the language primitives. So the data to be shared between applications in the communication system could be structurally simple, using the primitive language types mentioned above, or it could be more complicated, using, for example, C and C++ structs, like this:

struct Time { long year; short day; short hour; short minute; short second;

};

struct StockPrice { float price; Time timeStamp;

};

Within a set of applications using DCPS, the different applications do not automatically know the structure of the data being sent, nor do they necessarily interpret it in the same way (if, for instance, they use different operating systems, were written with different languages, or were compiled with different compilers). There must be a way to share not only the data, but also information about how the data is structured.

In DCPS, data definitions are shared among applications using OMG IDL, a language- independent means of describing data. For more information on data types and IDL, see Chapter 3.

2.2.1Data Topics — What is the Data Called?

Shared knowledge of the data types is a requirement for different applications to communicate with DCPS. The applications must also share a way to identify which data is to be shared. Data (of any data type) is uniquely distinguished by using a name called a Topic. By definition, a Topic corresponds to a single data type. However, several Topics may refer to the same data type.

Topics interconnect DataWriters and DataReaders. A DataWriter is an object in an application that tells Connext (and indirectly, other applications) that it has some values of a certain Topic. A corresponding DataReader is an object in an application that tells Connext that it wants to receive values for the same Topic. And the data that is passed from the DataWriter to the DataReader is of the data type associated with the Topic. DataWriters and DataReaders are described more in Section 2.3.

For a concrete example, consider a system that distributes stock quotes between applications. The applications could use a data type called StockPrice. There could be multiple Topics of the StockPrice data type, one for each company’s stock, such as IBM, MSFT, GE, etc. Each Topic uses the same data type.

Data Type: StockPrice

struct StockPrice { float price;

Time timeStamp;

};

2-3

Topic: “IBM”

Topic: “MSFT”

Topic: “GE”

Now, an application that keeps track of the current value of a client’s portfolio would subscribe to all of the topics of the stocks owned by the client. As the value of each stock changes, the new price for the corresponding topic is published and sent to the application.

2.2.2Samples, Instances, and Keys

The value of data associated with a Topic can change over time. The different values of the Topic passed between applications are called samples. In our stock-price example, samples show the price of a stock at a certain point in time. So each sample may show a different price.

For a data type, you can select one or more fields within the data type to form a key. A key is something that can be used to uniquely identify one instance of a Topic from another instance of the same Topic. Think of a key as a way to sub-categorize or group related data values for the same Topic. Note that not all data types are defined to have keys, and thus, not all topics have keys. For topics without keys, there is only a single instance of that topic.

However, for topics with keys, a unique value for the key identifies a unique instance of the topic. Samples are then updates to particular instances of a topic. Applications can subscribe to a topic and receive samples for many different instances. Applications can publish samples of one, all, or any number of instances of a topic. Many quality of service parameters actually apply on a per instance basis. Keys are also useful for subscribing to a group of related data streams (instances) without pre-knowledge of which data streams (instances) exist at runtime.

For example, let’s change the StockPrice data type to include the symbol of the stock. Then instead of having a Topic for every stock, which would result in hundreds or thousands of topics and related DataWriters and DataReaders, each application would only have to publish or subscribe to a single Topic, say “StockPrices.” Successive values of a stock would be presented as successive samples of an instance of “StockPrices”, with each instance corresponding to a single stock symbol.

Data Type: StockPrice

struct StockPrice { float price; Time timeStamp;

char *symbol; //@key

};

Instance 1 = (Topic: “StockPrices”) + (Key: “MSFT”)

sample a, price = $28.00

sample b, price = $27.88

Instance 2 = (Topic: “StockPrices”) + (Key: “IBM”)

sample a, price = $74.02

sample b, price = $73.50

Etc.

Just by subscribing to “StockPrices,” an application can get values for all of the stocks through a single topic. In addition, the application does not have to subscribe explicitly to any particular stock, so that if a new stock is added, the application will immediately start receiving values for that stock as well.

To summarize, the unique values of data being passed using DCPS are called samples. A sample is a combination of a Topic (distinguished by a Topic name), an instance (distinguished by a key), and the actual user data of a certain data type. As seen in Figure 2.1 on page 2-5, a Topic identifies data of a

2-4

single type, ranging from one single instance to a whole collection of instances of that given topic for keyed data types. For more information, see Chapter 3: Data Types and Data Samples and Chapter 5: Topics.

Figure 2.1 Relationship of Topics, Keys, and Instances

								a_type:instance1
	Type:a_type							Key = key1
	Key = ...
			Topic:a_topic					a_type:instance2
								Key = key2
								a_type:instance3
								Key = key3

By using keys, a Topic can identify a collection of data-object instances.

2.3DataWriters/Publishers and DataReaders/Subscribers

In DCPS, applications must use APIs to create entities (objects) in order to establish publish- subscribe communications between each other. The entities and terminology associated with the data itself have been discussed already—Topics, keys, instances, samples. This section will introduce the DCPS entities that user code must create to send and receive the data. Note that Entity is actually a basic DCPS concept. In object-oriented terms, Entity is the base class from which other DCPS classes—Topic, DataWriter, DataReader, Publisher, Subscriber,

DomainParticipants—derive. For general information on Entities, see Chapter 4: Entities.

The sending side uses objects called Publishers and DataWriters. The receiving side uses objects called Subscribers and DataReaders. Figure 2.2 illustrates the relationship of these objects.

❏An application uses DataWriters to send data. A DataWriter is associated with a single Topic. You can have multiple DataWriters and Topics in a single application. In addition, you can have more than one DataWriter for a particular Topic in a single application.

❏A Publisher is the DCPS object responsible for the actual sending of data. Publishers own and manage DataWriters. A DataWriter can only be owned by a single Publisher while a Publisher can own many DataWriters. Thus the same Publisher may be sending data for many different Topics of different data types. When user code calls the write() method on a DataWriter, the data sample is passed to the Publisher object which does the actual dissemination of data on the network. For more information, see Chapter 6: Sending Data.

❏The association between a DataWriter and a Publisher is often referred to as a publication although you never create a DCPS object known as a publication.

❏An application uses DataReaders to access data received over DCPS. A DataReader is associated with a single Topic. You can have multiple DataReaders and Topics in a single application. In addition, you can have more than one DataReader for a particular Topic in a single application.

2-5

Figure 2.2 Overview

❏A Subscriber is the DCPS object responsible for the actual receipt of published data. Subscribers own and manage DataReaders. A DataReader can only be owned by a single

Subscriber while a Subscriber can own many DataReaders. Thus the same Subscriber may receive data for many different Topics of different data types. When data is sent to an application, it is first processed by a Subscriber; the data sample is then stored in the appropriate DataReader. User code can either register a listener to be called when new data arrives or actively poll the DataReader for new data using its read() and take() methods. For more information, see Chapter 7: Receiving Data.

❏The association between a DataReader and a Subscriber is often referred to as a subscription although you never create a DCPS object known as a subscription.

Example: The publish-subscribe communications model is analogous to that of magazine publications and subscriptions. Think of a publication as a weekly periodical such as Newsweek®. The Topic is the name of the periodical (in this case the string "Newsweek"). The type specifies the format of the information, e.g., a printed magazine. The user data is the contents (text and graphics) of each sample (weekly issue). The middleware is the distribution service (usually the US Postal service) that delivers the magazine from where it is created (a printing house) to the individual subscribers (people’s homes). This analogy is illustrated in Figure 2.3. Note that by subscribing to a publication, subscribers are requesting current and future samples of that publication (such as once a week in the case of Newsweek), so that as new samples are published, they are delivered without having to submit another request for data.

By default, each data sample is propagated individually, independently, and uncorrelated with other samples. However, an application may request that several samples be sent as a coherent set, so that they may be interpreted as such on the receiving side.

2-6

Figure 2.3 An Example of Publish-Subscribe

Topic = "Newsweek"					Topic = "Newsweek"
		Sample
Publisher		Issue for Feb. 15			Subscriber
	Send				Receive
		Delivery		Service

The publish-subscribe model is analogous to publishing magazines. The Publisher sends samples of a particular Topic to all Subscribers of that Topic. With Newsweek® magazine, the Topic would be "Newsweek." The sample consists of the data (articles and pictures) sent to all Subscribers every week. The middleware (Connext) is the distribution channel: all of the planes, trucks, and people who distribute the weekly issues to the Subscribers.

2.4Domains and DomainParticipants

You may have several independent DCPS applications all running on the same set of computers. You may want to isolate one (or more) of those applications so that it isn’t affected by the others. To address this issue, DCPS has a concept called Domains.

Domains represent logical, isolated, communication networks. Multiple applications running on the same set of hosts on different Domains are completely isolated from each other (even if they are on the same machine). DataWriters and DataReaders belonging to different domains will never exchange data.

Applications that want to exchange data using DCPS must belong to the same Domain. To belong to a Domain, DCPS APIs are used to configure and create a DomainParticipant with a specific Domain Index. Domains are differentiated by the Domain Index (an integer value). Applications that have created DomainParticipants with the same Domain Index belong to the same Domain. DomainParticipants own Topics, Publishers and Subscribers which in turn owns

DataWriters and DataReaders. Thus all DCPS Entities belong to a specific domain.

An application may belong to multiple domains simultaneously by creating multiple

DomainParticipants with different domain indices. However, Publishers/DataWriters and

Subscribers/DataReaders only belong to the domain in which they were created.

As mentioned before, multiple domains may be used for application isolation which is useful when users are testing their applications using computers on the same network or even the same computers. By assigning each user different domains, one can guarantee that the data produced by one user’s application won’t accidentally be received by another. In addition, domains may be a way to scale and construct larger systems that are composed of multi-node subsystems. Each subsystem would use an internal domain for intra-system communications and an external domain to connect to other subsystems.

For more information, see Chapter 8: Working with Domains.

2-7

2.5Quality of Service (QoS)

The publish-subscribe approach to distributed communications is a generic mechanism that can be employed by many different types of systems. The DCPS model described here extends the publish-subscribe model to address the needs of real-time, data-critical applications. It provides standardized mechanisms, known as Quality of Service Policies, that allow application developers to configure how communications occur, to limit resources used by the middleware, to detect system incompatibilities and setup error handling routines.

2.5.1Controlling Behavior with Quality of Service (QoS) Policies

QosPolicies control many aspects of how and when data is distributed between applications. The overall QoS of the DCPS system is made up of the individual QosPolicies for each DCPS

Entity. There are QosPolicies for Topics, DataWriters, Publishers, DataReaders, Subscribers, and DomainParticipants.

On the publishing side, the QoS of each Topic, the Topic’s DataWriter, and the DataWriter’s Publisher all play a part in controlling how and when data samples are sent to the middleware. Similarly, the QoS of the Topic, the Topic’s DataReader, and the DataReader’s Subscriber control behavior on the subscribing side.

Users will employ QosPolicies to control a variety of behaviors. For example, the DEADLINE policy sets up expectations of how often a DataReader expects to see samples. The OWNERSHIP and OWNERSHIP_STRENGTH policy are used together to configure and arbitrate whose data is passed to the DataReader when there are multiple DataWriters for the same instance of a Topic. The HISTORY policy specifies whether a DataWriter should save old data to send to new subscriptions that join the network later. Many other policies exist and they are presented in QosPolicies (Section 4.2).

Some QosPolicies represent “contracts” between publications and subscriptions. For communications to take place properly, the QosPolicies set on the DataWriter side must be compatible with corresponding policies set on the DataReader side.

For example, the RELIABILITY policy is set by the DataWriter to state whether it is configured to send data reliably to DataReaders. Because it takes additional resources to send data reliably, some DataWriters may only support a best-effort level of reliability. This implies that for those DataWriters, Connext will not spend additional effort to make sure that the data sent is received by DataReaders or resend any lost data. However, for certain applications, it could be imperative that their DataReaders receive every piece of data with total reliability. Running a system where the DataWriters have not been configured to support the DataReaders could lead to erratic failures.

To address this issue, and yet keep the publications and subscriptions as decoupled as possible, DCPS provides a way to detect and notify when QosPolicies set by DataWriters and DataReaders are incompatible. DCPS employs a pattern known as RxO (Requested versus Offered). The DataReader sets a “requested” value for a particular QosPolicy. The DataWriter sets an “offered” value for that QosPolicy. When Connext matches a DataReader to a DataWriter, QosPolicies are checked to make sure that all requested values can be supported by the offered values.

Note that not all QosPolicies are constrained by the RxO pattern. For example, it does not make sense to compare policies that affect only the DataWriter but not the DataReader or vice versa.

If the DataWriter can not satisfy the requested QosPolicies of a DataReader, Connext will not connect the two entities and will notify the applications on each side of the incompatibility if so configured.

For example, a DataReader sets its DEADLINE QoS to 4 seconds—that is, the DataReader is requesting that it receive new data at least every 4 seconds.

2-8

In one application, the DataWriter sets its DEADLINE QoS to 2 seconds—that is, the DataWriter is committing to sending data at least every 2 seconds. This writer can satisfy the request of the reader, and thus, Connext will pass the data sent from the writer to the reader.

In another application, the DataWriter sets its DEADLINE QoS to 5 seconds. It only commits to sending data at 5 second intervals. This will not satisfy the request of the DataReader. Connext will flag this incompatibility by calling user-installed listeners in both DataWriter and DataReader applications and not pass data from the writer to the reader.

For a summary of the QosPolicies supported by Connext, see QosPolicies (Section 4.2).

2.6Application Discovery

The DCPS model provides anonymous, transparent, many-to-many communications. Each time an application sends a sample of a particular Topic, the middleware distributes the sample to all the applications that want that Topic. The publishing application does not need to specify how many applications receive the Topic, nor where those applications are located. Similarly, subscribing applications do not specify the location of the publications. In addition, new publications and subscriptions of the Topic can appear at any time, and the middleware will automatically interconnect them.

So how is this all done? Ultimately, in each application for each publication, Connext must keep a list of applications that have subscribed to the same Topic, nodes on which they are located, and some additional QoS parameters that control how the data is sent. Also, Connext must keep a list of applications and publications for each of the Topics to which the application has subscribed.

This propagation of this information (the existence of publications and subscriptions and associated QoS) between applications by Connext is known as the discovery process. While the DDS (DCPS) standard does not specify how discovery occurs, Connext uses a standard protocol RTPS for both discovery and formatting on-the-wire packets.

When a DomainParticipant is created, Connext sends out packets on the network to announce its existence. When an application finds out that another application belongs to the same domain, then it will exchange information about its existing publications and subscriptions and associated QoS with the other application. As new DataWriters and DataReaders are created, this information is sent to known applications.

The Discovery process is entirely configurable by the user and is discussed extensively in Chapter 14: Discovery.

2-9

Index, Part 1

A

architectures supported ii-vi

C

client-server model 1-3 communications models 1-2

client-server 1-3 data-centric 2-1

DCPS 2-1, 2-8 object-centric 2-2 point-to-point 1-3 publish-subscribe 1-3, 2-5

D

data types 2-3

data-centric communications 2-1

DCPS 2-1, 2-8 domains

definition 2-7 multiple 2-7

E

environment variables NDDSHOME ii-vi

I

IDL 2-3

N

NDDSHOME ii-vi

O

object-centric communications 2-2

P

platforms supported ii-vi point-to-point communication 1-3 publications 2-6

definition 2-5 Publishers

definition 2-5

publish-subscribe communications 1-3, 2-5

Q

Quality of Service. See QoS

R

real-time applications features of 2-2

S

samples definition 2-4

stock quote example 2-3 to 2-4 Subscribers

definition 2-6

T

Topics 2-6

definition 2-3 to 2-4 typographical conventions ii-vi

Index-1