Skip to content

Commit 034d05e

Browse files
emiliocuestafemiliocuestaf
authored
Add documentation for type support context operations (#1240)
* Add documentation for type support context operations Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com> * Fix example Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com> * Fix rest of examples Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com> --------- Signed-off-by: Emilio Cuesta <emiliocuesta@eprosima.com>
1 parent 0e6e96b commit 034d05e

File tree

5 files changed

+155
-0
lines changed

5 files changed

+155
-0
lines changed

‎code/DDSCodeTester.cpp‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2161,6 +2161,16 @@ void dds_topic_examples()
21612161
//!--
21622162
}
21632163

2164+
{
2165+
//DDS_TYPE_SUPPORT_CONTEXT_DEF
2166+
struct MyContext : eprosima::fastdds::dds::TopicDataType::Context
2167+
{
2168+
uint32_t string_max_length = 256;
2169+
uint32_t sequence_max_length = 1024;
2170+
};
2171+
//!--
2172+
}
2173+
21642174
{
21652175
//DDS_DYNAMIC_TYPES_IDL_PARSING_CREATE_TYPE
21662176
// Create a DomainParticipant in the desired domain
@@ -3173,6 +3183,32 @@ void dds_dataWriter_examples()
31733183
//!--
31743184
}
31753185

3186+
{
3187+
//DDS_SET_TYPE_SUPPORT_CONTEXT_DW
3188+
// User-defined context struct carrying per-writer configuration.
3189+
struct MyContext : public TopicDataType::Context
3190+
{
3191+
uint32_t string_max_length = 0;
3192+
uint32_t sequence_max_length = 0;
3193+
};
3194+
3195+
// Create a DataWriter (initially disabled, e.g. via participant QoS).
3196+
DataWriterQos writer_qos = DATAWRITER_QOS_DEFAULT;
3197+
DataWriter* writer = publisher->create_datawriter(topic, writer_qos);
3198+
3199+
// Create a context carrying per-writer configuration.
3200+
auto context = std::make_shared<MyContext>();
3201+
context->string_max_length = 512;
3202+
context->sequence_max_length = 1024;
3203+
3204+
// Set it before enabling the DataWriter.
3205+
ReturnCode_t ret = writer->set_type_support_context(context);
3206+
assert(ret == RETCODE_OK);
3207+
3208+
// Then enable the writer (e.g., by enabling its DomainParticipant).
3209+
//!--
3210+
}
3211+
31763212
{
31773213
//DDS_DELETE_DATAWRITER
31783214
// Create a DataWriter
@@ -4053,6 +4089,32 @@ void dds_dataReader_examples()
40534089
//!--
40544090
}
40554091

4092+
{
4093+
//DDS_SET_TYPE_SUPPORT_CONTEXT_DR
4094+
// User-defined context struct carrying per-reader configuration.
4095+
struct MyContext : public TopicDataType::Context
4096+
{
4097+
uint32_t string_max_length = 0;
4098+
uint32_t sequence_max_length = 0;
4099+
};
4100+
4101+
// Create a DataReader (initially disabled, e.g. via participant QoS).
4102+
DataReaderQos reader_qos = DATAREADER_QOS_DEFAULT;
4103+
DataReader* reader = subscriber->create_datareader(topic, reader_qos);
4104+
4105+
// Create a context carrying per-reader configuration.
4106+
auto context = std::make_shared<MyContext>();
4107+
context->string_max_length = 512;
4108+
context->sequence_max_length = 1024;
4109+
4110+
// Set it before enabling the DataReader.
4111+
ReturnCode_t ret = reader->set_type_support_context(context);
4112+
assert(ret == RETCODE_OK);
4113+
4114+
// Then enable the reader (e.g., by enabling its DomainParticipant).
4115+
//!--
4116+
}
4117+
40564118
{
40574119
//DDS_DELETE_DATAREADER
40584120
// Create a DataReader

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -304,6 +304,19 @@
304304
.. |TopicDataType::getKey-api| replace:: :cpp:func:`getKey()<eprosima::fastdds::dds::TopicDataType::getKey>`
305305
.. |TopicDataType::is_bounded-api| replace:: :cpp:func:`is_bounded()<eprosima::fastdds::dds::TopicDataType::is_bounded>`
306306
.. |TopicDataType::m_isGetKeyDefined-api| replace:: :cpp:member:`m_isGetKeyDefined<eprosima::fastdds::dds::TopicDataType::m_isGetKeyDefined>`
307+
.. |TopicDataType::Context-api| replace:: :cpp:struct:`TopicDataType::Context<eprosima::fastdds::dds::TopicDataType::Context>`
308+
.. |TopicDataType::serialize_ctx-api| replace:: :cpp:func:`serialize_ctx()<eprosima::fastdds::dds::TopicDataType::serialize_ctx>`
309+
.. |TopicDataType::deserialize_ctx-api| replace:: :cpp:func:`deserialize_ctx()<eprosima::fastdds::dds::TopicDataType::deserialize_ctx>`
310+
.. |TopicDataType::calculate_serialized_size_ctx-api| replace:: :cpp:func:`calculate_serialized_size_ctx()<eprosima::fastdds::dds::TopicDataType::calculate_serialized_size_ctx>`
311+
.. |TopicDataType::create_data_ctx-api| replace:: :cpp:func:`create_data_ctx()<eprosima::fastdds::dds::TopicDataType::create_data_ctx>`
312+
.. |TopicDataType::delete_data_ctx-api| replace:: :cpp:func:`delete_data_ctx()<eprosima::fastdds::dds::TopicDataType::delete_data_ctx>`
313+
.. |TopicDataType::compute_key_ctx-api| replace:: :cpp:func:`compute_key_ctx()<eprosima::fastdds::dds::TopicDataType::compute_key_ctx>`
314+
.. |TopicDataType::is_bounded_ctx-api| replace:: :cpp:func:`is_bounded_ctx()<eprosima::fastdds::dds::TopicDataType::is_bounded_ctx>`
315+
.. |TopicDataType::is_plain_ctx-api| replace:: :cpp:func:`is_plain_ctx()<eprosima::fastdds::dds::TopicDataType::is_plain_ctx>`
316+
.. |TopicDataType::construct_sample_ctx-api| replace:: :cpp:func:`construct_sample_ctx()<eprosima::fastdds::dds::TopicDataType::construct_sample_ctx>`
317+
.. |TopicDataType::get_max_serialized_size_ctx-api| replace:: :cpp:func:`get_max_serialized_size_ctx()<eprosima::fastdds::dds::TopicDataType::get_max_serialized_size_ctx>`
318+
.. |DataWriter::set_type_support_context-api| replace:: :cpp:func:`DataWriter::set_type_support_context()<eprosima::fastdds::dds::DataWriter::set_type_support_context>`
319+
.. |DataReader::set_type_support_context-api| replace:: :cpp:func:`DataReader::set_type_support_context()<eprosima::fastdds::dds::DataReader::set_type_support_context>`
307320
.. |TopicDescription-api| replace:: :cpp:class:`TopicDescription<eprosima::fastdds::dds::TopicDescription>`
308321
.. |TopicListener-api| replace:: :cpp:class:`TopicListener<eprosima::fastdds::dds::TopicListener>`
309322
.. |TopicListener::on_inconsistent_topic-api| replace:: :cpp:func:`on_inconsistent_topic()<eprosima::fastdds::dds::TopicListener::on_inconsistent_topic>`

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -151,4 +151,22 @@ value |DataWriterQos::DataWriterQos-api|.
151151
|DataWriterQos::DataWriterQos-api|.
152152

153153

154+
.. _dds_layer_publisher_dataWriter_type_support_context:
155+
156+
Type support context
157+
--------------------
158+
159+
A DataWriter can be configured with a :ref:`type support context <dds_layer_topic_type_support_context>`
160+
that is forwarded to the |TopicDataType-api| callbacks on every write operation.
161+
This allows the type implementation to rely on per-writer information (e.g., bounded sizes)
162+
163+
The context must be set **before** enabling the DataWriter using
164+
|DataWriter::set_type_support_context-api|.
165+
Calling this method on an already-enabled DataWriter returns ``RETCODE_ILLEGAL_OPERATION``.
166+
167+
.. literalinclude:: /../code/DDSCodeTester.cpp
168+
:language: c++
169+
:start-after: //DDS_SET_TYPE_SUPPORT_CONTEXT_DW
170+
:end-before: //!
171+
:dedent: 8
154172

‎docs/fastdds/dds_layer/subscriber/dataReader/dataReader.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,3 +160,23 @@ value |DataReaderQos::DataReaderQos-api|.
160160
* On |Subscriber::set_default_datareader_qos-api| it refers
161161
to the default constructed |DataReaderQos::DataReaderQos-api|.
162162

163+
164+
.. _dds_layer_subscriber_dataReader_type_support_context:
165+
166+
Type support context
167+
--------------------
168+
169+
A DataReader can be configured with a :ref:`type support context <dds_layer_topic_type_support_context>`
170+
that is forwarded to the |TopicDataType-api| callbacks on every read operation.
171+
This allows the type implementation to rely on per-reader information (e.g., bounded sizes) without
172+
resorting to global state.
173+
174+
The context must be set **before** enabling the DataReader using
175+
|DataReader::set_type_support_context-api|.
176+
Calling this method on an already-enabled DataReader returns ``RETCODE_ILLEGAL_OPERATION``.
177+
178+
.. literalinclude:: /../code/DDSCodeTester.cpp
179+
:language: c++
180+
:start-after: //DDS_SET_TYPE_SUPPORT_CONTEXT_DR
181+
:end-before: //!
182+
:dedent: 8

‎docs/fastdds/dds_layer/topic/typeSupport/typeSupport.rst‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,3 +83,45 @@ from different sub-flows.
8383
The middleware keeps these sub-flows separated, but all will be restricted to the same QoS values of
8484
the Topic.
8585
If no key is provided, the data set associated with the Topic is restricted to a single flow.
86+
87+
88+
.. _dds_layer_topic_type_support_context:
89+
90+
Type support context
91+
--------------------
92+
93+
Fast DDS allows passing a user-defined *context* object to the type support callbacks, enabling
94+
type-specific information (e.g., upper bounds for strings and sequences) to be available during
95+
serialization, deserialization, and related operations without needing global state.
96+
97+
The context is represented by the |TopicDataType::Context-api| interface.
98+
Users subclass it to carry whatever per-endpoint information their type requires:
99+
100+
.. literalinclude:: /../code/DDSCodeTester.cpp
101+
:language: c++
102+
:start-after: //DDS_TYPE_SUPPORT_CONTEXT_DEF
103+
:end-before: //!
104+
:dedent: 8
105+
106+
The context-aware virtual methods of |TopicDataType-api| all follow the same pattern: they receive a
107+
``const std::shared_ptr<TopicDataType::Context>&`` as their first argument, and their default
108+
implementation ignores the context and delegates to the corresponding context-free method.
109+
Users may override any subset of the following methods:
110+
111+
- |TopicDataType::serialize_ctx-api| — serialize a sample using the context.
112+
- |TopicDataType::deserialize_ctx-api| — deserialize a payload using the context.
113+
- |TopicDataType::calculate_serialized_size_ctx-api| — compute the serialized size with the context.
114+
- |TopicDataType::create_data_ctx-api| — allocate a new sample using the context.
115+
- |TopicDataType::delete_data_ctx-api| — deallocate a sample using the context.
116+
- |TopicDataType::compute_key_ctx-api| — extract the key using the context.
117+
- |TopicDataType::is_bounded_ctx-api| — check whether the type is bounded with this context.
118+
- |TopicDataType::is_plain_ctx-api| — check whether the type is plain with this context.
119+
- |TopicDataType::construct_sample_ctx-api| — in-place construct a sample using the context.
120+
- |TopicDataType::get_max_serialized_size_ctx-api| — return the maximum serialized size with this context.
121+
122+
The context is attached to a :ref:`dds_layer_publisher_dataWriter` or
123+
:ref:`dds_layer_subscriber_dataReader` **before enabling** the entity, using
124+
|DataWriter::set_type_support_context-api| or |DataReader::set_type_support_context-api|
125+
respectively.
126+
Because the context is set before the entity is enabled, it is guaranteed to be available for every
127+
write or read operation performed during the entity's lifetime.

0 commit comments

Comments
 (0)