# Loaning

group (Loans API)

  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