2. General Compatibility

This section describes compatibility issues that affect the Connext suite. Unless noted otherwise, the issues in this section do not apply to RTI Connext DDS Micro.

2.1. Platforms

Note

For information on new and removed platforms in this release, see What’s New in 6.0.0. See also individual products’ Release Notes.

2.2. Wire Compatibility

2.2.1. New default GUID generation mode

Starting in 6.0.0, the default value of DDS::DomainParticipantQos::wire_protocol::rtps_auto_id_kind has changed from DDS_RTPS_AUTO_ID_FROM_IP (which caused the rtps_host_id to be the IP address by default) to DDS_RTPS_AUTO_ID_FROM_UUID (which causes the rtps_host_id, rtps_app_id, and rtps_instance_id to be a unique, randomly generated value). This change was done to comply with the latest RTPS specification and reduce the possibility of non-unique GUIDs due to process ID collision.

As a result of this change, out-of-the-box, DomainParticipants within the same process no longer have a GUID that is ordered by creation time (via rtps_instance_id). In other words, you can no longer expect that all DomainParticipants will be ordered sequentially within an application, since they are now using a random value to determine the GUID rather than a sequential (time-based) value. This new ordering may affect the usage of API functions that output a list of DomainParticipant InstanceHandles, such as DDS::DomainParticipant::get_discovered_participants.

Furthermore, if you are using older versions of RTI Administration Console and RTI Monitor to display data from a 6.0.0 application, these tools may display confusing information if system properties (those that start with “dds.sys_info”) are turned off. When you turn off system properties during discovery (to save on bandwidth and discovery time), older versions of Admin Console and Monitor figure out what those properties are by assuming that part of the GUID is the host IP address and process ID. (In some cases, Admin Console and Monitor can find the IP address through the locators, but if that information is not available, the tools will also assume that the random value is the IP address.) For more information on how your older version of Admin Console or Monitor handles host name and process ID, see the Help menu in Admin Console for your specific version or see the RTI Monitor User’s Manual for your specific version. (All older versions of Admin Console will have this issue with 6.0.0 data, out-of-the-box; not all older versions of Monitor will have this issue out-of-the-box.)

If you want the default value to be DDS_RTPS_AUTO_ID_FROM_IP instead of DDS_RTPS_AUTO_ID_FROM_UUID, like it was before, change it in the WIRE_PROTOCOL QosPolicy. (Remember that the old default value increases the possibility of non-unique GUIDs due to process ID collision.)

2.2.2. Default shared memory locator has changed

See information about this change in Section 2.5.

2.2.3. 4.2e alignment option deprecated

If your Connext DDS application’s data type uses a double, long long, unsigned long long, or long double, it will not interoperate with applications built with RTI Data Distribution Service 4.2e or lower.

In previous releases (5.3.1 or lower), you could use the -use42eAlignment command-line option when generating code with RTI Code Generator, in combination with the properties dds.data_writer.type_support.use_42e_alignment and dds.data_reader.type_support.use_42e_alignment, to get backward compatibility. These options are no longer available in 6.0.0. The option use_42e_compatible_alignment in DynamicDataTypeSerializationProperty_t is not available either.

If you need interoperability between 6.0.0 and 4.2e applications, contact RTI Support at support@rti.com.

2.2.4. Changed wire representation of TypeObject

See information about this change in Section 2.4.2.

2.2.5. TypeCode information is not sent by default

See information about this change in Section 2.4.3.

2.3. Reliability Protocol

2.3.1. Changes in behavior of write() operation with KEEP_LAST configuration

In previous releases, a race condition may have caused the write operation on a KEEP_LAST DataWriter to return a timeout error when the send window was full and the blocking time expired (according to max_blocking_time in the Reliability QosPolicy). This race condition occurred only with small blocking times.

A keep-last reliable DataWriter will block if the send window is full, but it should not return a timeout error. In 6.0.0, this timeout problem has been fixed (see RTI Issue ID CORE-8845 in the “Other Fixes” section of the Core Libraries Release Notes). If the blocking time expires, the new sample is added to its associated instance. If there are depth samples in the instance, the new sample replaces the oldest sample of the same instance, even if that sample is not fully acknowledged.

2.4. Type System Compatibility

2.4.1. Migration to Extended CDR encoding version 2 (XCDR2)

2.4.1.1. Overview

Connext DDS now supports the Extended Common Data Representation (CDR) encoding version 2 (XCDR2), in addition to version 1 (XCDR). XCDR2 is supported in both Connext DDS and Connext DDS Micro.

XCDR2 is more efficient on the wire than Extended CDR encoding version 1 (XCDR). For new applications, Extended CDR encoding 2 is the recommended data representation; however, if you need to keep compatibility and interoperability with old Connext DDS applications (5.3.1 and below), you may have to continue using Extended CDR encoding 1.

You may use the new DataRepresentationQosPolicy in the DataWriterQos to configure which version of Extended CDR, version 1 or version 2, the DataWriter will use to serialize its data. The same QosPolicy exists in the DataReaderQos to configure which version(s) the DataReader will accept from DataWriters. DataWriters can offer only one data representation, while DataReaders can request multiple data representations. The default value AUTO is translated into XCDR.

DataReaders can be configured to receive data using both XCDR2 and XCDR. This way, a DataReader can still interoperate and receive data from old Connext DDS DataWriters using XCDR, while receiving data from new DataWriters using XCDR2.

The opposite is not true. DataWriters can publish only one data representation. Therefore, if there is a requirement to receive data for a topic ‘T’ with old Connext DDS DataReaders, you will have to continue to publish data for topic ‘T’ with XCDR representation on the new DataWriters or use a bridge such as RTI Routing Service to translate between XCDR and XCDR2.

For additional information, see the RTI Connext DDS Core Libraries Getting Started Guide Addendum for Extensible Types.

2.4.1.2. Known Issues

Note the following known issues with XCDR2:

2.4.1.2.1. Incorrect keyhash generation in .Net/Java when using XCDR2 data representation
2.4.1.2.1.1. Incorrect key-hash generation in .Net when using XCDR2 data representation

In 6.0.0, the generation of key-hashes in .Net is incorrect in some cases when using the XCDR2 data representation.

As a result, a subscriber of a different language may treat as different two instances that are actually the same if one of those two samples comes from an application written in .Net and the other sample comes from an application written in a different language.

The affected types are the following:

1) Keyed types where one of the key members is double long long or unsigned long long. For example:

struct MyStruct {
    @key char m1;
    @key double m2;
    @key double m3;
    long m4;
};

2) Keyed types that inherit from another type where the key fields are only on the base type. For example:

@nested
struct MyBaseStruct {
    @key long myLong;
};

struct MyStruct: MyBaseStruct {
    long myLong2;
};

In addition, when a publisher application in any language sets the writer_qos.protocol.disable_inline_keyhash QoS to true, and a different application in C/C++/Java does not set this property, a .Net subscriber application can treat as different two instances that are coming from each one of those applications in the following cases:

1) Keyed types that have an inheritance relationship where the key can be in both the parent or the derived class. For example:

@nested
struct MyBaseStruct {
    @key long myLong;
};

struct MyStruct: MyBaseStruct {
    long myLong2;
};

2) Keyed types that have a key member whose type is the same as the one defined in the previous point. For example:

struct MyBaseStruct {
    @key long myLong;
};

struct MyStruct: MyBaseStruct {
    long myLong2;
};

struct MyKeyedType {
    @key MyStruct m1
    long m2;
}

3) Keyed types with a key member whose type is an unkeyed type that has an inheritance relationship. For example:

@nested
struct MyBaseStruct {
    long myLong;
};

struct MyStruct: MyBaseStruct {
    long myLong2;
};

struct MyKeyedType {
    @key MyStruct m1
    long m2;
}

These issues will be fixed in an upcoming patch.

[RTI Issue IDs CODEGENII-1197 and CODEGENII-1198]

2.4.1.2.1.2. Incorrect key-hash generation in Java when using XCDR2 data representation

In 6.0.0, the generation of key-hashes in Java is incorrect in some cases when using the XCDR2 data representation.

As a result, a subscriber of a different language may treat as different two instances that are actually the same when they come from an application written in Java and an application written in a different language.

The types affected by this issue are keyed types that inherit from a base type, when their keys are only in the base type. For example:

@nested
struct MyBaseStruct {
    @key long myLong;
};

struct MyStruct: MyBaseStruct {
    long myLong2;
};

In addition, when a publisher application in any language sets the writer_qos.protocol.disable_inline_keyhash QoS to true, and a different application in C/C++/.Net does not set this property, a Java subscriber application might interpret as different two instances that are coming from each of the applications in the following cases:

  1. Keyed type that inherits from a base type and the key is only in the derived type:
struct MyBaseStruct {
    long myLong;
};

struct mystruct: MyBaseStruct {
    @key long myLong2;
};

2) Keyed types who have a key member whose type is the same as the one defined in the previous point. For example:

struct MyBaseStruct {
    long myLong;
};

struct MySruct: MyBaseStruct {
    @key long myLong2;
};

struct MyKeyedType {
    @key MyStruct m1
    long m2;
};

These issues will be fixed in an upcoming patch.

[RTI Issue IDs CODEGENII-1197 and CODEGENII-1198]

2.4.1.2.2. Incorrect serialization in Java when using XCDR2 for types containing wchar, double, long long, or unsigned long long members

Serialization in Java when using the XCDR2 data representation for types that contain wchar, double, long long, or unsigned long long members is incorrect.

As a result:

1) A Java publisher application publishing one of those types may throw an error like the following one:

com.rti.dds.cdr.IllegalCdrStateException: not enough available space in CDR buffer

2) A subscriber application in any language that receives data from that Java publisher application might receive incorrect data or report deserialization errors.

This problem will be fixed in an upcoming patch.

[RTI Issue ID CODEGENII-1206]

2.4.2. Changed wire representation of TypeObject

In this release, Connext DDS enables TypeObject compression by default to reduce bandwidth usage when exchanging endpoint discovery data. Specifically, Connext DDS reduces the size needed to propagate a TypeObject as part of Simple Endpoint Discovery. With this feature, a compressed version of the serialized TypeObject (TypeObjectLb) is now sent as a Simple Endpoint Discovery parameter. See What’s New in 6.0.0 for details.

As a result of this feature:

  • Previous versions of Connext DDS will not be able to receive TypeObject out-of-the-box from applications running 6.0.0, since that TypeObject is now compressed.

  • Therefore, out-of-the-box, type matching with Connext DDS 5.x applications and lower will be done using the registered type name and not the TypeObject. If the registered type names in the DataWriter and DataReader are different, Connext DDS 6.x and higher applications will not communicate with Connext DDS 5.x and lower applications.
    When 6.x applications detect this scenario, the following warning will be logged:

    DISCBuiltinTopicPublicationDataPlugin_deserialize:Received type information
for a remote Participant that does not support TypeObject compression.
TypeObject compression is currently enabled for the local participant,
which may prevent communication between local and remote Participant if
registered typenames are different.  In order to avoid this issue, please
set DiscoveryConfigQosPolicy's endpoint_type_object_lb_serialization_threshold
to -1 to disable TypeObject compression.

  • Additionally, Connext DDS 5.x services and tools relying on type definitions require you to register the type through XML to properly work out-of-the-box with 6.x. For example, if Routing Service 5.x communicates with an out-of-the-box 6.x application, types will not be received through discovery. Therefore, you need to configure the types in the Routing Service configuration file (see the Route Types section in the Routing Service User’s Manual). Otherwise, Routing Service will not be able to create routes.

If your system is affected by any of the above issues, you have a few options:

2.4.3. TypeCode information is not sent by default

The default value for DDS_DomainParticipantQos::resource_limits:: type_code_max_serialized_length has changed to 0 (from 2048). This change disables sending TypeCode by default, in order to decrease Endpoint Discovery traffic.

This change may affect compatibility with old Connext DDS (4.5f and below) applications whose functionality depended on discovering the type information from remote applications using TypeCodes. Connext DDS 4.5f and below did not support TypeObjects (the standard alternative to TypeCode) as a way to exchange type information; the only way to do that was through TypeCodes.

This change may also affect compatibility with old versions of RTI Routing Service (4.5f and below) if you did not provide the type definitions to Routing Service using XML. In this case, some routes in the old Routing Service may stop forwarding data.

If you have this problem with Connext DDS 4.5f and below, configure your Connext DDS 6.0.0 application to send TypeCodes by setting DDS_DomainParticipantQos::resource_limits:: type_code_max_serialized_length to the old default value (2048) or a bigger value if your types need it.

2.4.4. Unbounded sequences and strings in XML type representation

Previously, if a type defined in XML had its sequences or strings set to -1 in the attributes sequenceMaxLength or stringMaxLength, the resulting sequence or string length was interpreted as being of a default bounded size rather than unbounded. The default size for sequences was 100 and for strings was 255. This problem has been resolved. The resulting length is now interpreted as unbounded in 6.0.0.

This change may lead to some unexpected memory growth when moving existing applications to Connext DDS 6.0.0.

If the strings and/or sequences are not supposed to be unbounded, set the maximum length to 100 for sequences and 255 for strings.

If the strings or sequences are supposed to be unbounded, make sure that you limit the memory usage by using properties such as dds.data_writer.history.memory_manager.fast_pool.pool_buffer_max_size or the <memory_management> tag in RTI Routing Service, RTI Recording Service, and XML-Based Application Creation. For additional information, see the “DDS Sample-Data and Instance-Data Memory Management” chapter in the RTI Connext DDS Core Libraries User’s Manual.

2.4.5. wchar and wstring language binding changes

Starting in Connext DDS 6.0.0 (and Connext DDS Micro 3.0.0), for C, traditional C++, and Ada languages, the mapping of an IDL wchar has changed from a 4-byte integer to a 2-byte integer. DDS_Wchar is now mapped to DDS_UnsignedShort instead of DDS_UnsignedLong. This change may lead to some compilation warnings when compiling old Connext DDS applications with libraries in Connext DDS 6.0.0 (and Connext DDS Micro 3.0.0) and higher. If so, you will need to fix these compilation warnings.

Wire interoperability with Connext DDS 5.x and lower (and Connext DDS Micro 2.4.x and lower) is not broken as long as you continue using the Extended CDR encoding version 1 data representation (see the Data Representation chapter in the RTI Connext DDS Core Libraries Getting Started Guide Addendum for Extensible Types), because the wire representation of a wchar and wstring is still the same.

2.4.6. Properties dds.type_consistency.ignore_member_names and dds.type_consistency.ignore_sequence_bounds have been deprecated

See information about this change in Section 3.1.4.1.

2.5. Transport Compatibility

2.5.1. Default shared memory locator has changed

This release changes the way Connext DDS detects if two different DomainParticipants can communicate over shared memory. In previous releases, the compatibility detection was based on both DomainParticipants having the same shared memory locator. In this release, the compatibility detection is based on checking if it is possible to attach to a shared memory segment compatible with Connext DDS. See “Improved shared memory transport compatibility detection” in What’s New in 6.0.0 for more information.

As a result of this change, Connext DDS 6 applications will not communicate over shared memory with older Connext DDS applications. You will need to take the following action, depending on what release you’re communicating with.

To communicate over shared memory with Connext DDS 5.3:

  • Configure the WIRE_PROTOCOL QoS: In Connext DDS 5.3 and Connext DDS 6, set the rtps_host_id field to DDS_RTPS_AUTO_ID in all the DomainParticipants running on the same host. In Connext DDS 6 DomainParticipants, set the rtps_auto_id_kind field to the same value used in the Connext DDS 5.3 application. If the Connext DDS 5.3 DomainParticipants are using an rtps_auto_id_kind field of DDS_RTPS_AUTO_ID_FROM_UUID, it is also required to set the dds.transport.shmem.builtin.use_530_from_uuid_locator property to TRUE for all the Connext DDS 6 DomainParticipants. (By default, it is set to FALSE.)
  • If the rtps_host_id field cannot be set to DDS_RTPS_AUTO_ID due to system restrictions, set the dds.transport.shmem.builtin.host_id property to the same value for all the DomainParticipants running on the same host. (That is, each DomainParticipant has to have the property set to the same value.)

To communicate over shared memory with Connext DDS 5.2 or older versions:

  • Configure the WIRE_PROTOCOL QoS: In Connext DDS 5.2 or older versions, set the rtps_host_id field to DDS_RTPS_AUTO_ID in all the DomainParticipants running on the same host. In Connext DDS 6 DomainParticipants, set the rtps_auto_id_kind field to DDS_RTPS_AUTO_ID_FROM_IP.
  • Another option, available only if the WIRE_PROTOCOL QoS’s rtps_host_id (in Connext DDS 5.2 or older) is set to a value different than DDS_RTPS_AUTO_ID: define the dds.transport.shmem.builtin.host_id property in Connext DDS 6 DomainParticipants with the same value as rtps_host_id in the WIRE_PROTOCOL QoS of the older version.

2.5.2. VxWorks shared-memory transport compatibility

Previously, applications could not communicate between kernel and RTP mode using the shared memory transport on 64-bit VxWorks® 6 systems. (This is not an issue for 64-bit VxWorks 7 systems.) This issue has been resolved.

As a result of this fix, applications built with older Connext DDS releases cannot communicate with applications built with this release if the communication uses shared memory on 64-bit VxWorks 6 systems and occurs between kernel and RTP mode. (This configuration is not a common use case.)

2.6. XML Compatibility

2.6.1. QoS Profile multiple inheritance

QoS Profile composition (also referred to as QoS Profile multiple inheritance) is an enhancement to the existing QoS Profile single inheritance mechanism, allowing a QoS Profile to be composed from multiple QoS Profiles. The following article makes some recommendations on how to use QoS Profile composition: QoS Profile Inheritance and Composition Guidance. Following these recommendations is strongly encouraged to avoid unexpected results.

2.6.2. XSD issues

See XSD-related regressions in Section 4.1.1.

2.7. Other Compatibility Issues

2.7.1. Behavior change when retrieving QoS using topic_name (when there are multiple matching QoSes)

When you have multiple matching QoSes of the same type (e.g., datawriter_qos), because either a topic_filter attribute is not provided or it is provided with “*”, the new behavior in 6.0.0 is for Connext DDS to return the first matching QoS. Previously, Connext DDS returned the last matching QoS.

For example, you could use a Connext DDS API that returns a QoS based on a specified topic_name value. In the C API, you could use a function like DDS::DomainParticipantFactory::get_datawriter_qos_from_profile_w_topic_name() to return a QoS based on a topic name.

Consider the following XML snippet:

<qos_profile name="String_Specified">
    <datawriter_qos name="A" topic_filter="A1_*">
          ...
    </datawriter_qos>
    <datawriter_qos name="B" topic_filter="B2_*">
          ...
    </datawriter_qos>
    <datawriter_qos name="C">
          ...
    </datawriter_qos>
    <datawriter_qos name="D">
          ...
    </datawriter_qos>
    <datawriter_qos name="E">
          ...
    </datawriter_qos>
</qos_profile>

Say that the above is your XML file, and you specify the topic_name “MyTopic”. Neither A nor B matches “MyTopic”, so Connext DDS has to choose one of the other QoSes (C, D, or E). Since C, D, and E have no specified topic_filter, any of them could be used as a matching candidate for “MyTopic”. Before 6.0.0, the API would have returned the “E” QoS, because E is the last matching QoS. This behavior has changed. Convention dictates that the first matching candidate should be used, not the last. Therefore, if there is no QoS that matches the topic_name, Connext DDS now gets the first candidate QoS value with topic_filter unspecified—in this case, C instead of E.

Now consider the following XML snippet:

<qos_profile name="String_NULL">
    <datawriter_qos name="A" topic_filter="A1_*">
          ...
    </datawriter_qos>
    <datawriter_qos name="B" topic_filter="B2_*">
          ...
    </datawriter_qos>
    <datawriter_qos name="C" topic_filter="*">
          ...
    </datawriter_qos>
    <datawriter_qos name="D" topic_filter="*">
          ...
    </datawriter_qos>
    <datawriter_qos name="E" topic_filter="*">
          ...
    </datawriter_qos>
</qos_profile>

Say that the above is your XML file, and you don’t specify a topic_name. Connext DDS cannot find a QoS in this file with an unspecified topic_filter; however, it can match with one of the “*” topic_filter attributes—but there are multiple such QoSes. Before 6.0.0, Connext DDS returned the “E” Qos (the last matching candidate value). Now in 6.0.0, Connext DDS returns the first candidate value, C.

As a result of this change in 6.0.0, you may see a different QoS returned than before, but only in cases where there are multiple matching QoSes to choose from. If you want the same behavior in 6.0.0 as before, change the order of the QoSes in your XML file. For instance, in the above examples, switch the C <datawriter_qos> with the E <datawriter_qos>.