Loaning

group loan

Functions

dds_return_t dds_request_loan(dds_entity_t entity, void **sample)

Request a loan from an entity.

Borrow a sample from the entity, which currently must be a writer. This sample can then be returned using dds_return_loan or can be used to publish data using dds_write or dds_writedispose.

If the topic type has a fixed size (and so no internal pointers) and a PSMX interface is configured, the memory will be borrowed from the PSMX implementation, which allows Cyclone to avoid copies and/or serialization if there is no need for sending the data over a network interface or storing it in the WHC.

Parameters

  • entity – [in] The entity to request loans from.

  • sample – [out] Where to store the address of the loaned sample.

Return values

  • DDS_RETCODE_OK – The operation was successful.

  • DDS_RETCODE_BAD_PARAMETER – One or more parameters are invalid.

  • DDS_RETCODE_ILLEGAL_OPERATION – The operation is invoked on an inappropriate object.

  • DDS_RETCODE_ALREADY_DELETED – The entity has already been deleted.

  • DDS_RETCODE_ERROR – An unfortunate incident occurred.

Returns

A dds_return_t indicating success or failure.

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 middleware-owned samples returned by a read/take operation and samples borrowed from the writer using dds_request_loan.

For reader loans, the dds_read and dds_take operations implicitly return outstanding loans referenced by the sample array passed in. Looping until no data is returned therefore often eliminates the need for calling this function.

For writer loans, a dds_write operation takes over the loan. Consequently, this function is only needed in the exceptional case where a loan is taken but ultimately not used to publish data.

Parameters

  • entity – [in] The entity that the loan(s) belong to. If a read or query condition is passed in for the entity, the reader for that condition is used.

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

  • bufsz – [in] The size of the buffer.

Return values

  • DDS_RETCODE_OK –

    • the operation was successful

    • a no-op if bufsz <= 0, otherwise

    • buf[0] .. buf[k-1] were successfully returned loans, k = bufsz or buf[k] = null

    • buf[0] is set to a null pointer, buf[k > 0] undefined

  • DDS_RETCODE_BAD_PARAMETER –

    • the entity parameter is not a valid parameter

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

    • a non-loan was encountered (all loans are still returned)

  • DDS_RETCODE_PRECONDITION_NOT_MET –

    • bufsz > 0 and buf[0] != null but not a loan, nothing done

  • 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_shared_memory_available(const dds_entity_t entity)

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

Note

dds_request_loan_of_size 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_request_loan_of_size(dds_entity_t writer, size_t size, void **sample)

Request a loan of a specified size from an entity.

Borrow a sample of a specified size from the entity, which currently must be a writer. This sample can then be returned using dds_return_loan or can be used to publish data using dds_write or dds_writedispose.

Note

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

Parameters

  • writer – [in] The entity to request loans from.

  • size – [in] the requested loan size

  • sample – [out] Where to store the address of the loaned sample.

Returns

DDS_RETCODE_OK if successful, DDS_RETCODE_ERROR otherwise