Loaning samples in DataWriter (#229)

Signed-off-by: Iker Luengo <ikerluengo@eprosima.com>

Author: IkerLuengo

code/DDSCodeTester.cpp

@@ -1870,6 +1870,38 @@ void dds_dataWriter_examples()
         // but delete it at the end to avoid leaks
         custom_type_support->deleteData(data);
         //!--
+
+        {
+        //DDS_DATAWRITER_LOAN_SAMPLES
+        // Borrow a data instance
+        void* data = nullptr;
+        if (ReturnCode_t::RETCODE_OK == data_writer->loan_sample(data))
+        {
+            bool error = false;
+
+            // Fill the data values
+            // (...)
+
+            if (error)
+            {
+                // Return the loan without publishing
+                data_writer->discard_loan(data);
+                return;
+            }
+
+            // Publish the new value
+            if (data_writer->write(data, eprosima::fastrtps::rtps::InstanceHandle_t()) != ReturnCode_t::RETCODE_OK)
+            {
+                // Error
+                return;
+            }
+        }
+
+        // The data instance can be reused to publish new values,
+        // but delete it at the end to avoid leaks
+        custom_type_support->deleteData(data);
+        //!--
+        }
     }
 }
 

docs/03-exports/aliases-api.include

@@ -58,6 +58,8 @@
 .. |DataWriter::get_qos-api| replace:: :cpp:func:`get_qos()<eprosima::fastdds::dds::DataWriter::get_qos>`
 .. |DataWriter::set_qos-api| replace:: :cpp:func:`DataWriter::set_qos()<eprosima::fastdds::dds::DataWriter::set_qos>`
 .. |DataWriter::write-api| replace:: :cpp:func:`write()<eprosima::fastdds::dds::DataWriter::write>`
+.. |DataWriter::loan_sample-api| replace:: :cpp:func:`loan_sample()<eprosima::fastdds::dds::DataWriter::loan_sample>`
+.. |DataWriter::discard_loan-api| replace:: :cpp:func:`discard_loan()<eprosima::fastdds::dds::DataWriter::discard_loan>`
 .. |DataWriterListener-api| replace:: :cpp:class:`DataWriterListener <eprosima::fastdds::dds::DataWriterListener>`
 
 .. |DataWriter::get_offered_deadline_missed_status-api| replace:: :cpp:func:`get_offered_deadline_missed_status()<eprosima::fastdds::dds::DataWriter::get_offered_deadline_missed_status>`

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

@@ -49,4 +49,37 @@ If ``max_blocking_time`` elapses before the DataWriter is able to store
 the modification without exceeding the limits, the write operation will fail and return ``TIMEOUT``.
 
 
+.. _dds_layer_publisher_write_loans:
 
+Borrowing a data buffer
+-----------------------
+
+When the user calls |DataWriter::write-api| with a new sample value,
+the data is copied from the given sample to the DataWriter's memory.
+For large data types this copy can consume significant time and memory resources.
+Instead, the DataWriter can loan a sample from its memory to the user,
+and the user can fill this sample with the required values.
+When |DataWriter::write-api| is called with such a loaned sample,
+the DataWriter does not copy its contents, as it already owns the buffer.
+
+To use loaned data samples in publications, perform the following steps:
+
+1. Get a reference to a loaned sample using |DataWriter::loan_sample-api|.
+2. Use the reference to build the data sample.
+3. Write the sample using |DataWriter::write-api|.
+
+
+Once |DataWriter::write-api| has been called with a loaned sample,
+the loan is considered returned, and it is not safe to make any
+changes on the contents of the sample.
+
+If function |DataWriter::loan_sample-api| is called but the sample is never written,
+the loan must be returned to the DataWriter using |DataWriter::discard_loan-api|.
+Otherwise the DataWriter may run out of samples.
+
+
+.. literalinclude:: /../code/DDSCodeTester.cpp
+   :language: c++
+   :start-after: //DDS_DATAWRITER_LOAN_SAMPLES
+   :end-before: //!
+   :dedent: 8