Loaning

group loan

Functions

dds_return_t dds_return_loan(dds_entity_t entity, void **buf, int32_t bufsz)

Return loaned samples to a reader or writer

Used to release sample buffers returned by a read/take operation (a reader-loan) or, in case shared memory is enabled, of the loan_sample operation (a writer-loan).

When the application provides an empty buffer to a reader-loan, memory is allocated and managed by DDS. By calling dds_return_loan(), the reader-loan is released so that the buffer can be reused during a successive read/take operation. When a condition is provided, the reader to which the condition belongs is looked up.

Writer-loans are normally released implicitly when writing a loaned sample, but you can cancel a writer-loan prematurely by invoking the return_loan() operation. For writer loans, buf is overwritten with null pointers for all successfully returned entries. Any failure causes it to abort, possibly midway through buf.

Parameters

  • entity – [in] The entity that the loan belongs to.

  • buf – [inout] An array of (pointers to) samples, some or all of which will be set to null pointers.

  • bufsz – [in] The number of (pointers to) samples stored in buf.

Return values

  • DDS_RETCODE_OK –

    • the operation was successful; for a writer loan, all entries in buf are set to null

    • this specifically includes cases where bufsz <= 0 while entity is valid

  • DDS_RETCODE_BAD_PARAMETER –

    • the entity parameter is not a valid parameter

    • buf is null, or bufsz > 0 and buf[0] = null

    • (for writer loans) buf[0 <= i < bufsz] is null; operation is aborted, all buf[j < i] = null on return

  • DDS_RETCODE_PRECONDITION_NOT_MET –

    • (for reader loans) buf was already returned (not guaranteed to be detected)

    • (for writer loans) buf[0 <= i < bufsz] does not correspond to an outstanding loan, all buf[j < i] = null on return

  • DDS_RETCODE_UNSUPPORTED –

    • (for writer loans) invoked on a writer not supporting loans.

  • DDS_RETCODE_ILLEGAL_OPERATION –

    • the operation is invoked on an inappropriate object.

Returns

A dds_return_t indicating success or failure

bool dds_is_loan_available(const dds_entity_t entity)

Check if a Loan is available to reader/writer The loan is available if the shared memory is enabled and all the constraints to enable shared memory are met and the type is fixed.

Note

dds_loan_sample can be used if and only if dds_is_loan_available returns true.

Parameters

  • entity – [in] the handle of the entity

Returns

loan available or not

bool dds_is_shared_memory_available(const dds_entity_t entity)

Check if a shared memory is available to reader/writer.

Note

dds_loan_shared_memory_buffer can be used if and only if dds_is_shared_memory_available returns true.

Parameters

  • entity – [in] the handle of the entity

Returns

true if shared memory is available, false otherwise

dds_return_t dds_loan_shared_memory_buffer(dds_entity_t writer, size_t size, void **buffer)

Loan a shared memory buffer of a specific size from the writer.

Note

Currently this function is to be used with dds_writecdr by adding the loaned buffer to serdata as iox_chunk.

Note

The function can only be used if dds_is_shared_memory_available is true for the writer.

Parameters

  • writer – [in] the writer to loan the buffer from

  • size – [in] the requested buffer size

  • buffer – [out] the loaned buffer

Returns

DDS_RETCODE_OK if successful, DDS_RETCODE_ERROR otherwise

dds_return_t dds_loan_sample(dds_entity_t writer, void **sample)

Loan a sample from the writer.

Note

This function is to be used with dds_write to publish the loaned sample.

Note

The function can only be used if dds_is_loan_available is true for the writer.

Parameters

  • writer – [in] the writer to loan the buffer from

  • sample – [out] the loaned sample

Returns

DDS_RETCODE_OK if successful, DDS_RETCODE_ERROR otherwise