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 usingdds_write
ordds_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
anddds_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
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 usingdds_write
ordds_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
-
dds_return_t dds_request_loan(dds_entity_t entity, void **sample)¶