RTI Connext Modern C++ API  Version 6.0.0
 All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator Friends Groups Pages
Conventions

This sections describes some conventions used in the API.

API Documentation Terms

In the API documentation, the term module refers to a logical grouping of documentation and elements in the API.

Stereotypes

Commonly used stereotypes in the API documentation include the following.

Extensions

<<extension>> An RTI Connext product extension to the DDS standard specification.

The 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:
participant->register_durable_subscription(...);

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

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

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

Experimental

<<experimental>> Experimental features subject to change.

Types

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::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 to explicitly activate 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 a explicit activation, you will need to pass a flag (for example -std=c++0x or -std=c++11 in gcc and clang). Rtiddsgen can help with that.

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

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

Exceptions in the API

If a function doesn't document what exceptions it may throw and is not declared OMG_NOEXCEPT, then it may throw any of the standard exceptions. In most cases applications don't need to explicitly catch these 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.

Some times a function may throw an exception that may be interesting to catch and handle. In those cases the exception will be documented in the "throws" section of that function. An example is dds::pub::DataWriter::qos().

Note that many functions can also throw C++ standard exceptions such as std::bad_alloc.

See Also
Exceptions

RTI Connext Modern C++ API Version 6.0.0 Copyright © Sun Mar 3 2019 Real-Time Innovations, Inc