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)
dds::core::policy::Reliability reliability;

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

• RTI Connext experimental features are used to evaluate new features and get user feedback.
• These features are not guaranteed to be fully supported and might be implemented only of some of the programming languages supported bt RTI Connext
• Experimental features may or may not appear in future product releases.
• Experimental features should not be used in production.

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:

• Deep-copy copy constructor and assignment operator.
• Move constructor and move-assignment operator <<C++11>>.
• Destructor.
• Equality operators.
• Namespace-level swap() function.

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:

• The entity has one or more references.
• The entity has a non-null listener (if it applies).
• The entity has been explicitly retained.
• The entity created another object that is still in use. For example, while a Topic exist, its related DomainParticipant won't be deleted.

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

Reference types provide the following functionality:

• Constructors specific to the type

  Creates a new object and a reference to it. For example:

  // Create a domain participant and one reference to it.
  dds::domain::DomainParticipant participant(MY_DOMAIN_ID);

• Copy constructor

  Creates a new reference to an existing object, increasing the reference count. For example:

  dds::domain::DomainParticipant same_participant = participant;

• Assignment operator

  Replaces the object that was referenced to with a new one, possibly decreasing the reference count of the former object and increasing it for the new one.

• Constructor from dds::core::null (or nullptr <<C++11>>)

  Creates an instance that doesn't reference any object. For example:

  dds::domain::DomainParticipant null_participant = dds::core::null;

• Assignment operator from dds::core::null (or nullptr <<C++11>>)

  Makes the reference empty, decreasing the reference count.

  dds::domain::DomainParticipant participant(MY_DOMAIN_ID);
  participant = dds::core::null; // This will destroy the participant object

• Equal operator (to another reference)

  Returns true only if the referenced object is the same. For example:

  dds::domain::DomainParticipant participant1(MY_DOMAIN_ID);
  dds::domain::DomainParticipant participant2(MY_DOMAIN_ID);
  
  if (participant1 != participant2) {
      std::cout << "References to different objects\n";
  }
  
  // Note that this also destroys the former object referenced to by participant2
  participant2 = participant1;
  if (participant1 == participant2) {
      std::cout << "References to the same object\n";
  }

  The operators <, <=, >, >= are also supported, and compare the underlying pointer.

• Equal operator to dds::core::null (or nullptr <<C++11>>)

  Returns true only if this reference is empty. For example:

  dds::domain::DomainParticipant participant = dds::core::null;
   // dds::core::null and nullptr are interchangeable in C++11
  if (participant == nullptr) {
      std::cout << "Empty reference\n";
  }

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

• close()

  Forces the destruction of the underlying object. After this, calling a method on the destroyed object throws dds::core::AlreadyClosedError. For example:

  dds::domain::DomainParticipant participant1(MY_DOMAIN_ID);
  dds::domain::DomainParticipant participant2 = participant1;
  
  participant2.close(); // Destroys the underlying object
  
  int id = participant1.domain_id(); // throws dds::core::AlreadyClosedError

• retain()

  Disables the destruction of the underlying object. When all references are destroyed the underlying object still exists and can be looked up. To finally destroy a retained object you need to explicitly call close().

  For example:

  using namespace dds::domain;
  
  void create_participant()
  {
      DomainParticipant participant(MY_DOMAIN_ID);
      participant.retain();
  } // participant goes out of scope
  
  void test_retain()
  {
      create_participant();
      DomainParticipant participant = find(MY_DOMAIN_ID);
      
      // ...
      
      // Since the participant has been retained, we need to explicitly close it:
      participant.close();
  }

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:

• Defines move constructors and move-assignment operators for most types, both in the API and in types generated from IDL.
• Enables the use of the range for-loop in classes like dds::sub::LoanedSamples.
• Enables the use of lambda functions in places like dds::sub::cond::ReadCondition
• Specifies some key functions as noexcept, like move constructors.
• Enables the use of std::initializer_list in several functions. For example see rti::core::policy::Property. <<extension>>
• Provides utilities to manipulate dds::core::xtypes::DynamicType and dds::core::xtypes::DynamicData using tuples. <<extension>> <<experimental>>
• Supports the interchangeable use of std::chrono::duration and dds::core::Duration. <<extension>>
• Supports the interchangeable use of nullptr and dds::core::null.

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

• <<in>>
  • An input parameter.

• <<out>>
  • An output parameter.

• <<inout>>
  • An input and output parameter.

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