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

Loaned Samples

group loaned_sample

Typedefs

typedef enum dds_loaned_sample_state dds_loaned_sample_state_t

State of the data contained in a memory block.

typedef uint32_t dds_loan_data_type_t

Identifier used to distinguish between raw data types (C/C++/Python/…)

void(* dds_loaned_sample_free_f )(struct dds_loaned_sample *loaned_sample) ddsrt_nonnull_all

Definition for function to free a loaned sample.

Param loaned_sample

[in] A loaned sample

typedef struct dds_loaned_sample_ops dds_loaned_sample_ops_t

Container for implementation specific operations.

typedef struct dds_loaned_sample dds_loaned_sample_t

The definition of a block of memory originating from a PSMX.

Enums

enum dds_loaned_sample_state

State of the data contained in a memory block.

Values:

enumerator DDS_LOANED_SAMPLE_STATE_UNITIALIZED

enumerator DDS_LOANED_SAMPLE_STATE_RAW_KEY

enumerator DDS_LOANED_SAMPLE_STATE_RAW_DATA

enumerator DDS_LOANED_SAMPLE_STATE_SERIALIZED_KEY

enumerator DDS_LOANED_SAMPLE_STATE_SERIALIZED_DATA

Functions

inline DDS_INLINE_EXPORT void ddsrt_nonnull_all dds_loaned_sample_ref (dds_loaned_sample_t *loaned_sample)

Generic function to increase the refcount for a loaned sample.

Parameters

• loaned_sample – [in] A loaned sample

inline DDS_INLINE_EXPORT void ddsrt_nonnull_all dds_loaned_sample_unref (dds_loaned_sample_t *loaned_sample)

Generic function to decrease the refcount for a loaned sample.

Calls the PSMX plugin specific free function once the reference count reaches 0.

Parameters

• loaned_sample – [in] A loaned sample

struct dds_loaned_sample_ops

#include <dds_loaned_sample.h>

Container for implementation specific operations.

struct dds_loaned_sample

#include <dds_loaned_sample.h>

The definition of a block of memory originating from a PSMX.

Public Members

dds_loaned_sample_ops_t ops

the implementation specific ops for this sample

struct dds_loaned_sample_origin loan_origin

the origin of the loan

struct dds_psmx_metadata *metadata

pointer to the associated metadata

void *sample_ptr

pointer to the loaned sample

ddsrt_atomic_uint32_t refc

the number of references to this loan