RTI Connext Modern C++ API Version 7.3.0
Conventions

Basic concepts required to use the API correctly.

Basic concepts required to use the API correctly.

There are a few basic conventions that you need to understand to use this API correctly:

Type system

All types in the API are value types, reference types, or move-only types. In this documentation a type is a value type, unless explicitly marked with <<reference-type>> or <<move-only-type>>. In some cases the type may be marked with <<value-type>> for clarity.

Value types

<<value-type>> Value types implement value semantics.

Note that in this API, types that don't specify their type semantics are value types by default. IDL-generated types are also value types.

Value types provide the following functionality:

Those operations are not documented for each type unless they deviate from their usual behavior.

Reference types

<<reference-type>> Reference types implement reference semantics.

In a reference type copy operations, such as copy-construction and copy-assignment
are shallow. The reference types are modeled after shared pointers. Similar to pointers, it is important to distinguish between an entity and a reference (or handle) to it. A single entity may have multiple references. Copying a reference does not copy the entity it is referring to—creating additional references from the existing reference(s) is a relatively inexpensive operation.

The lifecycle of references and the entity they are referring to is not the same. In general, the entity lives as long as there is at least one reference to it. When the last reference to the entity ceases to exists, the entity it is referring to is destroyed.

However, there are some exceptions. It is possible—and often convenient—to retain an entity even though it has no references, for example to look it up later. An reference can also be explicitly closed, deleting the object it references, regardless of the existence of other references.

An entity is considered to still be in use (i.e., retained) if any of the following conditions are met:

All reference types inherit from dds::core::Reference. The reference semantics are implemented using a shared count.

Reference types provide the following functionality:

Some reference types, including dds::core::Entity and its subclasses, also provide:

Reference types with an inheritance relationship such as dds::core::Entity or dds::core::cond::Condition can use dds::core::polymorphic_cast to cast from a base to a derived class.

For more examples on reference types see Entity Use Cases

Move-only types

<<move-only-type>> Move-only types are types that can't be copied, only "moved." A move-only type encapsulates a view of an internal resource. Only one reference to that resource may exist at a time.

C++11 Support

<<C++11>> Functionality supported only in C++11.

This API is designed to integrate with and make use of C++11. The API headers are prepared to detect at application-compile time what C++11 features are available and make use of them.

Different compilers support different C++11 features, and some require
explicitly activating C++11 support. If your compiler activates C++11 by default (for example, Visual Studio 2010 and later), you don’t need to do anything. Whatever features are available will be used. If your compiler requires an explicit activation, you will need to pass a flag (for example, -std=c++0x or -std=c++11 in gcc and clang). The Platform Notes can help with that.

The API provides the following C++11 features when available:

Exceptions in the API

The modern C++ API uses exceptions to report errors.

If a function doesn't document what exceptions it may throw and is not declared noexcept, then it may throw any of the standard exceptions.

Destructors won't throw exceptions. There are cases however where you may need to handle an error during an object destruction. Some classes, like the reference types provide a close() operation–which can throw–that destroys the underlying entity.

Note that the API can also throw C++ standard exceptions such as std::bad_alloc.

For a few critical operations both a regular exception-throwing function and a noexcept function are provided. The noexcept versions always return an rti::core::Result object, and are always extension functions that need to be accessed with the -> operator. For example, a dds::sub::DataReader provides both take() and take_noexcept():

auto samples = reader.take(); // may throw
auto result = reader->take_noexcept(); // never throws
if (result.is_ok()) {
auto& samples = result.get();
// ...
}
See also
Exceptions

Extensions to the standard API

<<extension>> The stereotype <<extension>> indicates that a type or a function is RTI Connext product extension to the standard DDS specification.

The RTI extension APIs complement the standard APIs specified by the OMG DDS specification.

There are the following kinds of extensions: extension methods for a standard class, extension types, and extension standalone functions.

To call an extension methods for an standard class use the extensions() method or the overloaded arrow operator (->). For example:

// Standard class (in dds namespace)
dds::domain::DomainParticipant participant(MY_DOMAIN_ID);
// Call a standard method
participant.assert_liveliness();
// Call an extension method:
participant.extensions().register_durable_subscription(...);
// or:
void assert_liveliness()
Manually assert the liveliness of the DomainParticipant.
Definition: TDomainParticipant.hpp:320
void register_durable_subscription(const rti::core::EndpointGroup &group, const std::string &topic_name)
<<extension>> Registers a Durable Subscription on the specified dds::topic::Topic on all Persistence ...

Note that the arrow operator is noexcept but the extensions() method of a reference type is not (it may throw dds::core::NullReferenceError if the object is dds::core::null).

In this documentation extension members in a standard type appear as members of that type, although they are members of a delegate type called through the standard type (calling extensions() or the arrow operator). We omit this implementation detail from the API documentation for simplicity.

Extension types reside in the rti namespace instead of the dds namespace. For example:

// FlowController is an extension class and it resides in the rti namespace
rti::pub::FlowController flow_controller(participant);
// All methods in an extension class are called using the usual dot operator
flow_controller.trigger_flow();
<<extension>> <<reference-type>> A flow controller is the object responsible for shaping the network ...
Definition: FlowController.hpp:345

The following example combines an extension function for a standard type (Reliability) and an extension type (AcknowledgmentKind):

// Standard class (in dds namespace)
// Call a standard method
reliability.kind(dds::core::policy::ReliabilityKind::RELIABLE);
// Call an extension method, passing an extension enumeration:
reliabilty.extensions().acknowledgment_kind(
rti::core::policy::AcknowledgmentKind::APPLICATION_AUTO);
// or:
reliabilty->acknowledgment_kind(
rti::core::policy::AcknowledgmentKind::APPLICATION_AUTO);
Indicates the level of reliability in sample delivered that a dds::pub::DataWriter offers or a dds::s...
Definition: TCorePolicy.hpp:1298
dds::core::policy::Reliability & acknowledgment_kind(rti::core::policy::AcknowledgmentKind ack_kind)
<<extension>> Sets the kind of reliable acknowledgment
Reliability & kind(dds::core::policy::ReliabilityKind the_kind)
Sets the reliability kind.
Definition: TCorePolicy.hpp:1328

Extension standalone functions are also in the rti namespace. For example:

// Standard function (in the dds namespace)
dds::sub::find<dds::sub::DataReader<Foo> >(
subscriber, "Foo Topic", std::back_inserter(readers));
// Extension function (in the rti namespace)
rti::sub::find_datareaders(subscriber, std::back_inserter(readers));
uint32_t find_datareaders(dds::sub::Subscriber subscriber, AnyDataReaderBackInsertIterator begin)
<<extension>> Retrieve all the dds::sub::DataReader created from this dds::sub::Subscriber
Definition: sub/findImpl.hpp:424

Experimental

<<experimental>> Experimental features subject to change.

Method Parameters

Some times the parameter may have one of the following stereotypes, but in most cases the function signature reveals if the parameter is an input parameter (by value or const-reference), or output parameter (non-const reference).