【FastDDS】 Entity Policy 之 扩展Qos策略

3.1.2.2. eProsima 扩展¶

eProsima QoS 策略扩展允许更改 RTPS 层可配置设置的值。

3.1.2.2.1. DataSharingQosPolicy¶

此附加 QoS 允许配置写入器和读取器之间的数据共享传递通信。有关数据共享传递功能的描述，请参见数据共享传递。

QoS 策略数据成员列表：

• 数据共享类型：指定数据共享传递的行为。有关可能值及其影响的描述，请参见 DataSharingKind。
• 共享内存目录：将用于内存映射文件的目录。如果未配置，则将使用系统默认目录。
• 最大域数量：确定本地或远程端点中的数据共享域 ID 的最大数量。域 ID 在数据共享传递兼容的端点之间交换。如果该值低于任何远程端点的列表大小，则匹配可能会失败。值为零表示 ID 的数量不受限制。
• 数据共享域 ID：为当前 DataWriter 或 DataReader 配置的数据共享域 ID 列表。如果未提供 ID，系统将为当前机器创建一个唯一的 ID。
• 数据共享监听器线程设置：专用于监听传入流量的数据共享线程的 ThreadSettings。

注意
此 QoS 策略适用于 DataWriter 和 DataReader 实体。不能在已启用的实体上更改它。

DataSharingKind¶

有三个可能的值（请参见 DataSharingKind）：

• OFF：数据共享传递被禁用。不会使用数据共享传递功能执行任何通信。
• ON：手动启用数据共享传递。如果当前主题与数据共享传递不兼容，将发生错误。与共享至少一个数据共享域 ID 的远程实体的通信将使用数据共享传递功能完成。
• AUTO：如果当前主题与数据共享兼容，则激活数据共享传递；如果不兼容，则停用。

数据共享配置辅助函数¶

为了设置数据共享传递配置，必须使用以下辅助成员函数之一。每种 DataSharingKind 类型都有一个对应的函数：

可以稍后使用 add_domain_id() 函数添加数据共享域 ID，而不是在这些辅助函数上定义它们。请注意，添加新的域 ID 算作修改 QosPolicy，因此必须在启用实体之前完成。

示例¶

C++

// 本示例使用 DataWriter，但它也可应用于 DataReader 实体

DataWriterQos writer_qos;

// DataSharing 默认设置为 AUTO，这意味着如果主题兼容，将使用 DataSharing。如果未指定共享内存目录，将使用默认目录。

// 将 DataSharing 配置为 ON 以启用 DataSharing 并指定共享内存目录（必选）
writer_qos.data_sharing().on("/path/to/shared_memory/directory");
// 或者，将 DataSharing 配置为 OFF 以禁用它
writer_qos.data_sharing().off();

// 将 DataSharing 配置为 AUTO 并带有两个用户定义的 ID（也可与 ON 一起使用）
std::vector<uint16_t> ids;
ids.push_back(0x1234);
ids.push_back(0xABCD);
writer_qos.data_sharing().automatic(ids);

// 或者，单独添加它们
writer_qos.data_sharing().add_domain_id(uint16_t(0x1234));
writer_qos.data_sharing().add_domain_id(uint16_t(0xABCD));

// 或者可以留空 ID，系统将自动为当前机器创建一个唯一的 ID

// 将最大域数量设置为 5。设置为 0 表示“无限制”
writer_qos.data_sharing().set_max_domains(5);

// [可选] 监听线程的 ThreadSettings
writer_qos.data_sharing().data_sharing_listener_thread(eprosima::fastdds::rtps::ThreadSettings{-1, 0, 0, -1});

// 在相应实体的创建中使用修改后的 QoS
writer_ = publisher_->create_datawriter(topic_, writer_qos);

XML

<?xml version="1.0" encoding="UTF-8" ?>
<dds>
    <profiles xmlns="http://www.eprosima.com">
        <data_writer profile_name="writer_profile_qos_datasharing">
            <qos>
                <data_sharing>
                    <kind>AUTOMATIC</kind>
                    <domain_ids>
                        <domainId>123</domainId>
                        <domainId>098</domainId>
                    </domain_ids>
                </data_sharing>
            </qos>
        </data_writer>

        <data_reader profile_name="reader_profile_qos_datasharing">
            <qos>
                <data_sharing>
                    <kind>AUTOMATIC</kind>
                    <domain_ids>
                        <domainId>123</domainId>
                        <domainId>098</domainId>
                    </domain_ids>
                    <data_sharing_listener_thread>
                        <scheduling_policy>-1</scheduling_policy>
                        <priority>0</priority>
                        <affinity>0</affinity>
                        <stack_size>-1</stack_size>
                    </data_sharing_listener_thread>
                </data_sharing>
            </qos>
        </data_reader>
    </profiles>
<dds>

3.1.2.2.2. DisablePositiveACKsQosPolicy¶

当不需要严格的可靠通信且带宽有限时，此附加 QoS 允许减少网络流量。它包括更改读取器向写入器发送肯定确认的默认行为。相反，只有当读取器缺少样本时才会发送否定确认，但写入器会在将数据视为已确认之前保留一段可调整的时间。参见 DisablePositiveACKsQosPolicy。

QoS 策略数据成员列表：

• enabled：指定是否启用 QoS。如果为 true，则表示禁用肯定确认，DataReader 仅发送否定确认。否则，将同时发送肯定确认和否定确认。
• duration：指定 DataWriters 在将数据视为已确认之前保留数据的持续时间。此值不适用于 DataReaders。

注意
此 QoS 策略适用于 DataWriter 和 DataReader 实体。不能在已启用的实体上修改 enabled 数据成员。因此，必须在初始化期间设置此功能。只有 duration 数据成员可以在运行时修改。

警告
为了使 DataWriters 和 DataReaders 匹配，它们必须遵循兼容性规则。有关更多详细信息，请参见兼容性规则。

兼容性规则¶

为了保持 DataReaders 和 DataWriters 中的 DisablePositiveACKsQosPolicy 之间的兼容性，如果 DataWriter 禁用了此 QoS，则 DataReader 不能启用此 QoS。

可能的组合表：

示例¶

C++

// 此 Qos 对于 DataWriter 和 DataReader 实体具有不同的 API，因为它分别通过 ReliableWriterQos 和 ReliableReaderQos 访问。
// 有关更多详细信息，请参见 RTPSReliableWriterQos 和 RTPSReliableReaderQos 部分。
DataWriterQos writer_qos;
DataReaderQos reader_qos;

// DisablePositiveACKsQosPolicy 默认构造为 enabled = false
// 将 enabled 更改为 true
writer_qos.reliable_writer_qos().disable_positive_acks.enabled = true;
reader_qos.reliable_reader_qos().disable_positive_acks.enabled = true;

// DisablePositiveACKsQosPolicy 默认构造为无限持续时间
// 将持续时间更改为 1 秒
writer_qos.reliable_writer_qos().disable_positive_acks.duration = {1, 0};
reader_qos.reliable_reader_qos().disable_positive_acks.duration = {1, 0};

// 此外，DataWriters 可以额外禁用心跳搭载
writer_qos.reliable_writer_qos().disable_heartbeat_piggyback = true;

// 在相应实体的创建中使用修改后的 QoS
writer_ = publisher_->create_datawriter(topic_, writer_qos);
reader_ = subscriber_->create_datareader(topic_, reader_qos);

XML

<data_writer profile_name="writer_xml_conf_disable_positive_acks_profile">
    <qos>
        <disablePositiveAcks>
            <enabled>true</enabled>
            <duration>
                <sec>1</sec>
            </duration>
        </disablePositiveAcks>
    </qos>
</data_writer>

<data_reader profile_name="reader_xml_conf_disable_positive_acks_profile">
    <qos>
        <disablePositiveAcks>
            <enabled>true</enabled>
        </disablePositiveAcks>
    </qos>
</data_reader>

3.1.2.2.3. RTPSReliableReaderQos¶

此 RTPS QoS 策略允许配置多个 RTPS 可靠读取器的方面。参见 RTPSReliableReaderQos。

QoS 策略数据成员列表：

• times：定义 RTPSReader 事件的持续时间。有关更多详细信息，请参见 ReaderTimes。
• disable_positive_acks：配置禁用肯定确认的设置。有关更多详细信息，请参见 DisablePositiveACKsQosPolicy。

注意
此 QoS 策略适用于 DataReader 实体。只有 DisablePositiveACKsQosPolicy 的 duration 数据成员和 times 数据成员可以在已启用的实体上修改。

ReaderTimes¶

此结构定义与可靠读取器事件相关的时间。参见 ReaderTimes。

结构成员列表：

• initial_acknack_delay：定义初始 acknack 延迟的持续时间。
• heartbeat_response_delay：确定接收心跳消息时应用的延迟持续时间。

示例¶

C++

// 本示例仅适用于 DataReader 实体
DataReaderQos reader_qos;

// RTPSReliableReaderQos 默认构造为 initial_acknack_delay = 70 毫秒
// 将 initialAcknackDelay 更改为 70 纳秒
reader_qos.reliable_reader_qos().times.initial_acknack_delay = {0, 70};

// RTPSReliableReaderQos 默认构造为 heartbeat_response_delay = 5 毫秒
// 将 heartbeatResponseDelay 更改为 5 纳秒
reader_qos.reliable_reader_qos().times.heartbeat_response_delay = {0, 5};

// 您也可以更改 DisablePositiveACKsQosPolicy。有关更多详细信息，请参见 DisablePositiveACKsQosPolicy 部分。
reader_qos.reliable_reader_qos().disable_positive_acks.enabled = true;

// 在 DataReader 实体的创建中使用修改后的 QoS
reader_ = subscriber_->create_datareader(topic_, reader_qos);

XML

<data_reader profile_name="sub_profile_name">
    <times> <!-- readerTimesType -->
        <initial_acknack_delay> <!-- DURATION -->
            <nanosec>70</nanosec>
        </initial_acknack_delay>
        <heartbeat_response_delay> <!-- DURATION -->
            <nanosec>5</nanosec>
        </heartbeat_response_delay>
    </times>
    <!--您也可以更改 DisablePositiveACKsQosPolicy 的值。-->
    <!--有关更多详细信息，请参见 DisablePositiveACKsQosPolicy 部分-->
</data_reader>

3.1.2.2.4. RTPSReliableWriterQos¶

此 RTPS QoS 策略允许配置多个 RTPS 可靠写入器的方面。参见 RTPSReliableWriterQos。

QoS 策略数据成员列表：

• times：定义 RTPSWriter 事件的持续时间。有关更多详细信息，请参见 WriterTimes。
• disable_positive_acks：配置禁用肯定确认的设置。有关更多详细信息，请参见 DisablePositiveACKsQosPolicy。
• disable_heartbeat_piggyback：配置禁用心跳搭载机制的设置。有关更多详细信息，请参见 DisableHeartbeatPiggyback。

注意
此 QoS 策略适用于 DataWriter 实体。只有 DisablePositiveACKsQosPolicy 的 duration 数据成员和 times 数据成员可以在已启用的实体上修改。

WriterTimes¶

此结构定义与可靠写入器事件相关的时间。

结构成员列表：

• initial_heartbeat_delay：定义初始心跳延迟的持续时间。
• heartbeat_period：指定周期性心跳之间的间隔。
• nack_response_delay：确定应用于 ACKNACK 消息响应的延迟持续时间。
• nack_supression_duration：RTPSWriter 在发送数据后忽略接收到的 nack 消息，直到持续时间过去。

DisableHeartbeatPiggyback¶

除了使用 heartbeat_period 定期发送心跳（参见 WriterTimes）之外，可靠的 DataWriters 还使用一种机制在向 DataReaders 传递数据的同一消息中附加心跳子消息。此机制在必须更新可靠通信状态以保持最佳通信的特定情况下起作用：

• 当 DataWriter 向套接字发送的字节数与套接字缓冲区的长度相同时，在最后一个数据之后附加一个心跳子消息。
• 当 DataWriter 的历史记录已满时，DataWriter 开始在每个数据之后附加心跳子消息。

可以使用此策略禁用此机制。

示例¶

C++

// 本示例仅适用于 DataWriter 实体
DataWriterQos writer_qos;

// RTPSReliableWriterQos 默认构造为 initial_heartbeat_delay = 12 毫秒
// 将 initial_heartbeat_delay 更改为 20 纳秒
writer_qos.reliable_writer_qos().times.initial_heartbeat_delay = {0, 20};

// RTPSReliableWriterQos 默认构造为 heartbeat_period = 3 秒
// 将 heartbeat_period 更改为 5 秒
writer_qos.reliable_writer_qos().times.heartbeat_period = {5, 0};

// RTPSReliableWriterQos 默认构造为 nack_response_delay = 5 毫秒
// 将 nack_response_delay 更改为 10 纳秒
writer_qos.reliable_writer_qos().times.nack_response_delay = {0, 10};

// RTPSReliableWriterQos 默认构造为 nack_supression_duration = 0 秒
// 将 nack_supression_duration 更改为 20 纳秒
writer_qos.reliable_writer_qos().times.nack_supression_duration = {0, 20};

// 您也可以更改 DisablePositiveACKsQosPolicy。有关更多详细信息，请参见 DisablePositiveACKsQosPolicy 部分。
writer_qos.reliable_writer_qos().disable_positive_acks.enabled = true;

// RTPSReliableWriterQos 默认构造为 disable_heartbeat_piggyback = false
// 禁用心跳搭载机制。writer_qos.reliable_writer_qos().disable_heartbeat_piggyback = true;

// 在相应DataWriter实体的创建中使用修改后的QoS
writer_ = publisher_->create_datawriter(topic_, writer_qos);

XML

<data_writer profile_name="pub_profile_name">
    <times> <!-- writerTimesType -->
        <initial_heartbeat_delay> <!-- DURATION -->
            <nanosec>20</nanosec>
        </initial_heartbeat_delay>
        <heartbeat_period> <!-- DURATION -->
            <sec>5</sec>
        </heartbeat_period>
        <nack_response_delay> <!-- DURATION -->
            <nanosec>10</nanosec>
        </nack_response_delay>
        <nack_supression_duration> <!-- DURATION -->
            <nanosec>20</nanosec>
        </nack_supression_duration>
    </times>

    <!--也可更改DisablePositiveACKsQosPolicy的值。-->
    <!--详情参见DisablePositiveACKsQosPolicy部分-->
    <qos>
        <!--禁用心跳搭载机制。-->
        <disable_heartbeat_piggyback>true</disable_heartbeat_piggyback>
    </qos>
</data_writer>

3.1.2.2.5. FlowControllersQos¶

此QoS配置参与者的流控制器列表，以便这些流控制器之后可在其DataWriters上使用。它是指向FlowControllerDescriptor的共享指针的向量，FlowControllerDescriptor包含以下字段：

更多信息请参考流控制器部分。

注意
此QoS策略适用于DomainParticipant实体。已启用的实体上不能对其进行更改。

3.1.2.2.6. ParticipantResourceLimitsQos¶

此QoS配置内部资源的分配限制和物理内存使用情况。

QoS策略数据成员列表：

• locators：定义远程定位器集合的限制。
• participants：指定依赖于参与者总数的集合的分配行为和限制。
• readers：指定依赖于每个参与者的读取器总数的集合的分配行为和限制。
• writers：指定依赖于每个参与者的写入器总数的集合的分配行为和限制。
• send_buffers：定义发送缓冲区管理器的分配行为和限制。
• data_limits：规定变长数据的限制。
• content_filter：规定内容过滤器发现信息的限制。

注意
此QoS策略适用于DomainParticipant实体。已启用的实体上不能对其进行更改。

RemoteLocatorsAllocationAttributes¶

此结构包含远程定位器集合的限制。参见RemoteLocatorsAllocationAttributes。

结构成员列表：

• max_unicast_locators：此成员控制为每个发现的远程实体保留的最大单播定位器数量。建议使用属于同一域的所有系统上找到的最大本地地址数。
• max_multicast_locators：此成员控制为每个发现的远程实体保留的最大多播定位器数量。默认值通常足够，因为每个实体添加多个多播定位器没有意义。

ResourceLimitedContainerConfig¶

此结构包含资源受限集合的限制以及分配配置，分配配置可以是固定大小或动态大小。

结构成员列表：

• initial：指示要在集合中预分配的元素数量。
• maximum：指定集合中允许的最大元素数量。
• increment：规定当达到预留容量限制时要添加的项目数量。此成员的默认值取决于所选的分配配置。

SendBuffersAllocationAttributes¶

此结构包含发送缓冲区分配的限制。参见SendBuffersAllocationAttributes。

结构成员列表：

• preallocated_number：此成员控制要分配的初始发送缓冲区数量。默认值将根据可能启动发送操作的线程数量初步猜测所需的缓冲区数量。
• dynamic：此成员控制当发送缓冲区不可用时缓冲区管理器的行为。如果为true，将创建一个新缓冲区。否则，将等待缓冲区返回。
• network_buffers_config：此属性定义每个发送缓冲区中包含的网络缓冲区的分配行为和限制。默认值将预分配16个网络缓冲区，并在每次需要扩展向量时动态分配16个网络缓冲区。

注意
network_buffers_config还将用于实例化SerializedPayload_t向量，该向量包含在创建RTPS消息期间避免有效负载复制所需的元数据。

VariableLengthDataLimits¶

此结构包含变长数据的限制。参见VariableLengthDataLimits。

结构成员列表：

• max_properties：定义本地或远程参与者中属性数据的最大大小（以八位字节为单位）。
• max_user_data：规定本地或远程参与者中用户数据的最大大小（以八位字节为单位）。
• max_partitions：规定本地或远程参与者中分区数据的最大大小（以八位字节为单位）。

ContentFilterProperty::AllocationConfiguration¶

此结构包含与内容过滤器相关的发现信息的限制。参见ContentFilterProperty::AllocationConfiguration。

结构成员列表：

• expression_initial_size：过滤器表达式的预分配大小。
• expression_parameters：表达式参数列表的分配配置。

示例¶

C++

// 本示例仅适用于DomainParticipant实体
DomainParticipantQos participant_qos;

// 将参与者资源限制集合的最大大小设置为3，并将其分配配置设置为固定大小
participant_qos.allocation().participants =
        eprosima::fastdds::ResourceLimitedContainerConfig::fixed_size_configuration(
    3u);

// 将读取器的资源限制集合的最大大小设置为2，并将其分配配置设置为固定大小
participant_qos.allocation().readers =
        eprosima::fastdds::ResourceLimitedContainerConfig::fixed_size_configuration(2u);

// 将写入器的资源限制集合的最大大小设置为1，并将其分配配置设置为固定大小
participant_qos.allocation().writers =
        eprosima::fastdds::ResourceLimitedContainerConfig::fixed_size_configuration(1u);

// 将分区数据的最大大小设置为256
participant_qos.allocation().data_limits.max_partitions = 256u;

// 将用户数据的最大大小设置为256
participant_qos.allocation().data_limits.max_user_data = 256u;

// 将属性数据的最大大小设置为512
participant_qos.allocation().data_limits.max_properties = 512u;

// 将预分配的过滤器表达式大小设置为512
participant_qos.allocation().content_filter.expression_initial_size = 512u;

// 将表达式参数的最大数量设置为4，并将其分配配置设置为固定大小
participant_qos.allocation().content_filter.expression_parameters =
        eprosima::fastdds::ResourceLimitedContainerConfig::fixed_size_configuration(4u);

// 在相应DomainParticipant的创建中使用修改后的QoS
participant_ = factory_->create_participant(domain, participant_qos);

XML

<participant profile_name="participant_alloc_qos_example">
    <rtps>
        <allocation>
            <!-- 我们知道域上有3个参与者 -->
            <total_participants>
                <initial>3</initial>
                <maximum>3</maximum>
                <increment>0</increment>
            </total_participants>
            <!-- 我们知道每个参与者最多有2个读取器 -->
            <total_readers>
                <initial>2</initial>
                <maximum>2</maximum>
                <increment>0</increment>
            </total_readers>
            <!-- 我们知道每个参与者最多有1个写入器 -->
            <total_writers>
                <initial>1</initial>
                <maximum>1</maximum>
                <increment>0</increment>
            </total_writers>
            <max_partitions>256</max_partitions>
            <max_user_data>256</max_user_data>
            <max_properties>512</max_properties>

            <!-- 内容过滤器尚不能使用XML配置 -->
        </allocation>
    </rtps>
</participant>

3.1.2.2.7. PropertyPolicyQos¶

此附加QoS策略（PropertyPolicyQos）存储名称/值对，这些名称/值对可用于配置某些无法使用标准QoS策略直接配置的DDS设置。有关可使用此QoS策略配置的完整设置列表，请参考PropertyPolicyQos选项。

此QoS还允许添加可发送到外部实体的自定义用户属性。这可以通过将Property的propagate值设置为true来实现。

注意
此QoS策略适用于DomainParticipant、DataWriter和DataReader实体。已启用的实体上不能对其进行更改。

示例¶

C++

// 本示例使用DataWriter，但它也可应用于DomainParticipant和DataReader实体
DataWriterQos writer_qos;

// 为Auth:PKI-DH插件添加新属性
writer_qos.properties().properties().emplace_back("dds.sec.auth.plugin", "builtin.PKI-DH");

// 为Access:Permissions插件添加新属性
writer_qos.properties().properties().emplace_back(eprosima::fastdds::rtps::Property("dds.sec.access.plugin",
        "builtin.Access-Permissions"));

// 添加要发送到外部参与者的新用户自定义属性
writer_qos.properties().properties().emplace_back("Custom Property Name", "Custom value", true);


// Use modified QoS in the creation of the corresponding entity
writer_ = publisher_->create_datawriter(topic_, writer_qos);