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 Loaned Sample.

typedef uint32_t dds_loan_data_type_t

Identifier used to distinguish between raw data types (C/C++/Python/…) in a Loaned Sample.

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 Loaned Sample.

Enums

enum dds_loaned_sample_state

State of the data contained in a Loaned Sample.

Values:

enumerator DDS_LOANED_SAMPLE_STATE_UNITIALIZED

state not set yet; not passed through PSMX interface

enumerator DDS_LOANED_SAMPLE_STATE_RAW_KEY

application representation, only key fields initialized

enumerator DDS_LOANED_SAMPLE_STATE_RAW_DATA

application representation, full sample initialized

enumerator DDS_LOANED_SAMPLE_STATE_SERIALIZED_KEY

CDR/XCDR1/XCDR2-serialized key value serialized.

enumerator DDS_LOANED_SAMPLE_STATE_SERIALIZED_DATA

CDR/XCDR1/XCDR2-serialized sample value serialized.

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.

Loaned Samples are freed in the order in which their reference counts drop to 0.

On the writing side, writing (or “returning”) Loaned Samples in the order in which they were requested will ensure that the “free” operations is also invoked in the that order.

On the reading side, the serdata constructed by dds_reader_store_loaned_sample may or may not reference the Loaned Sample, and if not the Loaned Sample will be dropped once the PSMX Plugin invokes dds_loaned_sample_unref on it.

Otherwise, the Loaned Sample will be referenced by a sample in the reader history cache and stay there until it gets dropped (and the PSMX Plugin also invokes dds_loaned_sample_unref on it). If the reading application does not use loans in the reads/takes, that will be once it is pushed out of the history or taken. If the application uses takecdr or take_with_collector, then it is dependent on when the application logic drops the serdata via ddsi_serdata_unref.

If the application does use loans in reads/takes, and Cyclone DDS decides to hand the data in the Loaned Sample to the application, the earliest time at which it can be dropped is when it is removed from the reader history cache and the loan is returned by the application using dds_return_loan.

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 Loaned Sample.

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