Skip to content

Commit 4b8d976

Browse files
Mario-DLMario-DL
authored
Add DataWriter sample prefilter documentation (#1077)
* Refs #23264: Add prefilter feature documentation Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com> * Refs #23264: Update due to impl review Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com> * Refs #23264: Add Miguel's advice Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com> * Refs #23264: Apply Miguel's review Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com> --------- Signed-off-by: Mario Dominguez <mariodominguez@eprosima.com>
1 parent f3f2d34 commit 4b8d976

4 files changed

Lines changed: 130 additions & 0 deletions

File tree

‎code/DDSCodeTester.cpp‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3285,6 +3285,96 @@ void dds_dataWriter_examples()
32853285
//!
32863286
}
32873287
}
3288+
3289+
{
3290+
//DDS_DATAWRITER_SAMPLE_PREFILTER
3291+
struct CustomUserWriteData : public eprosima::fastdds::rtps::WriteParams::UserWriteData
3292+
{
3293+
CustomUserWriteData(
3294+
const eprosima::fastdds::rtps::GuidPrefix_t& prefix)
3295+
: filtered_out_prefix(prefix)
3296+
{
3297+
}
3298+
3299+
eprosima::fastdds::rtps::GuidPrefix_t filtered_out_prefix;
3300+
};
3301+
3302+
struct CustomPreFilter : public eprosima::fastdds::dds::IContentFilter
3303+
{
3304+
// Custom evaluation
3305+
bool evaluate(
3306+
const SerializedPayload& payload,
3307+
const FilterSampleInfo& filter_sample_info,
3308+
const eprosima::fastdds::rtps::GUID_t& reader_guid) const override
3309+
{
3310+
static_cast<void>(payload);
3311+
static_cast<void>(filter_sample_info);
3312+
3313+
bool sample_should_be_sent = true;
3314+
3315+
auto custom_write_data =
3316+
std::static_pointer_cast<CustomUserWriteData>(
3317+
filter_sample_info.user_write_data);
3318+
3319+
// If the reader is the one to filter out, do not send the sample
3320+
if (custom_write_data->filtered_out_prefix == reader_guid.guidPrefix)
3321+
{
3322+
sample_should_be_sent = false;
3323+
}
3324+
return sample_should_be_sent;
3325+
}
3326+
3327+
};
3328+
3329+
// Create a DataWriter
3330+
DataWriter* data_writer =
3331+
publisher->create_datawriter(topic, DATAWRITER_QOS_DEFAULT);
3332+
if (nullptr == data_writer)
3333+
{
3334+
// Error
3335+
return;
3336+
}
3337+
3338+
// Set a prefilter on the filtered reader
3339+
eprosima::fastdds::dds::ReturnCode_t ret = data_writer->set_sample_prefilter(
3340+
std::make_shared<CustomPreFilter>());
3341+
3342+
if (ret != eprosima::fastdds::dds::RETCODE_OK)
3343+
{
3344+
// Error
3345+
return;
3346+
}
3347+
3348+
// Create a custom user write data
3349+
eprosima::fastdds::rtps::GuidPrefix_t filtered_out_prefix;
3350+
filtered_out_prefix.value[0] = 0x01; // Example prefix to filter out
3351+
filtered_out_prefix.value[1] = eprosima::fastdds::rtps::octet(0x73);
3352+
filtered_out_prefix.value[2] = eprosima::fastdds::rtps::octet(0x71);
3353+
filtered_out_prefix.value[3] = eprosima::fastdds::rtps::octet(0x85);
3354+
filtered_out_prefix.value[4] = eprosima::fastdds::rtps::octet(0x69);
3355+
filtered_out_prefix.value[5] = eprosima::fastdds::rtps::octet(0x76);
3356+
filtered_out_prefix.value[6] = eprosima::fastdds::rtps::octet(0x95);
3357+
filtered_out_prefix.value[7] = eprosima::fastdds::rtps::octet(0x66);
3358+
filtered_out_prefix.value[8] = eprosima::fastdds::rtps::octet(0x65);
3359+
filtered_out_prefix.value[9] = eprosima::fastdds::rtps::octet(0x82);
3360+
filtered_out_prefix.value[10] = eprosima::fastdds::rtps::octet(0x82);
3361+
filtered_out_prefix.value[11] = eprosima::fastdds::rtps::octet(0x79);
3362+
3363+
std::shared_ptr<CustomUserWriteData> custom_write_data =
3364+
std::make_shared<CustomUserWriteData>(filtered_out_prefix);
3365+
3366+
// Set the custom user write data
3367+
eprosima::fastdds::rtps::WriteParams write_params;
3368+
write_params.user_write_data(custom_write_data);
3369+
3370+
HelloWorld sample; //Auto-generated container class for topic data from Fast DDS-Gen
3371+
sample.msg("Hello there!"); // Add contents to the message
3372+
3373+
// Write a sample with the custom user write data
3374+
data_writer->write(&sample, write_params);
3375+
3376+
//!--
3377+
}
32883378
}
32893379

32903380
//DDS_SUBSCRIBER_LISTENER_SPECIALIZATION

‎docs/03-exports/aliases-api.include‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,7 @@
8888
.. |DataWriter::register_instance_w_timestamp| replace:: :cpp:func:`DataWriter::register_instance_w_timestamp()<eprosima::fastdds::dds::DataWriter::register_instance_w_timestamp>`
8989
.. |DataWriter::unregister_instance_w_timestamp| replace:: :cpp:func:`DataWriter::unregister_instance_w_timestamp()<eprosima::fastdds::dds::DataWriter::unregister_instance_w_timestamp>`
9090
.. |DataWriter::dispose_w_timestamp| replace:: :cpp:func:`DataWriter::dispose_w_timestamp()<eprosima::fastdds::dds::DataWriter::dispose_w_timestamp>`
91+
.. |DataWriter::set_sample_prefilter| replace:: :cpp:func:`DataWriter::set_sample_prefilter()<eprosima::fastdds::dds::DataWriter::set_sample_prefilter>`
9192

9293
.. |DataWriterListener-api| replace:: :cpp:class:`DataWriterListener <eprosima::fastdds::dds::DataWriterListener>`
9394

@@ -238,6 +239,8 @@
238239

239240
.. |IContentFilter-api| replace:: :cpp:class:`IContentFilter<eprosima::fastdds::dds::IContentFilter>`
240241
.. |IContentFilter::evaluate-api| replace:: :cpp:func:`evaluate()<eprosima::fastdds::dds::IContentFilter::evaluate>`
242+
.. |FilteredSampleInfo-api| replace:: :cpp:class:`FilteredSampleInfo<eprosima::fastdds::dds::IContentFilter::FilteredSampleInfo>`
243+
.. |FilteredSampleInfo::user_write_data-api| replace:: :cpp:member:`user_write_data<eprosima::fastdds::dds::IContentFilter::FilteredSampleInfo::user_write_data>`
241244
.. |IContentFilterFactory-api| replace:: :cpp:class:`IContentFilterFactory<eprosima::fastdds::dds::IContentFilterFactory>`
242245
.. |IContentFilterFactory::create_content_filter-api| replace:: :cpp:func:`create_content_filter()<eprosima::fastdds::dds::IContentFilterFactory::create_content_filter>`
243246
.. |IContentFilterFactory::delete_content_filter-api| replace:: :cpp:func:`delete_content_filter()<eprosima::fastdds::dds::IContentFilterFactory::delete_content_filter>`
@@ -1122,6 +1125,7 @@
11221125
.. |WriteParams-api| replace:: :cpp:class:`WriteParams <eprosima::fastdds::rtps::WriteParams>`
11231126
.. |WriteParams-sample_identity-api| replace:: :cpp:func:`sample_identity() <eprosima::fastdds::rtps::WriteParams::sample_identity>`
11241127
.. |WriteParams-related_sample_identity-api| replace:: :cpp:func:`related_sample_identity() <eprosima::fastdds::rtps::WriteParams::related_sample_identity>`
1128+
.. |WriteParams-user_write_data-api| replace:: :cpp:func:`user_write_data() <eprosima::fastdds::rtps::WriteParams::user_write_data>`
11251129

11261130
.. |ThreadSettings::scheduling_policy-api| replace:: :cpp:member:`scheduling_policy<eprosima::fastdds::rtps::ThreadSettings::scheduling_policy>`
11271131
.. |ThreadSettings::priority-api| replace:: :cpp:member:`priority<eprosima::fastdds::rtps::ThreadSettings::priority>`

‎docs/fastdds/dds_layer/publisher/dataWriter/publishingData.rst‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,3 +83,35 @@ Otherwise the DataWriter may run out of samples.
8383
:start-after: //DDS_DATAWRITER_LOAN_SAMPLES
8484
:end-before: //!
8585
:dedent: 8
86+
87+
.. _dds_layer_publisher_prefiltering:
88+
89+
Prefiltering out DataReaders
90+
----------------------------
91+
92+
The user can use an overload of the |DataWriter::write-api| method that allows providing a |WriteParams-api| structure.
93+
One of the members of this latter structure is the |WriteParams-user_write_data-api| in which the user
94+
can store extra information to be used by the prefiltering mechanism.
95+
96+
By implementing the |IContentFilter-api| and passing it to the DataWriter with |DataWriter::set_sample_prefilter|,
97+
user can prevent the DataWriter from sending samples to the matched DataReaders based on both:
98+
the content of the sample (|SerializedPayload_t-api|) and/or the |WriteParams-user_write_data-api|
99+
within |FilteredSampleInfo::user_write_data-api|.
100+
If the return value of |IContentFilter::evaluate-api| is ``false``, the sample will not be sent to the DataReader
101+
identified by its |Guid_t-api| in the method's input argument.
102+
It is strongly recommended that the |IContentFilter::evaluate-api| implementation neither performs any blocking
103+
operation nor uses the DataWriter, as this may lead to deadlocks or undesired behavior.
104+
105+
.. warning::
106+
107+
Prefiltering is currently incompatible with :ref:`datasharingqospolicy`.
108+
Hence, ensure that the |DataSharingQosPolicy::kind-api| is set to ``OFF`` or
109+
if ``AUTO`` is used, :ref:`constraints<datasharing-delivery-constraints>` are not met.
110+
111+
Next is an example of how to use the prefiltering mechanism:
112+
113+
.. literalinclude:: /../code/DDSCodeTester.cpp
114+
:language: c++
115+
:start-after: //DDS_DATAWRITER_SAMPLE_PREFILTER
116+
:end-before: //!
117+
:dedent: 8

‎docs/spelling_wordlist.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -239,6 +239,10 @@ preallocated
239239
preallocates
240240
preallocation
241241
preconfigure
242+
prefilter
243+
Prefilter
244+
prefiltering
245+
Prefiltering
242246
prepended
243247
preprocessor
244248
programmatically

0 commit comments

Comments
 (0)