RTPS payload pool (#202)

* RTPS payload pool (#199) * Refs 9544. Adding new interfaces to API-ref Signed-off-by: Iker Luengo <ikerluengo@eprosima.com> * Refs 9544. alias for references to API-ref Signed-off-by: Iker Luengo <ikerluengo@eprosima.com> * Refs 9544. Update RTPS doc with references to API-ref Signed-off-by: Iker Luengo <ikerluengo@eprosima.com> * Refs 9544. Documentation of Payload pool Signed-off-by: Iker Luengo <ikerluengo@eprosima.com> * Refs 9544. Example with custom Payload pool Signed-off-by: Iker Luengo <ikerluengo@eprosima.com> * Refs 9544. Suggestions and documentation check errors Signed-off-by: Iker Luengo <ikerluengo@eprosima.com> * Apply suggestions from code review Co-authored-by: Eduardo Ponz Segrelles <eduardoponz@eprosima.com> * Alphabetical order. Signed-off-by: Miguel Company <MiguelCompany@eprosima.com> * Explicitly indicating overloaded methods Signed-off-by: Miguel Company <MiguelCompany@eprosima.com> * Adding links to examples. Signed-off-by: Miguel Company <MiguelCompany@eprosima.com> Co-authored-by: IkerLuengo <57146230+IkerLuengo@users.noreply.github.com> Co-authored-by: Eduardo Ponz Segrelles <eduardoponz@eprosima.com>
eProsima · Nov 17, 2020 · f4c0477 · f4c0477
1 parent c64c700
commit f4c0477
Show file tree

Hide file tree

Showing 7 changed files with 307 additions and 22 deletions.
diff --git a/code/CodeTester.cpp b/code/CodeTester.cpp
@@ -933,16 +933,113 @@ void rtps_api_example_create_entities()
     }
 
     //RTPS_API_WRITE_SAMPLE
-    //Request a change from the history
+    //Request a change from the writer
     CacheChange_t* change = writer->new_change([]() -> uint32_t {
         return 255;
     }, ALIVE);
     //Write serialized data into the change
     change->serializedPayload.length = sprintf((char*) change->serializedPayload.data, "My example string %d", 2) + 1;
-    //Insert change back into the history. The Writer takes care of the rest.
+    //Insert change into the history. The Writer takes care of the rest.
     history->add_change(change);
     //!--
+}
+
+
+void rtps_api_example_create_entities_with_custom_pool()
+{
+    RTPSParticipantAttributes participant_attr;
+    participant_attr.setName("participant");
+    RTPSParticipant* participant = RTPSDomain::createParticipant(0, participant_attr);
+
+    //RTPS_API_ENTITY_CREATE_WITH_PAYLOAD_POOL
+    // A simple payload pool that reserves and frees memory each time
+    class CustomPayloadPool : public IPayloadPool
+    {
+        bool get_payload(
+                uint32_t size,
+                CacheChange_t& cache_change) override
+        {
+            // Reserve new memory for the payload buffer
+            octet* payload = new octet[size];
+
+            // Assign the payload buffer to the CacheChange and update sizes
+            cache_change.serializedPayload.data = payload;
+            cache_change.serializedPayload.length = size;
+            cache_change.serializedPayload.max_size = size;
+
+            // Tell the CacheChange who needs to release its payload
+            cache_change.payload_owner(this);
+
+            return true;
+        }
+
+        bool get_payload(
+                SerializedPayload_t& data,
+                IPayloadPool*& /* data_owner */,
+                CacheChange_t& cache_change) override
+        {
+            // Reserve new memory for the payload buffer
+            octet* payload = new octet[data.length];
+
+            // Copy the data
+            memcpy(payload, data.data, data.length);
+
+            // Assign the payload buffer to the CacheChange and update sizes
+            cache_change.serializedPayload.data = payload;
+            cache_change.serializedPayload.length = data.length;
+            cache_change.serializedPayload.max_size = data.length;
+
+            // Tell the CacheChange who needs to release its payload
+            cache_change.payload_owner(this);
+
+            return true;
+        }
 
+        bool release_payload(
+                CacheChange_t& cache_change) override
+        {
+            // Ensure precondition
+            assert(this == cache_change.payload_owner());
+
+            // Dealloc the buffer of the payload
+            delete[] cache_change.serializedPayload.data;
+
+            // Reset sizes and pointers
+            cache_change.serializedPayload.data = nullptr;
+            cache_change.serializedPayload.length = 0;
+            cache_change.serializedPayload.max_size = 0;
+
+            // Reset the owner of the payload
+            cache_change.payload_owner(nullptr);
+
+            return true;
+        }
+    };
+
+    std::shared_ptr<CustomPayloadPool> payload_pool = std::make_shared<CustomPayloadPool>();
+
+    // A writer using the custom payload pool
+    HistoryAttributes writer_history_attr;
+    WriterHistory* writer_history = new WriterHistory(writer_history_attr);
+    WriterAttributes writer_attr;
+    RTPSWriter* writer = RTPSDomain::createRTPSWriter(participant, writer_attr, payload_pool, writer_history);
+
+    // A reader using the same instance of the custom payload pool
+    HistoryAttributes reader_history_attr;
+    ReaderHistory* reader_history = new ReaderHistory(reader_history_attr);
+    ReaderAttributes reader_attr;
+    RTPSReader* reader = RTPSDomain::createRTPSReader(participant, reader_attr, payload_pool, reader_history);
+
+    // Write and Read operations work as usual, but take the Payloads from the pool.
+    // Requesting a change to the Writer will provide one with an empty Payload taken from the pool
+    CacheChange_t* change = writer->new_change([]() -> uint32_t {
+        return 255;
+    }, ALIVE);
+
+    // Write serialized data into the change and add it to the history
+    change->serializedPayload.length = sprintf((char*) change->serializedPayload.data, "My example string %d", 2) + 1;
+    writer_history->add_change(change);
+    //!--
 }
 
 void rtps_api_example_conf()

diff --git a/docs/03-exports/aliases-api.include b/docs/03-exports/aliases-api.include
@@ -579,10 +579,39 @@
 .. |DomainId-api| replace:: :cpp:type:`DomainId <dds::fastdds::eprosima::DomainId_t>`
 .. |c_InstanceHandle_Unknown-api| replace:: :cpp:member:`c_InstanceHandle_Unknown <rtps::fastrtps::eprosima::c_InstanceHandle_Unknown>`
 
+.. |RTPSDomain-api| replace:: :cpp:class:`RTPSDomain <eprosima::fastrtps::rtps::RTPSDomain>`
+.. |RTPSDomain::createParticipant-api| replace:: :cpp:func:`RTPSDomain::createParticipant() <eprosima::fastrtps::rtps::RTPSDomain::createParticipant>`
+.. |RTPSDomain::createRTPSWriter-api| replace:: :cpp:func:`RTPSDomain::createRTPSWriter() <eprosima::fastrtps::rtps::RTPSDomain::createRTPSWriter>`
+.. |RTPSDomain::createRTPSReader-api| replace:: :cpp:func:`RTPSDomain::createRTPSReader() <eprosima::fastrtps::rtps::RTPSDomain::createRTPSReader>`
+
 .. |RTPSParticipants-api| replace:: :cpp:class:`RTPSParticipants <eprosima::fastrtps::rtps::RTPSParticipant>`
 .. |RTPSParticipant-api| replace:: :cpp:class:`RTPSParticipant <eprosima::fastrtps::rtps::RTPSParticipant>`
+.. |RTPSParticipantAttributes-api| replace:: :cpp:class:`RTPSParticipantAttributes<eprosima::fastrtps::rtps::RTPSParticipantAttributes>`
+
 .. |RTPSReaders-api| replace:: :cpp:class:`RTPSReaders <eprosima::fastrtps::rtps::RTPSReader>`
+.. |ReaderAttributes-api| replace:: :cpp:class:`ReaderAttributes<eprosima::fastrtps::rtps::ReaderAttributes>`
+.. |ReaderListener-api| replace:: :cpp:class:`ReaderListener<eprosima::fastrtps::rtps::ReaderListener>`
+.. |ReaderListener::onNewCacheChangeAdded-api| replace:: :cpp:func:`ReaderListener::onNewCacheChangeAdded<eprosima::fastrtps::rtps::ReaderListener::onNewCacheChangeAdded>`
+
 .. |RTPSWriters-api| replace:: :cpp:class:`RTPSWriters <eprosima::fastrtps::rtps::RTPSWriter>`
+.. |WriterAttributes-api| replace:: :cpp:class:`WriterAttributes<eprosima::fastrtps::rtps::WriterAttributes>`
+.. |RTPSWriters::new_change-api| replace:: :cpp:func:`RTPSWriter::new_change() <eprosima::fastrtps::rtps::RTPSWriter::new_change>`
+
+.. |History-api| replace:: :cpp:class:`History <eprosima::fastrtps::rtps::History>`
+.. |WriterHistory-api| replace:: :cpp:class:`WriterHistory <eprosima::fastrtps::rtps::WriterHistory>`
+.. |WriterHistory::add_change-api| replace:: :cpp:func:`WriterHistory::add_change() <eprosima::fastrtps::rtps::WriterHistory::add_change>`
+.. |ReaderHistory-api| replace:: :cpp:class:`ReaderHistory <eprosima::fastrtps::rtps::ReaderHistory>`
+.. |CacheChange_t-api| replace:: :cpp:class:`CacheChange_t<eprosima::fastrtps::rtps::CacheChange_t>`
+
+.. |HistoryAttributes-api| replace:: :cpp:class:`HistoryAttributes<eprosima::fastrtps::rtps::HistoryAttributes>`
+.. |HistoryAttributes::memoryPolicy-api| replace:: :cpp:member:`memoryPolicy<eprosima::fastrtps::rtps::HistoryAttributes::memoryPolicy>`
+.. |HistoryAttributes::payloadMaxSize-api| replace:: :cpp:member:`payloadMaxSize<eprosima::fastrtps::rtps::HistoryAttributes::payloadMaxSize>`
+.. |HistoryAttributes::initialReservedCaches-api| replace:: :cpp:member:`initialReservedCaches<eprosima::fastrtps::rtps::HistoryAttributes::initialReservedCaches>`
+
+.. |IPayloadPool-api| replace:: :cpp:class:`IPayloadPool <eprosima::fastrtps::rtps::IPayloadPool>`
+.. |IPayloadPool::get_payload-api| replace:: :cpp:func:`IPayloadPool::get_payload <eprosima::fastrtps::rtps::IPayloadPool::get_payload>`
+.. |IPayloadPool::release_payload-api| replace:: :cpp:func:`IPayloadPool::release_payload <eprosima::fastrtps::rtps::IPayloadPool::release_payload>`
+
 
 .. |DiscoverySettings-api| replace:: :cpp:class:`DiscoverySettings <eprosima::fastrtps::rtps::DiscoverySettings>`
 .. |leaseDuration_announcementperiod| replace:: :cpp:member:`leaseDuration_announcementperiod <eprosima::fastrtps::rtps::DiscoverySettings::leaseDuration_announcementperiod>`

diff --git a/docs/fastdds/api_reference/rtps/history/IChangePool.rst b/docs/fastdds/api_reference/rtps/history/IChangePool.rst
@@ -0,0 +1,8 @@
+.. rst-class:: api-ref
+
+IChangePool
+--------------------------------
+
+.. doxygenclass:: eprosima::fastrtps::rtps::IChangePool
+    :project: FastDDS
+    :members:
diff --git a/docs/fastdds/api_reference/rtps/history/IPayloadPool.rst b/docs/fastdds/api_reference/rtps/history/IPayloadPool.rst
@@ -0,0 +1,8 @@
+.. rst-class:: api-ref
+
+IPayloadPool
+--------------------------------
+
+.. doxygenclass:: eprosima::fastrtps::rtps::IPayloadPool
+    :project: FastDDS
+    :members:
diff --git a/docs/fastdds/api_reference/rtps/history/history.rst b/docs/fastdds/api_reference/rtps/history/history.rst
@@ -6,6 +6,8 @@ History
 .. toctree::
 
     /fastdds/api_reference/rtps/history/History_class
+    /fastdds/api_reference/rtps/history/IChangePool
+    /fastdds/api_reference/rtps/history/IPayloadPool
     /fastdds/api_reference/rtps/history/ReaderHistory
     /fastdds/api_reference/rtps/history/WriterHistory