From 60557c485012bc44c717c59d18c06cbc124feba7 Mon Sep 17 00:00:00 2001 From: Eduardo Ponz Segrelles Date: Tue, 21 Nov 2023 08:47:10 +0100 Subject: [PATCH] ThreadSettings documentation (#590) * Refs #19645. Fix cardinality and add TCP accept thread. Signed-off-by: Miguel Company Signed-off-by: EduPonz * Refs #19645. Add OS thread name column. Signed-off-by: Miguel Company Signed-off-by: EduPonz * Refs #19645. Add basic section for ThreadSettings. Signed-off-by: Miguel Company Signed-off-by: EduPonz * Refs #19645: Reference ThreadSettings section in execution model Signed-off-by: EduPonz * Refs #19645: DomainParticipantFactory ThreadSettings configuration Signed-off-by: EduPonz * Refs #19645: DomainParticipant ThreadSettings configuration Signed-off-by: EduPonz * Refs #19645: PortBasedTransportDescriptor ThreadSettings configuration Signed-off-by: EduPonz * Refs #19645: SHM ThreadSettings configuration Signed-off-by: EduPonz * Refs #19645: FlowControllerDescriptor ThreadSettings configuration Signed-off-by: EduPonz * Refs #19645: DataReader ThreadSettings configuration Signed-off-by: EduPonz * Refs #19645: Log ThreadSettings configuration Signed-off-by: EduPonz * Refs #19645: Apply Miguel's suggestions Signed-off-by: EduPonz * Refs #19645: Apply Miguel's suggestions 2 Signed-off-by: EduPonz * Refs #19645: Add missing TCPTransportDescriptor thread settings Signed-off-by: EduPonz * Refs #19645: Add missing includes Signed-off-by: EduPonz --------- Signed-off-by: Miguel Company Signed-off-by: EduPonz Co-authored-by: Miguel Company --- code/DDSCodeTester.cpp | 107 +++- .../Examples/C++/DDSHelloWorld/CMakeLists.txt | 4 - .../DDSHelloWorld/src/HelloWorldPublisher.cpp | 9 +- .../src/HelloWorldSubscriber.cpp | 9 +- code/XMLTester.xml | 605 ++++++++++++------ code/XMLTesterExample.xml | 128 +++- code/XMLTesterSkipValidation.xml | 4 + docs/03-exports/aliases-api.include | 21 + docs/03-exports/aliases.include | 2 + .../rtps/attributes/ThreadSettings.rst | 8 + .../rtps/attributes/attributes.rst | 1 + .../transport_generic_interfaces.rst | 1 + .../port_based_transport_descriptor.rst | 8 + .../core/policy/eprosimaExtensions.rst | 170 ++++- .../domainParticipant/domainParticipant.rst | 57 +- .../domainParticipantFactory.rst | 20 +- .../simple_app/includes/publisher.rst | 22 +- .../simple_app/includes/subscriber.rst | 20 +- .../library_overview/includes/exec_model.rst | 79 ++- docs/fastdds/logging/logging_thread.rst | 2 + .../transport/shared_memory/shared_memory.rst | 79 ++- docs/fastdds/transport/tcp/tcp.rst | 29 +- docs/fastdds/transport/udp/udp.rst | 12 +- .../use_cases/large_data/large_data.rst | 30 +- docs/fastdds/xml_configuration/common.rst | 59 ++ .../xml_configuration/domainparticipant.rst | 22 +- .../domainparticipantfactory.rst | 86 +++ docs/fastdds/xml_configuration/log.rst | 41 +- .../xml_configuration/xml_configuration.rst | 1 + 29 files changed, 1229 insertions(+), 407 deletions(-) create mode 100644 docs/fastdds/api_reference/rtps/attributes/ThreadSettings.rst create mode 100644 docs/fastdds/api_reference/transport/transport_generic_interfaces/port_based_transport_descriptor.rst create mode 100644 docs/fastdds/xml_configuration/domainparticipantfactory.rst diff --git a/code/DDSCodeTester.cpp b/code/DDSCodeTester.cpp index 76a7a90ec..3555e409e 100644 --- a/code/DDSCodeTester.cpp +++ b/code/DDSCodeTester.cpp @@ -1,54 +1,52 @@ +#include +#include +#include + +#include + #include #include -#include #include -#include +#include #include +#include +#include +#include +#include +#include +#include +#include #include -#include #include -#include #include -#include -#include -#include -#include +#include #include #include #include +#include #include -#include +#include +#include +#include #include +#include #include -#include - -#include -#include -#include -#include -#include -#include -#include - +#include +#include +#include +#include #include -#include -#include #include #include -#include -#include -#include - +#include +#include #include #include #include - +#include +#include #include - -#include - -#include -#include +#include using namespace eprosima::fastdds::dds; @@ -3945,6 +3943,9 @@ void dds_qos_examples() // unique for the current machine datasharing.automatic(); + // [OPTIONAL] ThreadSettings for listening thread + datasharing.data_sharing_listener_thread(eprosima::fastdds::rtps::ThreadSettings{-1, 0, 0, -1}); + //!-- } @@ -4083,17 +4084,30 @@ void dds_qos_examples() //!-- } + { + using namespace eprosima::fastdds::rtps; + //DDS_CHANGE_THREAD_SETTINGS + ThreadSettings thread_settings; + thread_settings.scheduling_policy = 2; + thread_settings.priority = 10; + thread_settings.affinity = 4; + thread_settings.stack_size = 2000; + //!-- + } + { //DDS_CHANGE_TRANSPORT_CONFIG_QOS TransportConfigQos transport; - //Add new transport to the list of user transports + // Add new transport to the list of user transports std::shared_ptr descriptor = std::make_shared(); descriptor->sendBufferSize = 9126; descriptor->receiveBufferSize = 9126; transport.user_transports.push_back(descriptor); - //Set use_builtin_transports to false + // Set use_builtin_transports to false transport.use_builtin_transports = false; + // [OPTIONAL] Set ThreadSettings for the builtin transports reception threads + transport.builtin_transports_reception_threads_ = eprosima::fastdds::rtps::ThreadSettings{2, 2, 2, 2}; //!-- } @@ -4354,6 +4368,9 @@ void log_examples() // Stop the loggin thread and free its resources. Log::KillThread(); + + // Configure ThreadSettings for the logging thread + Log::SetThreadConfig(eprosima::fastdds::rtps::ThreadSettings{-1, 0, 0, -1}); //!-- } @@ -4556,6 +4573,10 @@ void dds_transport_examples () udp_transport->receiveBufferSize = 9216; udp_transport->non_blocking_send = true; + // [OPTIONAL] ThreadSettings configuration + udp_transport->default_reception_threads(eprosima::fastdds::rtps::ThreadSettings{2, 2, 2, 2}); + udp_transport->set_thread_config_for_port(12345, eprosima::fastdds::rtps::ThreadSettings{3, 3, 3, 3}); + // Link the Transport Layer to the Participant. qos.transport().user_transports.push_back(udp_transport); @@ -4573,6 +4594,12 @@ void dds_transport_examples () tcp_transport->add_listener_port(5100); tcp_transport->set_WAN_address("80.80.99.45"); + // [OPTIONAL] ThreadSettings configuration + tcp_transport->default_reception_threads(eprosima::fastdds::rtps::ThreadSettings{-1, 0, 0, -1}); + tcp_transport->set_thread_config_for_port(12345, eprosima::fastdds::rtps::ThreadSettings{-1, 0, 0, -1}); + tcp_transport->keep_alive_thread = eprosima::fastdds::rtps::ThreadSettings{-1, 0, 0, -1}; + tcp_transport->accept_thread = eprosima::fastdds::rtps::ThreadSettings{-1, 0, 0, -1}; + // Link the Transport Layer to the Participant. qos.transport().user_transports.push_back(tcp_transport); @@ -4602,6 +4629,12 @@ void dds_transport_examples () auto tcp_transport = std::make_shared(); qos.transport().user_transports.push_back(tcp_transport); + // [OPTIONAL] ThreadSettings configuration + tcp_transport->default_reception_threads(eprosima::fastdds::rtps::ThreadSettings{-1, 0, 0, -1}); + tcp_transport->set_thread_config_for_port(12345, eprosima::fastdds::rtps::ThreadSettings{-1, 0, 0, -1}); + tcp_transport->keep_alive_thread = eprosima::fastdds::rtps::ThreadSettings{-1, 0, 0, -1}; + tcp_transport->accept_thread = eprosima::fastdds::rtps::ThreadSettings{-1, 0, 0, -1}; + // Set initial peers. eprosima::fastrtps::rtps::Locator_t initial_peer_locator; initial_peer_locator.kind = LOCATOR_KIND_TCPv4; @@ -4623,6 +4656,11 @@ void dds_transport_examples () // Create a descriptor for the new transport. std::shared_ptr shm_transport = std::make_shared(); + // [OPTIONAL] ThreadSettings configuration + shm_transport->default_reception_threads(eprosima::fastdds::rtps::ThreadSettings{-1, 0, 0, -1}); + shm_transport->set_thread_config_for_port(12345, eprosima::fastdds::rtps::ThreadSettings{-1, 0, 0, -1}); + shm_transport->dump_thread(eprosima::fastdds::rtps::ThreadSettings{-1, 0, 0, -1}); + // Link the Transport Layer to the Participant. qos.transport().user_transports.push_back(shm_transport); //!-- @@ -5078,6 +5116,9 @@ void dds_usecase_examples() flow_control_300k_per_sec->max_bytes_per_period = 300 * 1000; flow_control_300k_per_sec->period_ms = 1000; + // [OPTIONAL] Configure sender thread settings + flow_control_300k_per_sec->sender_thread = eprosima::fastdds::rtps::ThreadSettings{-1, 0, 0, -1}; + // Register flow controller on participant DomainParticipantQos participant_qos; participant_qos.flow_controllers().push_back(flow_control_300k_per_sec); diff --git a/code/Examples/C++/DDSHelloWorld/CMakeLists.txt b/code/Examples/C++/DDSHelloWorld/CMakeLists.txt index 5d0523502..0611d3f94 100644 --- a/code/Examples/C++/DDSHelloWorld/CMakeLists.txt +++ b/code/Examples/C++/DDSHelloWorld/CMakeLists.txt @@ -14,10 +14,6 @@ cmake_minimum_required(VERSION 3.22) - - - - project(DDSHelloWorld) # Find requirements diff --git a/code/Examples/C++/DDSHelloWorld/src/HelloWorldPublisher.cpp b/code/Examples/C++/DDSHelloWorld/src/HelloWorldPublisher.cpp index 9f4c94bac..07cbb376b 100644 --- a/code/Examples/C++/DDSHelloWorld/src/HelloWorldPublisher.cpp +++ b/code/Examples/C++/DDSHelloWorld/src/HelloWorldPublisher.cpp @@ -19,12 +19,15 @@ #include "HelloWorldPubSubTypes.h" -#include +#include +#include + #include -#include -#include +#include #include #include +#include +#include using namespace eprosima::fastdds::dds; diff --git a/code/Examples/C++/DDSHelloWorld/src/HelloWorldSubscriber.cpp b/code/Examples/C++/DDSHelloWorld/src/HelloWorldSubscriber.cpp index 4a0b6e76c..3fdf6d13a 100644 --- a/code/Examples/C++/DDSHelloWorld/src/HelloWorldSubscriber.cpp +++ b/code/Examples/C++/DDSHelloWorld/src/HelloWorldSubscriber.cpp @@ -19,14 +19,17 @@ #include "HelloWorldPubSubTypes.h" -#include +#include +#include + #include -#include -#include +#include #include #include #include #include +#include +#include using namespace eprosima::fastdds::dds; diff --git a/code/XMLTester.xml b/code/XMLTester.xml index 51531d9e6..1ee93c7cb 100644 --- a/code/XMLTester.xml +++ b/code/XMLTester.xml @@ -107,29 +107,44 @@ <--> CONF-QOS-DATASHARING<--> - - - - AUTOMATIC - - 123 - 098 - - - - + + + + + AUTOMATIC + + 123 + 098 + + + + - - - - AUTOMATIC - - 123 - 098 - - - - + + + + AUTOMATIC + + 123 + 098 + + + -1 + 0 + 0 + -1 + + + + + + + +<--> <--> CONF-QOS-PARTITIONS<--> @@ -199,6 +214,34 @@ <--> +CONF-COMMON-THREAD-SETTINGS<--> + + + + +<--> + + + + + + <--> + 2 + 10 + 4 + 2000 + + + <--> + + + + + + +<--> +<--> + CONF-COMMON-TRANSPORT-SETTING<--> @@ -222,62 +265,98 @@ CONF-UDP-TRANSPORT-SETTING<--> - - - udp_transport - UDPv4 - 9216 - 9216 - true - - - - - - + + udp_transport - - false - - + UDPv4 + 9216 + 9216 + true + + 2 + 2 + 2 + 2 + + + + 3 + 3 + 3 + 3 + + + + + + + + + udp_transport + + false + + + + + +<--> <--> CONF-TCP-TRANSPORT-SETTING-SERVER<--> - - - tcp_server_transport - TCPv4 - - 5100 - - 80.80.99.45 - - - - - - + + tcp_server_transport - - false - - - - 80.80.99.45 -
80.80.99.45
- 5100 - 5100 - - - - - + TCPv4 + + 5100 + + 80.80.99.45 + + + -1 + 0 + 0 + -1 + + + + -1 + 0 + 0 + -1 + + + + -1 + 0 + 0 + -1 + + + -1 + 0 + 0 + -1 + + + + + + + + tcp_server_transport + + false + 80.80.99.45 @@ -286,66 +365,138 @@ 5100 - - - - + + + + + + 80.80.99.45 +
80.80.99.45
+ 5100 + 5100 + + + + + + + + + +<--> <--> CONF-TCP-TRANSPORT-SETTING-CLIENT<--> - - - tcp_client_transport - TCPv4 - - - - - - + + tcp_client_transport - - false - - - - -
80.80.99.45
- 5100 - 5100 - - - - - - + TCPv4 + + + -1 + 0 + 0 + -1 + + + + -1 + 0 + 0 + -1 + + + + -1 + 0 + 0 + -1 + + + -1 + 0 + 0 + -1 + + + + + + + + tcp_client_transport + + false + + + + +
80.80.99.45
+ 5100 + 5100 + + + + + + + + + +<--> <--> CONF-SHM-TRANSPORT-SETTING<--> - - - - shm_transport - SHM - - - - - - - + + + shm_transport - - - + SHM + + -1 + 0 + 0 + -1 + + + + -1 + 0 + 0 + -1 + + + + -1 + 0 + 0 + -1 + + + + + + + + + shm_transport + + + + + + +<--> <--> CONF-SHM-TRANSPORT-DISABLE-BUILTIN-TRANSPORTS<--> @@ -868,97 +1019,165 @@ <--> -XML-PARTICIPANT<--> +XML-PARTICIPANT-FACTORY<--> - - 4 - - DomainParticipant Name - - - - - - 7400 -
192.168.1.41
- - - + + + + true + + + -1 + 0 + 0 + -1 + + + -1 + 0 + 0 + -1 + + + + +<--> - - - - - 7400 -
192.168.2.41
- - - +XML-PARTICIPANT<--> + + + 4 + + DomainParticipant Name - - - -
100.100.100.10
- 23456 - - + + + + + 7400 +
192.168.1.41
+ + + - true + + + + + 7400 +
192.168.2.41
+ + + - 8192 + + + +
100.100.100.10
+ 23456 + + - 8192 + true - - - + 8192 - - 7400 - 200 - 10 - 0 - 1 - 2 - 3 - + 8192 - 99 + + + - - TransportId1 - TransportId2 - + + 7400 + 200 + 10 + 0 + 1 + 2 + 3 + - false + 99 - - - - - Property1Name - Property1Value - false - - - + + TransportId1 + TransportId2 + - - - + false - - 3.4.7.0.C - + + + + + Property1Name + Property1Value + false + + + - 72.61.73.70.66.61.72.6d.74.65.73.74 - - + + + + + + 3.4.7.0.C + + + 72.61.73.70.66.61.72.6d.74.65.73.74 + + + -1 + 0 + 0 + -1 + + + + -1 + 0 + 0 + -1 + + + + -1 + 0 + 0 + -1 + + + + -1 + 0 + 0 + -1 + + + + -1 + 0 + 0 + -1 + + + <--> @@ -3569,6 +3788,16 @@ true + + + + -1 + 0 + 0 + -1 + @@ -59,19 +73,73 @@ 250 false 5101 + + -1 + 0 + 0 + -1 + + + + -1 + 0 + 0 + -1 + + SHM_SAMPLE_DESCRIPTOR - SHM - 524288 - 1048576 - 1024 - 250 - test_file.dump + SHM + 524288 + 1048576 + 1024 + 250 + test_file.dump + + -1 + 0 + 0 + -1 + + + + -1 + 0 + 0 + -1 + + + + -1 + 0 + 0 + -1 + + + + + true + + + -1 + 0 + 0 + -1 + + + -1 + 0 + 0 + -1 + + + + 4 @@ -374,6 +442,41 @@ true + + + -1 + 0 + 0 + -1 + + + + -1 + 0 + 0 + -1 + + + + -1 + 0 + 0 + -1 + + + + -1 + 0 + 0 + -1 + + + + -1 + 0 + 0 + -1 + @@ -591,6 +694,12 @@ 0 11 + + -1 + 0 + 0 + -1 + @@ -790,6 +899,13 @@ TRUE + + + -1 + 0 + 0 + -1 + diff --git a/code/XMLTesterSkipValidation.xml b/code/XMLTesterSkipValidation.xml index 11d9edc6d..ae2482ca8 100644 --- a/code/XMLTesterSkipValidation.xml +++ b/code/XMLTesterSkipValidation.xml @@ -2,6 +2,10 @@ + + + + diff --git a/docs/03-exports/aliases-api.include b/docs/03-exports/aliases-api.include index 9c2b2d740..0aa94213c 100644 --- a/docs/03-exports/aliases-api.include +++ b/docs/03-exports/aliases-api.include @@ -162,6 +162,8 @@ .. |DomainParticipantFactoryQos-api| replace:: :cpp:class:`DomainParticipantFactoryQos` .. |DomainParticipantFactoryQos::entity_factory-api| replace:: :cpp:func:`entity_factory()` +.. |DomainParticipantFactoryQos::shm_watchdog_thread-api| replace:: :cpp:func:`shm_watchdog_thread()` +.. |DomainParticipantFactoryQos::file_watch_threads-api| replace:: :cpp:func:`file_watch_threads()` .. |DomainParticipantListener-api| replace:: :cpp:class:`DomainParticipantListener` .. |DomainParticipantListener::on_participant_discovery-api| replace:: :cpp:func:`on_participant_discovery()` @@ -181,6 +183,10 @@ .. |DomainParticipantQos::transport-api| replace:: :cpp:func:`transport()` .. |DomainParticipantQos::user_data-api| replace:: :cpp:func:`user_data()` .. |DomainParticipantQos::wire_protocol-api| replace:: :cpp:func:`wire_protocol()` +.. |DomainParticipantQos::builtin_controllers_sender_thread-api| replace:: :cpp:func:`builtin_controllers_sender_thread()` +.. |DomainParticipantQos::timed_events_thread-api| replace:: :cpp:func:`timed_events_thread()` +.. |DomainParticipantQos::discovery_server_thread-api| replace:: :cpp:func:`discovery_server_thread()` +.. |DomainParticipantQos::security_log_thread-api| replace:: :cpp:func:`security_log_thread()` .. |DomainParticipants-api| replace:: :cpp:class:`DomainParticipants ` .. |FlowControllerDescriptor-api| replace:: :cpp:class:`FlowControllerDescriptor` @@ -188,6 +194,7 @@ .. |FlowControllerDescriptor::scheduler-api| replace:: :cpp:member:`scheduler` .. |FlowControllerDescriptor::max_bytes_per_period-api| replace:: :cpp:member:`max_bytes_per_period` .. |FlowControllerDescriptor::period_ms-api| replace:: :cpp:member:`period_ms` +.. |FlowControllerDescriptor::sender_thread-api| replace:: :cpp:member:`sender_thread` .. |FlowControllerSchedulerPolicy-api| replace:: :cpp:enum:`FlowControllerSchedulerPolicy` .. |FIFO_SCHED_POLICY-api| replace:: :cpp:enumerator:`FIFO` @@ -346,6 +353,7 @@ .. |DataSharingQosPolicy::auto-api| replace:: :cpp:func:`automatic()` .. |DataSharingQosPolicy::on-api| replace:: :cpp:func:`on()` .. |DataSharingQosPolicy::off-api| replace:: :cpp:func:`off()` +.. |DataSharingQosPolicy::data_sharing_listener_thread-api| replace:: :cpp:func:`data_sharing_listener_thread()` .. |DurabilityServiceQosPolicy-api| replace:: :cpp:class:`DurabilityServiceQosPolicy` .. |service_cleanup_delay-api| replace:: :cpp:member:`service_cleanup_delay` @@ -577,6 +585,7 @@ .. |TransportConfigQos::use_builtin_transports-api| replace:: :cpp:member:`use_builtin_transports` .. |TransportConfigQos::send_socket_buffer_size-api| replace:: :cpp:member:`send_socket_buffer_size` .. |TransportConfigQos::listen_socket_buffer_size-api| replace:: :cpp:member:`listen_socket_buffer_size` +.. |TransportConfigQos::builtin_transports_reception_threads-api| replace:: :cpp:func:`builtin_transports_reception_threads()` .. |TransportDescriptorInterface-api| replace:: :cpp:struct:`TransportDescriptorInterface` .. |TransportDescriptorInterface::maxMessageSize-api| replace:: :cpp:member:`maxMessageSize` @@ -592,6 +601,9 @@ .. |ChainingTransport::send-api| replace:: :cpp:func:`send()` .. |ChainingTransport::receive-api| replace:: :cpp:func:`receive()` +.. |PortBasedTransportDescriptor::default_reception_threads-api| replace:: :cpp:func:`default_reception_threads` +.. |PortBasedTransportDescriptor::reception_threads-api| replace:: :cpp:func:`reception_threads` + .. |SocketTransportDescriptor::sendBufferSize-api| replace:: :cpp:var:`sendBufferSize` .. |SocketTransportDescriptor::receiveBufferSize-api| replace:: :cpp:var:`receiveBufferSize` .. |SocketTransportDescriptor::interfaceWhiteList-api| replace:: :cpp:var:`interfaceWhiteList` @@ -613,6 +625,8 @@ .. |TCPTransportDescriptor::calculate_crc-api| replace:: :cpp:var:`calculate_crc` .. |TCPTransportDescriptor::check_crc-api| replace:: :cpp:var:`check_crc` .. |TCPTransportDescriptor::apply_security-api| replace:: :cpp:var:`apply_security` +.. |TCPTransportDescriptor::keep_alive_thread-api| replace:: :cpp:var:`keep_alive_thread` +.. |TCPTransportDescriptor::accept_thread-api| replace:: :cpp:var:`accept_thread` .. |TCPTransportDescriptor::tls_config-api| replace:: :cpp:var:`tls_config` .. |TCPTransportDescriptor::TLSConfig-api| replace:: :cpp:struct:`TLSConfig` @@ -665,6 +679,7 @@ .. |SharedMemTransportDescriptor::port_queue_capacity-api| replace:: :cpp:func:`port_queue_capacity()` .. |SharedMemTransportDescriptor::healthy_check_timeout_ms-api| replace:: :cpp:func:`healthy_check_timeout_ms()` .. |SharedMemTransportDescriptor::rtps_dump_file-api| replace:: :cpp:func:`rtps_dump_file()` +.. |SharedMemTransportDescriptor::dump_thread-api| replace:: :cpp:func:`dump_thread()` .. |TypeConsistencyQos-api| replace:: :cpp:class:`TypeConsistencyQos` .. |TypeConsistencyQos::type_consistency-api| replace:: :cpp:member:`type_consistency` @@ -901,6 +916,7 @@ .. |Log::Flush-api| replace:: :cpp:func:`Log::Flush() ` .. |Log::KillThread-api| replace:: :cpp:func:`Log::KillThread() ` +.. |Log::SetThreadConfig-api| replace:: :cpp:func:`Log::SetThreadConfig() ` .. |StdoutErrConsumer::stderr_threshold-api| replace:: :cpp:func:`StdoutErrConsumer::stderr_threshold() ` @@ -976,3 +992,8 @@ .. |WriteParams-api| replace:: :cpp:class:`WriteParams ` .. |WriteParams-sample_identity-api| replace:: :cpp:func:`sample_identity() ` .. |WriteParams-related_sample_identity-api| replace:: :cpp:func:`related_sample_identity() ` + +.. |ThreadSettings::scheduling_policy-api| replace:: :cpp:member:`scheduling_policy` +.. |ThreadSettings::priority-api| replace:: :cpp:member:`priority` +.. |ThreadSettings::affinity-api| replace:: :cpp:member:`affinity` +.. |ThreadSettings::stack_size-api| replace:: :cpp:member:`stack_size` diff --git a/docs/03-exports/aliases.include b/docs/03-exports/aliases.include index 906eec5a9..eed1b2adb 100644 --- a/docs/03-exports/aliases.include +++ b/docs/03-exports/aliases.include @@ -127,3 +127,5 @@ .. |StatisticsDomainParticipant| replace:: :ref:`Statistics Domain Participant` .. |StatisticsQosTroubleshooting| replace:: :ref:`Statistics QoS Troubleshooting` + +.. |ThreadSettings| replace:: :ref:`ThreadSettings` diff --git a/docs/fastdds/api_reference/rtps/attributes/ThreadSettings.rst b/docs/fastdds/api_reference/rtps/attributes/ThreadSettings.rst new file mode 100644 index 000000000..1ad88e953 --- /dev/null +++ b/docs/fastdds/api_reference/rtps/attributes/ThreadSettings.rst @@ -0,0 +1,8 @@ +.. rst-class:: api-ref + +ThreadSettings +-------------- + +.. doxygenstruct:: eprosima::fastdds::rtps::ThreadSettings + :project: FastDDS + :members: diff --git a/docs/fastdds/api_reference/rtps/attributes/attributes.rst b/docs/fastdds/api_reference/rtps/attributes/attributes.rst index 6dc7acaa9..0b1349c7a 100644 --- a/docs/fastdds/api_reference/rtps/attributes/attributes.rst +++ b/docs/fastdds/api_reference/rtps/attributes/attributes.rst @@ -26,6 +26,7 @@ Attributes /fastdds/api_reference/rtps/attributes/RTPSWriterPublishMode /fastdds/api_reference/rtps/attributes/SendBuffersAllocationAttributes /fastdds/api_reference/rtps/attributes/SimpleEDPAttributes + /fastdds/api_reference/rtps/attributes/ThreadSettings /fastdds/api_reference/rtps/attributes/TypeLookupSettings /fastdds/api_reference/rtps/attributes/VariableLengthDataLimits /fastdds/api_reference/rtps/attributes/WriterAttributes diff --git a/docs/fastdds/api_reference/transport/transport_generic_interfaces.rst b/docs/fastdds/api_reference/transport/transport_generic_interfaces.rst index 05a5ee64a..754d594de 100644 --- a/docs/fastdds/api_reference/transport/transport_generic_interfaces.rst +++ b/docs/fastdds/api_reference/transport/transport_generic_interfaces.rst @@ -6,4 +6,5 @@ Transport Generic Interfaces /fastdds/api_reference/transport/transport_generic_interfaces/transport_descriptor_interface.rst /fastdds/api_reference/transport/transport_generic_interfaces/transport_interface.rst /fastdds/api_reference/transport/transport_generic_interfaces/transport_receiver_interface.rst + /fastdds/api_reference/transport/transport_generic_interfaces/port_based_transport_descriptor.rst /fastdds/api_reference/transport/transport_generic_interfaces/socket_transport_descriptor.rst diff --git a/docs/fastdds/api_reference/transport/transport_generic_interfaces/port_based_transport_descriptor.rst b/docs/fastdds/api_reference/transport/transport_generic_interfaces/port_based_transport_descriptor.rst new file mode 100644 index 000000000..885d24a19 --- /dev/null +++ b/docs/fastdds/api_reference/transport/transport_generic_interfaces/port_based_transport_descriptor.rst @@ -0,0 +1,8 @@ +.. _api_port_based_transport_descriptor: + +PortBasedTransportDescriptor +---------------------------- + +.. doxygenclass:: eprosima::fastdds::rtps::PortBasedTransportDescriptor + :project: FastDDS + :members: diff --git a/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst b/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst index 3817f82de..e9fd2cb60 100644 --- a/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst +++ b/docs/fastdds/dds_layer/core/policy/eprosimaExtensions.rst @@ -28,17 +28,34 @@ Please, see :ref:`datasharing-delivery` for a description of the data-sharing de List of QoS Policy data members: -+-------------------------+------------------------+-------------------------------------------+---------------+ -| Data Member | Type | Accessor | Default Value | -+=========================+========================+===========================================+===============+ -| Data-sharing kind | :ref:`datasharingkind` | |DataSharingQosPolicy::kind-api| | ``AUTO`` | -+-------------------------+------------------------+-------------------------------------------+---------------+ -| Shared memory directory | ``string`` | |DataSharingQosPolicy::shm_directory-api| | Empty string | -+-------------------------+------------------------+-------------------------------------------+---------------+ -| Maximum domain number | ``uint32_t`` | |DataSharingQosPolicy::max_domains-api| | 0 (unlimited) | -+-------------------------+------------------------+-------------------------------------------+---------------+ -| Data-sharing domain IDs | ``vector`` | |DataSharingQosPolicy::domain_ids-api| | Empty | -+-------------------------+------------------------+-------------------------------------------+---------------+ +.. list-table:: + :header-rows: 1 + :align: left + + * - Data Member + - Type + - Accessor + - Default Value + * - Data-sharing kind + - :ref:`datasharingkind` + - |DataSharingQosPolicy::kind-api| + - ``AUTO`` + * - Shared memory directory + - ``string`` + - |DataSharingQosPolicy::shm_directory-api| + - Empty string + * - Maximum domain number + - ``uint32_t`` + - |DataSharingQosPolicy::max_domains-api| + - 0 (unlimited) + * - Data-sharing domain IDs + - ``vector`` + - |DataSharingQosPolicy::domain_ids-api| + - Empty + * - Data-sharing listener thread settings + - |ThreadSettings| + - |DataSharingQosPolicy::data_sharing_listener_thread-api| + - * Data-sharing kind: Specifies the behavior of data-sharing delivery. @@ -54,6 +71,8 @@ List of QoS Policy data members: * Data sharing domain IDs: The list of data-sharing domain IDs configured for the current |DataWriter| or |DataReader|. If no ID is provided, the system will create a unique one for the current machine. +* Data-sharing listener thread settings: + The |ThreadSettings| for the data-sharing thread dedicated to listening for incoming traffic. .. note:: This QoS Policy concerns to |DataWriter| and |DataReader| entities. @@ -109,20 +128,23 @@ so it must be done before the entity is enabled. Example """"""" -C++ -*** -.. literalinclude:: ../../../../../code/DDSCodeTester.cpp - :language: c++ - :dedent: 8 - :start-after: //DDS_CHANGE_DATASHARING_QOS_POLICY - :end-before: //! +.. tabs:: -XML -*** -.. literalinclude:: /../code/XMLTester.xml - :language: xml - :start-after: CONF-QOS-DATASHARING<--> - :end-before: <--> + .. tab:: C++ + + .. literalinclude:: ../../../../../code/DDSCodeTester.cpp + :language: c++ + :dedent: 8 + :start-after: //DDS_CHANGE_DATASHARING_QOS_POLICY + :end-before: //! + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: CONF-QOS-DATASHARING<--> + :end-before: <--> + :lines: 2-4, 6-34, 36-37 .. _disablepositiveacksqospolicy: @@ -213,17 +235,28 @@ This QoS configures the list of flow controllers of a participant, so they can l its DataWriters. It is a vector of shared pointers to |FlowControllerDescriptor-api|, which has the following fields: -+------------------------------------------------------+-------------------------------------+-------------------------+ -| Data Member Name | Type | Default Value | -+======================================================+=====================================+=========================+ -| |FlowControllerDescriptor::name-api| | ``const char *`` | | -+------------------------------------------------------+-------------------------------------+-------------------------+ -| |FlowControllerDescriptor::scheduler-api| | |FlowControllerSchedulerPolicy-api| | |FIFO_SCHED_POLICY-api| | -+------------------------------------------------------+-------------------------------------+-------------------------+ -| |FlowControllerDescriptor::max_bytes_per_period-api| | ``int32_t`` | 0 (i.e. infinite) | -+------------------------------------------------------+-------------------------------------+-------------------------+ -| |FlowControllerDescriptor::period_ms-api| | ``uint64_t`` | 100 | -+------------------------------------------------------+-------------------------------------+-------------------------+ +.. list-table:: + :header-rows: 1 + :align: left + + * - Data Member Name + - Type + - Default Value + * - |FlowControllerDescriptor::name-api| + - ``const char *`` + - + * - |FlowControllerDescriptor::scheduler-api| + - |FlowControllerSchedulerPolicy-api| + - FIFO_SCHED_POLICY-api| + * - |FlowControllerDescriptor::max_bytes_per_period-api| + - ``int32_t`` + - 0 (i.e. infinite) + * - |FlowControllerDescriptor::period_ms-api| + - ``uint64_t`` + - 100 + * - |FlowControllerDescriptor::sender_thread-api| + - |ThreadSettings| + - Please refer to :ref:`flow-controllers` section for more information. @@ -855,6 +888,68 @@ XML :start-after: XML_RTPS_RELIABLE_WRITER_QOS<--> :end-before: <--> +.. _threadsettingsqos: + +ThreadSettings +^^^^^^^^^^^^^^ + +This structure is part of other QoS policies, and allows controlling some OS settings for the threads created. +The default values will leave the default OS settings on the created threads. +Changing these values may require special permissions. + +.. list-table:: + :header-rows: 1 + + * - Data Member Name + - Type + - Default Value + * - |ThreadSettings::scheduling_policy-api| + - ``int32_t`` + - -1 + * - |ThreadSettings::priority-api| + - ``int32_t`` + - -2^31 + * - |ThreadSettings::affinity-api| + - ``uint32_t`` + - 0 + * - |ThreadSettings::stack_size-api| + - ``int32_t`` + - -1 + +* |ThreadSettings::scheduling_policy-api|: Configures the scheduling policy used for the thread. + This value is platform specific and it is used as-is to configure the specific platform thread. + It is ignored on Windows platforms. +* |ThreadSettings::priority-api|: Configures the thread's priority. + This value is platform specific and it is used as-is to configure the specific platform thread. +* |ThreadSettings::affinity-api|: On some systems (Windows, Linux), this is a bit mask for setting + the threads affinity to each core individually. + On MacOS, this sets the affinity tag for the thread, and the OS tries to share the L2 cache + between threads with the same affinity. + This value is platform specific and it is used as-is to configure the specific platform thread. +* |ThreadSettings::stack_size-api|: Configures the thread's stack size in bytes. + This value is platform specific and it is used as-is to configure the specific platform thread. + +Example +""""""" + +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: ../../../../../code/DDSCodeTester.cpp + :language: c++ + :dedent: 8 + :start-after: //DDS_CHANGE_THREAD_SETTINGS + :end-before: //! + + .. tab:: XML + + .. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: CONF-COMMON-THREAD-SETTINGS<--> + :lines: 10,12-15,17 + :dedent: 16 + .. _transportconfigqos: TransportConfigQos @@ -883,6 +978,9 @@ List of QoS Policy data members: * - |TransportConfigQos::listen_socket_buffer_size-api| - ``uint32_t`` - 0 + * - |TransportConfigQos::builtin_transports_reception_threads-api| + - |ThreadSettings| + - * |TransportConfigQos::user_transports-api|: @@ -896,6 +994,8 @@ List of QoS Policy data members: * |TransportConfigQos::listen_socket_buffer_size-api|: The listen socket buffer size is also created with the system default size, but it can be changed using this data member. +* |TransportConfigQos::builtin_transports_reception_threads-api|: + The |ThreadSettings| for the reception threads of the builtin transports. .. note:: This QoS Policy concerns to |DomainParticipant| entities. diff --git a/docs/fastdds/dds_layer/domain/domainParticipant/domainParticipant.rst b/docs/fastdds/dds_layer/domain/domainParticipant/domainParticipant.rst index 1706bcd91..bbb8673a3 100644 --- a/docs/fastdds/dds_layer/domain/domainParticipant/domainParticipant.rst +++ b/docs/fastdds/dds_layer/domain/domainParticipant/domainParticipant.rst @@ -29,23 +29,46 @@ DomainParticipantQos |DomainParticipantQos-api| controls the behavior of the DomainParticipant. Internally it contains the following |QosPolicy-api| objects: -+--------------------------------+----------------------------------------------+----------+ -| QosPolicy class | Accessor/Mutator | Mutable | -+================================+==============================================+==========+ -| |UserDataQosPolicy| | |DomainParticipantQos::user_data-api| | Yes | -+--------------------------------+----------------------------------------------+----------+ -| |EntityFactoryQosPolicy| | |DomainParticipantQos::entity_factory-api| | Yes | -+--------------------------------+----------------------------------------------+----------+ -| |ParticipantResourceLimitsQos| | |DomainParticipantQos::allocation-api| | No | -+--------------------------------+----------------------------------------------+----------+ -| |PropertyPolicyQos| | |DomainParticipantQos::properties-api| | No | -+--------------------------------+----------------------------------------------+----------+ -| |WireProtocolConfigQos| | |DomainParticipantQos::wire_protocol-api| | No* | -+--------------------------------+----------------------------------------------+----------+ -| |TransportConfigQos| | |DomainParticipantQos::transport-api| | No | -+--------------------------------+----------------------------------------------+----------+ -| |FlowControllersQos| | |DomainParticipantQos::flow_controllers-api| | No | -+--------------------------------+----------------------------------------------+----------+ + +.. list-table:: + :header-rows: 1 + + * - QosPolicy class + - Accessor/Mutator + - Mutable + * - |UserDataQosPolicy| + - |DomainParticipantQos::user_data-api| + - Yes + * - |EntityFactoryQosPolicy| + - |DomainParticipantQos::entity_factory-api| + - Yes + * - |ParticipantResourceLimitsQos| + - |DomainParticipantQos::allocation-api| + - No + * - |PropertyPolicyQos| + - |DomainParticipantQos::properties-api| + - No + * - |WireProtocolConfigQos| + - |DomainParticipantQos::wire_protocol-api| + - No* + * - |TransportConfigQos| + - |DomainParticipantQos::transport-api| + - No + * - |FlowControllersQos| + - |DomainParticipantQos::flow_controllers-api| + - No + * - |ThreadSettings| + - |DomainParticipantQos::builtin_controllers_sender_thread-api| + - No + * - |ThreadSettings| + - |DomainParticipantQos::timed_events_thread-api| + - No + * - |ThreadSettings| + - |DomainParticipantQos::discovery_server_thread-api| + - No + * - |ThreadSettings| + - |DomainParticipantQos::security_log_thread-api| + - No .. Important:: The only mutable field in |WireProtocolConfigQos| is |m_DiscoveryServers|, which is contained in diff --git a/docs/fastdds/dds_layer/domain/domainParticipantFactory/domainParticipantFactory.rst b/docs/fastdds/dds_layer/domain/domainParticipantFactory/domainParticipantFactory.rst index dd8ab2ed8..753cf1381 100644 --- a/docs/fastdds/dds_layer/domain/domainParticipantFactory/domainParticipantFactory.rst +++ b/docs/fastdds/dds_layer/domain/domainParticipantFactory/domainParticipantFactory.rst @@ -27,11 +27,21 @@ DomainParticipantFactoryQos DomainParticipantFactoryQos controls the behavior of the :ref:`dds_layer_domainParticipantFactory`. Internally it contains the following |QosPolicy-api| objects: -+------------------------------+----------------------------------------------------------------------------+----------+ -| QosPolicy class | Accessor/Mutator | Mutable | -+==============================+============================================================================+==========+ -| |EntityFactoryQosPolicy| | |DomainParticipantFactoryQos::entity_factory-api| | Yes | -+------------------------------+----------------------------------------------------------------------------+----------+ +.. list-table:: + :header-rows: 1 + + * - QosPolicy class + - Accessor/Mutator + - Mutable + * - |EntityFactoryQosPolicy| + - |DomainParticipantFactoryQos::entity_factory-api| + - Yes + * - |ThreadSettings| + - |DomainParticipantFactoryQos::shm_watchdog_thread-api| + - No + * - |ThreadSettings| + - |DomainParticipantFactoryQos::file_watch_threads-api| + - No Since the DomainParticipantFactory is a singleton, its QoS can only be modified with the |DomainParticipantFactory::set_qos-api| member function. diff --git a/docs/fastdds/getting_started/simple_app/includes/publisher.rst b/docs/fastdds/getting_started/simple_app/includes/publisher.rst index 0bf6036ce..cd99ba363 100644 --- a/docs/fastdds/getting_started/simple_app/includes/publisher.rst +++ b/docs/fastdds/getting_started/simple_app/includes/publisher.rst @@ -52,20 +52,20 @@ The next block includes the C++ header files that allow the use of the Fast DDS .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldPublisher.cpp :language: C++ - :lines: 22-27 + :lines: 22-30 Next, we define the namespace that contains the eProsima Fast DDS classes and functions that we are going to use in our application. .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldPublisher.cpp :language: C++ - :lines: 29 + :lines: 32 The next line creates the :class:`HelloWorldPublisher` class that implements a publisher. .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldPublisher.cpp :language: C++ - :lines: 31 + :lines: 34 Continuing with the private data members of the class, the ``hello_`` data member is defined as an object of the :class:`HelloWorld` class that defines the data type @@ -77,7 +77,7 @@ in the DomainParticipant. .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldPublisher.cpp :language: C++ - :lines: 33-45 + :lines: 36-48 Then, the :class:`PubListener` class is defined by inheriting from the |DataWriterListener-api| class. This class overrides the default DataWriter listener callbacks, which allows the execution of routines in case of an @@ -93,7 +93,7 @@ Finally, the ``listener_`` object of the class is defined as an instance of :cla .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldPublisher.cpp :language: C++ - :lines: 47-83 + :lines: 50-86 :dedent: 4 The public constructor and destructor of the :class:`HelloWorldPublisher` class are defined below. @@ -103,7 +103,7 @@ The class destructor removes these data members and thus cleans the system memor .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldPublisher.cpp :language: C++ - :lines: 87-111 + :lines: 90-114 :dedent: 4 Continuing with the public member functions of the :class:`HelloWorldPublisher` class, the next snippet of code defines @@ -125,7 +125,7 @@ The default value of the QoS of each DDS Entity can be checked in the .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldPublisher.cpp :language: C++ - :lines: 113-155 + :lines: 116-158 :dedent: 4 To make the publication, the public member function ``publish()`` is implemented. @@ -137,7 +137,7 @@ This is simply the `writing` of a change by the DataWriter object. .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldPublisher.cpp :language: C++ - :lines: 157-167 + :lines: 160-170 :dedent: 4 The public *run* function executes the action of publishing a given number of times, waiting for 1 second between @@ -145,14 +145,14 @@ publications. .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldPublisher.cpp :language: C++ - :lines: 169-184 + :lines: 172-187 :dedent: 4 Finally, the HelloWorldPublisher is initialized and run in main. .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldPublisher.cpp :language: C++ - :lines: 187-202 + :lines: 190-205 CMakeLists.txt """"""""""""""" @@ -162,7 +162,7 @@ files needed to build the executable, and links the executable and the library t .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/CMakeLists.txt :language: bash - :lines: 47-48 + :lines: 43-44 At this point the project is ready for building, compiling and running the publisher application. From the build directory in the workspace, run the following commands. diff --git a/docs/fastdds/getting_started/simple_app/includes/subscriber.rst b/docs/fastdds/getting_started/simple_app/includes/subscriber.rst index 85208d7b0..5652141cb 100644 --- a/docs/fastdds/getting_started/simple_app/includes/subscriber.rst +++ b/docs/fastdds/getting_started/simple_app/includes/subscriber.rst @@ -37,17 +37,17 @@ the data reader class. * |DataReaderQoS-api|. Structure that defines the QoS of the DataReader. * |SampleInfo-api|. - It is the information that accompanies each sample that is ‘read’ or ‘taken.’ + It is the information that accompanies each sample that is 'read' or 'taken'. .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldSubscriber.cpp :language: C++ - :lines: 22,29 + :lines: 25-32 The next line defines the :class:`HelloWorldSubscriber` class that implements a subscriber. .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldSubscriber.cpp :language: C++ - :lines: 33 + :lines: 36 Starting with the private data members of the class, it is worth mentioning the implementation of the data reader listener. @@ -60,7 +60,7 @@ analog of the |DataWriterListener::on_publication_matched-api| callback of the D .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldSubscriber.cpp :language: C++ - :lines: 60-77 + :lines: 63-80 :dedent: 8 The second overridden callback is |DataReaderListener::on_data_available-api|. @@ -71,14 +71,14 @@ Each time a sample is read, the counter of samples received is increased. .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldSubscriber.cpp :language: C++ - :lines: 79-92 + :lines: 82-95 :dedent: 8 The public constructor and destructor of the class is defined below. .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldSubscriber.cpp :language: C++ - :lines: 102-126 + :lines: 105-129 :dedent: 4 Next comes the subscriber initialization public member function. @@ -90,7 +90,7 @@ The default value of the QoS of each DDS Entity can be checked in the .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldSubscriber.cpp :language: C++ - :lines: 128-168 + :lines: 131-171 :dedent: 4 The public member function :func:`run` ensures that the subscriber runs until all the samples have been received. @@ -99,14 +99,14 @@ This member function implements an active wait of the subscriber, with a 100ms s .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldSubscriber.cpp :language: C++ - :lines: 170-178 + :lines: 173-181 :dedent: 4 Finally, the participant that implements a subscriber is initialized and run in main. .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/src/HelloWorldSubscriber.cpp :language: C++ - :lines: 181-196 + :lines: 184-199 CMakeLists.txt """"""""""""""" @@ -117,7 +117,7 @@ files needed to build the executable, and links the executable and the library t .. literalinclude:: /../code/Examples/C++/DDSHelloWorld/CMakeLists.txt :language: bash - :lines: 50-51 + :lines: 46-47 At this point the project is ready for building, compiling and running the subscriber application. From the build directory in the workspace, run the following commands. diff --git a/docs/fastdds/library_overview/includes/exec_model.rst b/docs/fastdds/library_overview/includes/exec_model.rst index 3445b1a49..15107b2c5 100644 --- a/docs/fastdds/library_overview/includes/exec_model.rst +++ b/docs/fastdds/library_overview/includes/exec_model.rst @@ -4,6 +4,8 @@ Programming and execution model *Fast DDS* is concurrent and event-based. The following explains the multithreading model that governs the operation of *Fast DDS* as well as the possible events. +.. _concurrency_multithreading: + Concurrency and multithreading ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -26,67 +28,101 @@ Transport related threads (marked as UDP, TCP and SHM types) are only created wh * - Name - Type - Cardinality + - OS thread name - Description * - Event - General - One per DomainParticipant - - Processes periodic and triggered time events + - ``dds.ev.`` + - Processes periodic and triggered time events. |br| + See :ref:`dds_layer_domainParticipantQos`. * - Discovery Server Event - General - One per DomainParticipant - - Synchronizes access to the Discovery Server |br| Database + - ``dds.ds_ev.`` + - Synchronizes access to the Discovery Server |br| Database. |br| + See :ref:`dds_layer_domainParticipantQos`. * - Asynchronous Writer - General - - One per enabled asynchronous |br| flow controller - + - One per enabled asynchronous |br| flow controller. Minimum 1. + - ``dds.asyn..`` |br| + ```` - Manages asynchronous writes. - - Even for synchronous writers, some forms of |br| communication must be initiated in the |br| background. + Even for synchronous writers, some forms of |br| communication must be initiated in the |br| background. |br| + See :ref:`dds_layer_domainParticipantQos` and :ref:`flowcontrollersqos`. * - Datasharing Listener - General - One per |br| DataReader - - Listener thread that processes messages |br| received via Datasharing + - ``dds.dsha.`` + - Listener thread that processes messages |br| received via Datasharing. |br| + See :ref:`dds_layer_subscriber_dataReaderQos`. * - Reception - UDP - One per port - - Listener thread that processes incoming |br| UDP messages + - ``dds.udp.`` + - Listener thread that processes incoming |br| UDP messages. |br| + See :ref:`transportconfigqos` and :ref:`transport_udp_transportDescriptor`. * - Reception - TCP - - One per port - - Listener thread that processes incoming |br| TCP messages + - One per TCP connection + - ``dds.tcp.`` + - Listener thread that processes incoming |br| TCP messages. |br| + See :ref:`transport_tcp_transportDescriptor`. + * - Accept + - TCP + - One per TCP transport + - ``dds.tcp_accept`` + - Thread that processes incoming TCP connection requests. |br| + See :ref:`transport_tcp_transportDescriptor`. * - Keep Alive - TCP - - One per port - - Keep alive thread for TCP connections. + - One per TCP transport + - ``dds.tcp_keep`` + - Keep alive thread for TCP connections. |br| + See :ref:`transport_tcp_transportDescriptor`. * - Reception - SHM - One per port - - Listener thread that processes incoming |br| messages via SHM segments + - ``dds.shm.`` + - Listener thread that processes incoming |br| messages via SHM segments. |br| + See :ref:`transportconfigqos` and :ref:`transport_sharedMemory_transportDescriptor`. * - Logging - SHM - - One per SHM descriptor - - Stores and dumps transferred packets to a file. + - One per port + - ``dds.shmd.`` + - Stores and dumps transferred packets to a file. |br| + See :ref:`transportconfigqos` and :ref:`transport_sharedMemory_transportDescriptor`. * - Watchdog - SHM - One - - Monitors health of open shared memory |br| segments. + - ``dds.shm.wdog`` + - Monitors health of open shared memory |br| segments. |br| + See :ref:`transportconfigqos` and :ref:`transport_sharedMemory_transportDescriptor`. * - General Logging - Log - One - - Accumulates and writes to the appropriate |br| consumer log entries. + - ``dds.log`` + - Accumulates and writes to the appropriate |br| consumer log entries. |br| + See :ref:`dds_layer_log_thread`. * - Security Logging - Log - One per |br| DomainParticipant - - Accumulates and writes security log entries. + - ``dds.slog.`` + - Accumulates and writes security log entries. |br| + See :ref:`dds_layer_domainParticipantQos`. * - Watchdog - Filewatch - One - - Tracks the status of the watched file for |br| modifications + - ``dds.fwatch`` + - Tracks the status of the watched file for |br| modifications. |br| + See :ref:`dds_layer_domainParticipantFactoryQos`. * - Callback - Filewatch - One - - Runs the registered callback when the |br| watched file changes. + - ``dds.fwatch.cb`` + - Runs the registered callback when the |br| watched file changes. |br| + See :ref:`dds_layer_domainParticipantFactoryQos`. Some of these threads are only spawned when certain conditions are met: @@ -102,6 +138,9 @@ but the default configuration is to always use a metatraffic port and a unicast This applies both to UDP and Shared Memory since TCP does not support multicast. More information can be found at the :ref:`listening_locators_default` page. +*Fast DDS* offers the possibility of configuring certain attributes of the threads it creates by means of the +:ref:`threadsettingsqos`. + Event-driven architecture ^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/fastdds/logging/logging_thread.rst b/docs/fastdds/logging/logging_thread.rst index 20d96d19e..e034a442c 100644 --- a/docs/fastdds/logging/logging_thread.rst +++ b/docs/fastdds/logging/logging_thread.rst @@ -16,6 +16,8 @@ However, sometimes applications may want to wait until the logging routine is do The logging module provides this capability via the member function |Log::Flush-api|. Furthermore, it is possible to completely eliminate the thread and its resources using member function |Log::KillThread-api|. +In addition, it is possible to configure certain settings of this logging thread via the member function +|Log::SetThreadConfig-api|. .. literalinclude:: /../code/DDSCodeTester.cpp :language: c++ diff --git a/docs/fastdds/transport/shared_memory/shared_memory.rst b/docs/fastdds/transport/shared_memory/shared_memory.rst index 79f154e01..0d9df4b70 100644 --- a/docs/fastdds/transport/shared_memory/shared_memory.rst +++ b/docs/fastdds/transport/shared_memory/shared_memory.rst @@ -141,36 +141,52 @@ the TransportDescriptor for Shared Memory defines the following ones: .. list-table:: - :header-rows: 1 - - * - Member - - Data type - - Default - - Accessor / Mutator - - Description - * - ``segment_size_`` - - ``uint32_t`` - - ``512*1024`` - - |SharedMemTransportDescriptor::segment_size-api| - - Size of the shared memory segment |br| - (in octets). - * - ``port_queue_capacity_`` - - ``uint32_t`` - - ``512`` - - |SharedMemTransportDescriptor::port_queue_capacity-api| - - The size of the listening port |br| - (in messages). - * - ``healthy_check_timeout_ms_`` - - ``uint32_t`` - - ``1000`` - - |SharedMemTransportDescriptor::healthy_check_timeout_ms-api| - - Timeout for the health check of ports |br| - (in milliseconds). - * - ``rtps_dump_file_`` - - ``string`` - - ``""`` - - |SharedMemTransportDescriptor::rtps_dump_file-api| - - Full path of the protocol dump file. + :header-rows: 1 + :align: left + + * - Member + - Data type + - Default + - Accessor / Mutator + - Description + * - ``segment_size_`` + - ``uint32_t`` + - ``512*1024`` + - |SharedMemTransportDescriptor::segment_size-api| + - Size of the shared memory segment |br| + (in octets). + * - ``port_queue_capacity_`` + - ``uint32_t`` + - ``512`` + - |SharedMemTransportDescriptor::port_queue_capacity-api| + - The size of the listening port |br| + (in messages). + * - ``healthy_check_timeout_ms_`` + - ``uint32_t`` + - ``1000`` + - |SharedMemTransportDescriptor::healthy_check_timeout_ms-api| + - Timeout for the health check of ports |br| + (in milliseconds). + * - ``rtps_dump_file_`` + - ``string`` + - ``""`` + - |SharedMemTransportDescriptor::rtps_dump_file-api| + - Full path of the protocol dump file. + * - |PortBasedTransportDescriptor::default_reception_threads-api| + - |ThreadSettings| + - + - |PortBasedTransportDescriptor::default_reception_threads-api| + - Default |ThreadSettings| for the reception threads. + * - |PortBasedTransportDescriptor::reception_threads-api| + - ``std::map`` + - + - |PortBasedTransportDescriptor::reception_threads-api| + - |ThreadSettings| for the reception threads on specific ports. + * - |SharedMemTransportDescriptor::dump_thread-api| + - |ThreadSettings| + - + - |SharedMemTransportDescriptor::dump_thread-api| + - |ThreadSettings| for the SHM dump thread. If ``rtps_dump_file_`` is not empty, all the shared memory traffic on the DomainParticipant (sent and received) is traced to a file. @@ -218,8 +234,7 @@ The examples below show this procedure in both C++ code and XML file. :language: xml :start-after: CONF-SHM-TRANSPORT-SETTING :end-before: <--> - :lines: 2-3,5- - :append: + :lines: 2-4,6-41,43-44 .. note:: diff --git a/docs/fastdds/transport/tcp/tcp.rst b/docs/fastdds/transport/tcp/tcp.rst index f93aaf627..5eec238ef 100644 --- a/docs/fastdds/transport/tcp/tcp.rst +++ b/docs/fastdds/transport/tcp/tcp.rst @@ -1,3 +1,4 @@ +.. include:: ../../../03-exports/aliases.include .. include:: ../../../03-exports/aliases-api.include .. _transport_tcp_tcp: @@ -111,6 +112,22 @@ The following table describes the common data members for both TCPv4 and TCPv6. - |TCPTransportDescriptor::TLSConfig-api| - - Configuration for TLS. See |TLSconfig|. + * - |PortBasedTransportDescriptor::default_reception_threads-api| + - |ThreadSettings| + - + - Default |ThreadSettings| for the reception threads. + * - |PortBasedTransportDescriptor::reception_threads-api| + - ``std::map`` + - + - |ThreadSettings| for the reception threads on specific ports. + * - |TCPTransportDescriptor::keep_alive_thread-api| + - |ThreadSettings| + - + - |ThreadSettings| for the thread keeping alive TCP connections. + * - |TCPTransportDescriptor::accept_thread-api| + - |ThreadSettings| + - + - |ThreadSettings| for the threads processing incoming TCP connection requests. .. note:: @@ -191,8 +208,7 @@ TCP Server or TCP Client. :language: xml :start-after: CONF-TCP-TRANSPORT-SETTING-SERVER :end-before: <--> - :lines: 2-3,5- - :append: + :lines: 2-4,6-73,75-76 * **TCP Client**: If you provide |BuiltinAttributes::initialPeersList-api| to the DomainParticipant, it will act as *TCP client*, trying to connect to the remote *servers* at the given addresses and ports. @@ -215,8 +231,7 @@ TCP Server or TCP Client. :language: xml :start-after: CONF-TCP-TRANSPORT-SETTING-CLIENT :end-before: <--> - :lines: 2-3,5- - :append: + :lines: 2-4,6-58,60-61 :ref:`transport_tcp_example` shows how to use and configure a TCP transport. @@ -265,8 +280,7 @@ The following examples show how to configure the DomainParticipant both in C++ a :language: xml :start-after: CONF-TCP-TRANSPORT-SETTING-SERVER :end-before: <--> - :lines: 2-3,5- - :append: + :lines: 2-4,6-73,75-76 On the client side, the DomainParticipant must be configured with the **public** IP address and |TCPTransportDescriptor::listening_ports-api| of the *TCP server* as @@ -288,8 +302,7 @@ with the **public** IP address and |TCPTransportDescriptor::listening_ports-api| :language: xml :start-after: CONF-TCP-TRANSPORT-SETTING-CLIENT :end-before: <--> - :lines: 2-3,5- - :append: + :lines: 2-4,6-58,60-61 .. _transport_tcp_example: diff --git a/docs/fastdds/transport/udp/udp.rst b/docs/fastdds/transport/udp/udp.rst index d3ec502f7..c6fe47979 100644 --- a/docs/fastdds/transport/udp/udp.rst +++ b/docs/fastdds/transport/udp/udp.rst @@ -1,3 +1,4 @@ +.. include:: ../../../03-exports/aliases.include .. include:: ../../../03-exports/aliases-api.include .. _transport_udp_udp: @@ -61,6 +62,14 @@ The following table describes the common data members for both UDPv4 and UDPv6. - ``bool`` - ``false`` - Do not block on send operations (*). + * - |PortBasedTransportDescriptor::default_reception_threads-api| + - |ThreadSettings| + - + - Default |ThreadSettings| for the reception threads. + * - |PortBasedTransportDescriptor::reception_threads-api| + - ``std::map`` + - + - |ThreadSettings| for the reception threads on specific ports. .. note:: @@ -130,5 +139,4 @@ The examples below show this procedure in both C++ code and XML file. :language: xml :start-after: CONF-UDP-TRANSPORT-SETTING :end-before: <--> - :lines: 2-3,5- - :append: + :lines: 2-4,6-37,39-40 diff --git a/docs/fastdds/use_cases/large_data/large_data.rst b/docs/fastdds/use_cases/large_data/large_data.rst index 67929adba..8ea5cdbe7 100644 --- a/docs/fastdds/use_cases/large_data/large_data.rst +++ b/docs/fastdds/use_cases/large_data/large_data.rst @@ -244,22 +244,20 @@ They only differ in the way they decide the order in which the samples are sent. Example configuration ^^^^^^^^^^^^^^^^^^^^^ -+------------------------------------------------+ -| **C++** | -+------------------------------------------------+ -| .. literalinclude:: /../code/DDSCodeTester.cpp | -| :language: c++ | -| :start-after: //CONF-QOS-FLOWCONTROLLER | -| :end-before: //!-- | -| :dedent: 8 | -+------------------------------------------------+ -| **XML** | -+------------------------------------------------+ -| There is currently no way of configuring flow | -| controllers with XML. | -| This will be added in future releases of the | -| product | -+------------------------------------------------+ +.. tabs:: + + .. tab:: C++ + + .. literalinclude:: /../code/DDSCodeTester.cpp + :language: c++ + :start-after: //CONF-QOS-FLOWCONTROLLER + :end-before: //!-- + :dedent: 8 + + .. tab:: XML + + There is currently no way of configuring flow controllers with XML. + This will be added in future releases of the product. .. Warning:: diff --git a/docs/fastdds/xml_configuration/common.rst b/docs/fastdds/xml_configuration/common.rst index 2f4279908..f2aaf4f92 100644 --- a/docs/fastdds/xml_configuration/common.rst +++ b/docs/fastdds/xml_configuration/common.rst @@ -19,6 +19,8 @@ This section aims to explain these common elements. - :ref:`hQos` - :ref:`rLsQos` +* :ref:`ThreadSettingsType` + * :ref:`CommonQOS` - :ref:`xml_datasharing` @@ -26,6 +28,7 @@ This section aims to explain these common elements. - :ref:`xml_disableheartbeatpiggyback` - :ref:`xml_disablepositiveacks` - :ref:`xml_durability` + - :ref:`xml_entity_factory` - :ref:`xml_groupData` - :ref:`xml_latencybudget` - :ref:`xml_lifespan` @@ -313,6 +316,41 @@ Please refer to :ref:`ResourceLimitsQosPolicy` for further information on Resour | ```` | The number of extra samples to allocate on the pool. | ``uint32_t`` | 1 | +--------------------------------+-----------------------------------------------------------+---------------+---------+ +.. _ThreadSettingsType: + +ThreadSettings +^^^^^^^^^^^^^^ + +It controls some OS settings for the *Fast DDS* created threads. +Please refer to :ref:`threadsettingsqos` for further information on ResourceLimitsQos. + +.. list-table:: + :header-rows: 1 + + * - Name + - Description + - Values + - Default + * - |ThreadSettings::scheduling_policy-api| + - Configures the scheduling policy used for the thread. + - ``int32_t`` + - -1 + * - |ThreadSettings::priority-api| + - Configures the thread's priority. + - ``int32_t`` + - -2^31 + * - |ThreadSettings::affinity-api| + - On some systems (Windows, Linux), this is a bit mask for setting |br| + the threads affinity to each core individually. On MacOS, this |br| + sets the affinity tag for the thread, and the OS tries to share |br| + the L2 cache between threads with the same affinity. + - ``uint32_t`` + - 0 + * - |ThreadSettings::stack_size-api| + - Configures the thread's stack size in bytes. + - ``int32_t`` + - -1 + .. _CommonQOS: QoS @@ -344,6 +382,9 @@ Please refer to the :ref:`dds_layer_core_policy` section for more information on * - ```` - See :ref:`durabilityqospolicy`. - :ref:`xml_durability` + * - ```` + - See :ref:`entityfactoryqospolicy`. + - :ref:`xml_entity_factory` * - ```` - See :ref:`groupqospolicy`. - :ref:`xml_groupData` @@ -490,6 +531,24 @@ Durability - DataReaders: |VOLATILE-xml-api| |br| DataWriters: |TRANSIENT_LOCAL-xml-api| |br| +.. _xml_entity_factory: + +Entity Factory +"""""""""""""" + +.. list-table:: + :header-rows: 1 + :align: left + + * - Name + - Description + - Values + - Default + * - ```` + - See :ref:`entityfactoryqospolicy`. + - ``bool`` + - ``true`` + .. _xml_groupData: GroupData diff --git a/docs/fastdds/xml_configuration/domainparticipant.rst b/docs/fastdds/xml_configuration/domainparticipant.rst index ea7ff8c6e..9f14a6856 100644 --- a/docs/fastdds/xml_configuration/domainparticipant.rst +++ b/docs/fastdds/xml_configuration/domainparticipant.rst @@ -177,6 +177,26 @@ These elements allow the user to define the DomainParticipant configuration. delivery is used. See :ref:`intraprocess-delivery`. - ``string`` - Empty + * - ```` + - |ThreadSettings| for the builtin flow controllers sender thread. + - |ThreadSettings| + - + * - ```` + - |ThreadSettings| participant's timed events thread. + - |ThreadSettings| + - + * - ```` + - |ThreadSettings| for the discovery server thread. + - |ThreadSettings| + - + * - ```` + - |ThreadSettings| for the builtin transports reception threads. + - |ThreadSettings| + - + * - ```` + - |ThreadSettings| for the security log thread. + - |ThreadSettings| + - **Example** @@ -184,7 +204,7 @@ These elements allow the user to define the DomainParticipant configuration. :language: xml :start-after: XML-PARTICIPANT<--> :end-before: <--> - :lines: 2-3, 5-88, 90 + :lines: 2-4, 6-124, 126-127 .. note:: diff --git a/docs/fastdds/xml_configuration/domainparticipantfactory.rst b/docs/fastdds/xml_configuration/domainparticipantfactory.rst new file mode 100644 index 000000000..37eea6c50 --- /dev/null +++ b/docs/fastdds/xml_configuration/domainparticipantfactory.rst @@ -0,0 +1,86 @@ +.. include:: ../../03-exports/aliases.include +.. include:: ../../03-exports/aliases-api.include +.. include:: ../../03-exports/roles.include + +.. _participantfactoryprofiles: + +DomainParticipantFactory profiles +--------------------------------- + +The |DomainParticipantFactory| profiles allow the definition of the configuration of |DomainParticipantFactory-api| +through XML files. +These profiles are defined within the ```` XML tags. + +.. _domainparticipantfactoryattributes: + +DomainParticipantFactory XML attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ```` element has two attributes defined: ``profile_name`` and ``is_default_profile``. + +.. list-table:: + :header-rows: 1 + :align: left + + * - Name + - Description + - Use + * - ``profile_name`` + - Sets the name under which the ```` profile is registered in the |br| + DDS Domain, so that it can be loaded later by the |DomainParticipantFactory-api|, as shown in |br| + :ref:`loadingapplyingprofiles`. + - Mandatory + * - ``is_default_profile`` + - Sets the ```` profile as the default profile. Thus, if a default |br| + profile exists, it will be used when creating the DomainParticipantFactory + - Optional + +.. _domainparticipantfactoryconfig: + +DomainParticipantFactory configuration +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The ```` element has the following children elements: + +.. list-table:: + :header-rows: 1 + :align: left + + * - Name + - Description + - Values + * - ```` + - DomainParticipantFactory QoS. + - :ref:`domainparticipantfactoryqosconfig` + +.. _domainparticipantfactoryqosconfig: + +QoS element type +"""""""""""""""" + +.. list-table:: + :header-rows: 1 + :align: left + + * - Name + - Description + - Values + * - ```` + - Entity factory QoS Policy. + - :ref:`xml_entity_factory` + * - ```` + - |ThreadSettings| for the SHM watchdog thread. |br| + See :ref:`concurrency_multithreading`. + - :ref:`ThreadSettingsType` + * - ```` + - |ThreadSettings| for the File watch threads. + See :ref:`concurrency_multithreading`. + - :ref:`ThreadSettingsType` + +**Example** + +.. literalinclude:: /../code/XMLTester.xml + :language: xml + :start-after: XML-PARTICIPANT-FACTORY<--> + :end-before: <--> + :lines: 2-4, 6-24, 26-27 diff --git a/docs/fastdds/xml_configuration/log.rst b/docs/fastdds/xml_configuration/log.rst index e0fd0392d..fb0149e98 100644 --- a/docs/fastdds/xml_configuration/log.rst +++ b/docs/fastdds/xml_configuration/log.rst @@ -5,7 +5,7 @@ .. _logprofiles: Log profiles ----------------- +------------ *eProsima Fast DDS* allows for registering and configuring :ref:`Log consumers ` using XML configuration files. @@ -14,17 +14,32 @@ The logging profiles are defined within the ```` XML tags. The ```` element has two child elements: ```` and ````. These are described in the following table. -+-------------------+---------------------------------------------------------------+-----------------------+----------+ -| Name | Description | Values | Default | -+===================+===============================================================+=======================+==========+ -| ```` | If set to ``FALSE``, a call to | ``bool`` | ``true`` | -| | |Log::ClearConsumers-api| is |br| | | | -| | performed. See :ref:`dds_layer_log_register_consumers`. | | | -+-------------------+---------------------------------------------------------------+-----------------------+----------+ -| ```` | Defines the class and configuration of the consumer to |br| | :ref:`xmllogconsumer` | | -| | be registered. Multiple consumers can be registered |br| | | | -| | this way. See :ref:`dds_layer_log_consumer`. | | | -+-------------------+---------------------------------------------------------------+-----------------------+----------+ +.. list-table:: + :header-rows: 1 + :align: left + + * - Name + - Description + - Values + - Default + * - ```` + - If set to ``FALSE``, a call to |Log::ClearConsumers-api| is |br| + |Log::ClearConsumers-api| is |br| + performed. See :ref:`dds_layer_log_register_consumers`. + - ``bool`` + - ``true`` + * - ```` + - Defines the class and configuration of the consumer to |br| + be registered. Multiple consumers can be registered |br| + this way. See :ref:`dds_layer_log_consumer`. + - :ref:`xmllogconsumer` + - + * - ```` + - |ThreadSettings| for the logging thread. + - |ThreadSettings| + - + + The following constitutes an example of an XML configuration file that sets the |Log-api| to use one |StdoutConsumer-api|, one |StdoutErrConsumer-api|, and one |FileConsumer-api|: @@ -33,7 +48,7 @@ The following constitutes an example of an XML configuration file that sets the :language: xml :start-after: LOG-CONFIG<--> :end-before: <--> - :lines: 2-3, 5-43, 45 + :lines: 2-3, 5-53, 55 .. _xmllogconsumer: diff --git a/docs/fastdds/xml_configuration/xml_configuration.rst b/docs/fastdds/xml_configuration/xml_configuration.rst index f4c87363a..cf29f7254 100644 --- a/docs/fastdds/xml_configuration/xml_configuration.rst +++ b/docs/fastdds/xml_configuration/xml_configuration.rst @@ -33,6 +33,7 @@ to create complete XML files. :maxdepth: 2 /fastdds/xml_configuration/making_xml_profiles + /fastdds/xml_configuration/domainparticipantfactory /fastdds/xml_configuration/domainparticipant /fastdds/xml_configuration/datawriter /fastdds/xml_configuration/datareader