Loan mechanism

When using shared memory exchange, additional performance gains can be made by using the loan mechanism on the writer side. The loan mechanism directly allocates memory from the Eclipse iceoryx shared memory pool, and provides this to the user as a message data type. This eliminates a copy step in the publication process.

struct message_type *loaned_sample;
dds_return_t status = dds_loan_sample (writer, (void**)&loaned_sample);

If status returns DDS_RETCODE_OK, then loaned_sample contains a pointer to the memory pool object, in all other cases, loaned_sample should not be dereferenced.

Necessary information about the data type is supplied by the writer. When requesting loaned samples, the writer used to request the loaned sample must be the same data type as the sample that you are writing in it.

When requesting loaned samples, the maximum number of outstanding loans is defined by MAX_PUB_LOANS (default set to 8). This is the maximum number of loaned samples that each publisher can have outstanding from the shared memory. If the maximum is reached, to request new loaned samples, some must be returned (handed back to the publisher) through dds_write().

Note

When a loaned sample has been returned to the shared memory pool (by invoking dds_write()), dereferencing the pointer is undefined behaviour.

If Cyclone DDS is configured to use shared memory, but it is not possible to use the loan mechanism, a dds_write() still writes to the shared memory service. This increases the overhead by an additional copy step in publication. That is, when a block for publishing to the shared memory is requested, the data of the published sample is copied into it.