From 3c41c453e30fcaf2fc96c252e149184caa3422e8 Mon Sep 17 00:00:00 2001 From: elianalf <62831776+elianalf@users.noreply.github.com> Date: Mon, 29 Jul 2024 12:19:57 +0200 Subject: [PATCH] Refs #21363: Apply suggestions Signed-off-by: elianalf <62831776+elianalf@users.noreply.github.com> --- UPGRADING.md | 60 +++++++++++++++++++++++++++++----------------------- 1 file changed, 33 insertions(+), 27 deletions(-) diff --git a/UPGRADING.md b/UPGRADING.md index 603c1a0170..31ad8bf368 100644 --- a/UPGRADING.md +++ b/UPGRADING.md @@ -1,4 +1,4 @@ -# Migration Guide to Fast DDS 3.0.x +# Migration Guide from Fast DDS v2 to Fast DDS v3 This document aims to help during the migration process from *eProsima Fast DDS* version 2.x to *Fast DDS v3.0.0*. The new release includes more changes than the included in this document, so refer to the [release notes](https://fast-dds.docs.eprosima.com/en/latest/notes/notes.html) for further information. @@ -11,21 +11,20 @@ The following sections describe in detail the possible changes that your project - [Library management](#library-management) - [Compatibility with Fast CDR](#compatibility-with-fast-cdr) - [Namespace migrations and changes](#namespace-migrations-and-changes) -- [Public headers migrated to *fastdds*](#fast-rtps-public-headers-migration-to-fast-dds) -- [Public headers moved to private](#headers-migrated-to-private) +- [Public headers migrated to *fastdds*](#public-headers-migrated-to-fastdds) +- [Public headers moved to private](#public-headers-moved-to-private) - [API changes](#api-changes) - [Struct, Enum, Variable](#struct-enum-variable) - [Examples](#examples) - ## Library management The below list expose the changes related to the package name, environment variables and other library usages. * The package has been renamed from `fastrtps` to `fastdds`. * XML profiles loading environment variable has been renamed to: `FASTDDS_DEFAULT_PROFILES_FILE`. -* The XML configuration file that Fast DDS searches by default to load the profiles has been renamed to `DEFAULT_FASTDDS_PROFILES.xml`. +* The XML configuration file that Fast DDS looks for by default to load the profiles has been renamed to `DEFAULT_FASTDDS_PROFILES.xml`. * XML Schema namespace in fastdds_profiles.xsd has been updated to http://www.eprosima.com. * CMake Windows file names have been changed: @@ -38,6 +37,7 @@ The below list expose the changes related to the package name, environment varia ## Compatibility with Fast CDR Fast DDS v3.x is only compatible with Fast CDR v2.x. +If you are not using Fast CDR as [third-party](https://fast-dds.docs.eprosima.com/en/latest/installation/configuration/cmake_options.html#third-party-libraries-options), please ensure updating your local dependencies. ## Namespace migrations and changes @@ -50,13 +50,13 @@ The following list contains the namespace changes and migrations: * `StatisticsEventKind::` references changed to `statistics::EventKind::`. * `Duration_t` and `c_TimeInfinite` reference were moved to `dds::`. * `ParticipantAttributes`, `PublisherAttributes`, `SubscriberAttributes`, `ReplierAttributes`, `RequesterAttributes` were moved to `xmlparser::`. -* `Time_hpp` references were divided into `dds::Time_t::` and `rtps::Time_t::`. - +* `Time_t.hpp` references were explicitly distingueshed between `dds::Time_t::` and `rtps::Time_t::`. ## Public headers migrated to *fastdds* All public header extensions have been changed to `.hpp`. -Also, the `fixed_size_string.hpp` feature has been migrated from Fast DDS package to Fast CDR. +Also, the `fixed_size_string.hpp` implementation has been migrated from Fast DDS package to Fast CDR. + All the headers in `include/fastrtps` were migrated to `include/fastdds`. In particular, the following list includes headers that have been relocated to different paths or whose implementations have been incorporated into other headers. @@ -82,7 +82,6 @@ In particular, the following list includes headers that have been relocated to d | fastrtps/transport/UDPTransportDescritpor.h | fastdds/rtps/transport/UDPTransportDescritpor.hpp | | fastrtps/transport/TCPTransportDescritpor.h | fastdds/rtps/transport/TCPTransportDescritpor.hpp | - ## Public headers moved to private The following list contains headers that were previously in the `include` folder and have been relocated to the `src/cpp` folder. @@ -135,15 +134,18 @@ Since they are no longer public, it is not possible to include them in external ## API changes -| Deprecated APIs | New APIs | +The table contains the list of API changes, showing the previous methods and the corresponding new ones introduced in Fast DDS v3. +The new API methods achieve the same functionality, even though the signature of the method is different from the deprecated one. + +| Deprecated methods | New methods | |----------------------------------|-------------------------------------| | xmlparser::XMLProfileManager::library_settings(`LibrarySettingsAttributes`&) | DomainParticipantFactory::get_instance()->set_library_settings(const `LibrarySettings`&) | | fill_discovery_data_from_cdr_message(`ReaderProxyData`&, `MonitorServiceStatusData`&) |fill_discovery_data_from_cdr_message(`SubscriptionBuiltinTopicData`&, `MonitorServiceStatusData`&) | | fill_discovery_data_from_cdr_message(`WriterProxyData`&, `MonitorServiceStatusData`&) | fill_discovery_data_from_cdr_message(`PublicationBuiltinTopicData`&,`MonitorServiceStatusData`&) | | fill_discovery_data_from_cdr_message(`ParticipantProxyData`&, `MonitorServiceStatusData`&) | fill_discovery_data_from_cdr_message(`ParticipantBuiltinTopicData`&,`MonitorServiceStatusData`&) | -| on_participant_discovery(`DomainParticipant`*, `ParticipantDiscoveryInfo`&&, bool) |on_participant_discovery(`DomainParticipant`*, `ParticipantDiscoveryStatus`, `ParticipantBuiltinTopicData`&, `should_be_ignored`) | -| on_subscriber_discovery(`DomainParticipant`*, `ReaderDiscoveryInfo`&&, bool) | on_data_reader_discovery(`DomainParticipant`*, `ReaderDiscoveryStatus`, `SubscriptionBuiltinTopicData`&, `should_be_ignored`) | -| on_publisher_discovery(`DomainParticipant`*, `WriterDiscoveryInfo`&&, bool) | on_data_writer_discovery(`DomainParticipant`*, `WriterDiscoveryStatus`, `PublicationBuiltinTopicData`&, `should_be_ignored`) | +| on_participant_discovery(`DomainParticipant`*, `ParticipantDiscoveryInfo`&&, bool) |on_participant_discovery(`DomainParticipant`*, `ParticipantDiscoveryStatus`, `ParticipantBuiltinTopicData`&, bool&) | +| on_subscriber_discovery(`DomainParticipant`*, `ReaderDiscoveryInfo`&&, bool) | on_data_reader_discovery(`DomainParticipant`*, `ReaderDiscoveryStatus`, `SubscriptionBuiltinTopicData`&, bool&) | +| on_publisher_discovery(`DomainParticipant`*, `WriterDiscoveryInfo`&&, bool) | on_data_writer_discovery(`DomainParticipant`*, `WriterDiscoveryStatus`, `PublicationBuiltinTopicData`&, bool&) | | onReaderDiscovery(`RTPSParticipant`*, `ReaderDiscoveryInfo`&&, bool) | on_reader_discovery(`RTPSParticipant`*, `ReaderDiscoveryStatus`, `SubscriptionBuiltinTopicData`&, bool&) | | onWriterDiscovery(`RTPSParticipant`*, `WriterDiscoveryInfo`&&, bool) | on_writer_discovery(`RTPSParticipant`*, `WriterDiscoveryStatus`, `PublicationBuiltinTopicData`&, bool&) | | onParticipantDiscovery(`RTPSParticipant`*, `ParticipantDiscoveryInfo`&&, bool) | on_participant_discovery(`RTPSParticipant`*, `ParticipantDiscoveryStatus`, `ParticipantBuiltinTopicData`&, bool&) | @@ -152,7 +154,6 @@ Since they are no longer public, it is not possible to include them in external | XMLProfileManager::loadXMLFile(string) | load_XML_profiles_file(string&) | | XMLProfileManager::loadXMLString(const char*, size_t) | load_XML_profiles_string(const char*, size_t) | | XMLProfileManager::fillParticipantAttributes(const string&, `ParticipantAttributes`&, bool) | get_participant_qos_from_profile(string&, `DomainParticipantQos`&) | -getDynamicTypeByName |DynamicTypeBuilder XMLProfileManager::getDynamicTypeByName(string&) | get_dynamic_type_builder_from_xml_by_name(string&, `DynamicTypeBuilder::_ref_type`&) | | XMLProfileManager::fillRequesterAttributes(string&, RequesterAttributes&) | get_requester_qos_from_profile(string&, RequesterQos&) | | XMLParser::getXMLThroughputController(`tinyxml2::XMLElement`*, `ThroughputControllerDescriptor`&, uint8_t) | XMLParser::getXMLFlowControllerDescriptorList(`tinyxml2::XMLElement`*, `FlowControllerDescriptorList`&, uint8_t) | @@ -202,10 +203,10 @@ getDynamicTypeByName | DynamicPubSubType::getKey(const void* const, `InstanceHand`*, bool) | DynamicPubSubType::compute_key(const void* const, `InstanceHand`&, bool) | | DynamicPubSubType::getSerializedSizeProvider(const void* const, `DataRepresentationId_t`) | DynamicPubSubType::calculate_serialized_size(const void* const, `DataRepresentationId_t`) | - - ## Struct, Enum, Variable +The following list shows the changes of the struct, enums and variables that have been modified. + * Extend `SubscriptionBuiltinTopicData` with additional fields to mimic those of `ReaderProxyData`. * Extend `PublicationBuiltinTopicData` with additional fields to mimic those of `WriterProxyData`. * Extend `ParticipantBuiltinTopicData` adding the the Product version and additional fields to mimic those of `ParticipantProxyData`. @@ -223,21 +224,27 @@ getDynamicTypeByName * `m_isGetKeyDefined` is `is_compute_key_provided` * `m_topicDataTypeName` is `topic_data_typename_` - ## Examples +All the examples have been refactored to follow the same structure: +* File names, guards, and classes follow new format. +* Detailed and well-formed README.md with example explanation. +* Example structured in applications, stopped by `SIGTERM` signal. + ### Hello World Refactor the HelloWorld example with the current new example format. In this hello world example, the key changes are: -* Removed --env option and set that environment behavior as default. -* Added subscriber waitsets class and its usage. -* Provided XML profiles examples that target several scenarios (e.g.,SampleConfig_Controller, Events, Multimedia). +* The XML profile is loaded from the environment (if defined), and the `--env` CLI option has been removed. +* Add a subscriber implementing the waitsets mechanism. +* Provide XML profiles examples targeting several scenarios (e.g., SampleConfig_Controller, Events, Multimedia). ### X-Types Examples -In this X-Types example, a type is defined at runtime on the publisher side using the Dynamic Types API, and the subscriber discovers the type, creates a reader for it, and prints the received data. This example is type compatible with the Hello World example, and a compatibility test has been added for this. +In this X-Types example, a type is defined at runtime on the publisher side using the Dynamic Types API. +The subscriber discovers the type, creates a reader for it, and prints the received data. +This example is type compatible with the Hello World example. ### Configuration -In this configuration example, the key changes are: +In the configuration example, the key changes are: * Included LargeData as an option (builtin transport argument). * Included all previous QoS examples: * Deadline @@ -266,16 +273,15 @@ In this delivery mechanisms example, the key changes are: ### Discovery Server Refactor the DiscoveryServerExample example with the current new example format. -This refactors the DiscoveryServerExample to the new example format. It also adds proper tests for the examples testing automation. ### Flow Controller Refactor the FlowControlExample example with the current new example format. In this Flow Controller example, the key changes are: -* Publishers continuously send samples. The user can set the number of samples to send. +* Publishers continuously send samples. The user can set the number of samples to send. * User can set the following QoS and properties for the Flow Controller: * Scheduler policy used by the flow controller. * Maximum number of bytes to be sent to the network per period. - * Period of time in milliseconds during which the flow controller is allowed to send the maximum number of bytes per period. + * Period of time in milliseconds during which the flow controller is allowed to send the maximum number of bytes per period. * Property fastdds.sfc.priority. * Property fastdds.sfc.bandwidth_reservation. @@ -287,8 +293,8 @@ Refactor the Static EDP Discovery example with the new example format. ### Security Refactor the SecureHelloWorld example with the current new example format. -A security folder created in examples with a modified version of hello world, supporting security plugins. ### RTPS Entities Refactor the rtps/Registered example with the current new example format. -This RTPS example demonstrates a basic RTPS deployment. The main change is that serialization and deserialization are done with overload methods from fastcdr. +This RTPS example demonstrates a basic RTPS deployment. +The main change is that serialization and deserialization are done with overload methods from fastcdr.