Function dds_return_loan

Function Documentation

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