173 lines
6.4 KiB
C
173 lines
6.4 KiB
C
// Copyright(c) 2021 ZettaScale Technology
|
|
// Copyright(c) 2021 Apex.AI, Inc
|
|
//
|
|
// This program and the accompanying materials are made available under the
|
|
// terms of the Eclipse Public License v. 2.0 which is available at
|
|
// http://www.eclipse.org/legal/epl-2.0, or the Eclipse Distribution License
|
|
// v. 1.0 which is available at
|
|
// http://www.eclipse.org/org/documents/edl-v10.php.
|
|
//
|
|
// SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
|
|
|
|
// API extension
|
|
// defines functions needed for loaning and shared memory usage
|
|
|
|
#ifndef DDS_PUBLIC_LOAN_API_H
|
|
#define DDS_PUBLIC_LOAN_API_H
|
|
|
|
#include "dds/ddsc/dds_basic_types.h"
|
|
#include "dds/ddsrt/retcode.h"
|
|
#include "dds/export.h"
|
|
|
|
#if defined(__cplusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
/**
|
|
* @defgroup loan (Loans API)
|
|
* @ingroup dds
|
|
*/
|
|
|
|
/**
|
|
* @brief Request a loan from an entity.
|
|
* @ingroup loan
|
|
*
|
|
* Borrow a sample from the entity, which currently must be a writer. This sample
|
|
* can then be returned using @ref dds_return_loan or can be used to publish data
|
|
* using @ref dds_write or @ref 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.
|
|
*
|
|
* @param[in] entity The entity to request loans from.
|
|
* @param[out] sample Where to store the address of the loaned sample.
|
|
*
|
|
* @returns A dds_return_t indicating success or failure.
|
|
*
|
|
* @retval DDS_RETCODE_OK
|
|
* The operation was successful.
|
|
* @retval DDS_RETCODE_BAD_PARAMETER
|
|
* One or more parameters are invalid.
|
|
* @retval DDS_RETCODE_ILLEGAL_OPERATION
|
|
* The operation is invoked on an inappropriate object.
|
|
* @retval DDS_RETCODE_ALREADY_DELETED
|
|
* The entity has already been deleted.
|
|
* @retval DDS_RETCODE_ERROR
|
|
* An unfortunate incident occurred.
|
|
*/
|
|
DDS_EXPORT dds_return_t dds_request_loan (dds_entity_t entity, void **sample);
|
|
|
|
/**
|
|
* @brief Return loaned samples to a reader or writer
|
|
* @ingroup loan
|
|
* @component read_data
|
|
*
|
|
* Used to release middleware-owned samples returned by a read/take operation and samples
|
|
* borrowed from the writer using @ref dds_request_loan.
|
|
*
|
|
* For reader loans, the @ref dds_read and @ref 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 @ref 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.
|
|
*
|
|
* @param[in] entity 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.
|
|
* @param[in,out] buf An array of (pointers to) samples, some or all of which will be set to null pointers.
|
|
* @param[in] bufsz The size of the buffer.
|
|
*
|
|
* @returns A dds_return_t indicating success or failure
|
|
* @retval 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
|
|
* @retval 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)
|
|
* @retval DDS_RETCODE_PRECONDITION_NOT_MET
|
|
* - bufsz > 0 and buf[0] != null but not a loan, nothing done
|
|
* @retval DDS_RETCODE_UNSUPPORTED
|
|
* - (for writer loans) invoked on a writer not supporting loans.
|
|
* @retval DDS_RETCODE_ILLEGAL_OPERATION
|
|
* - the operation is invoked on an inappropriate object.
|
|
*/
|
|
DDS_EXPORT dds_return_t dds_return_loan (dds_entity_t entity, void **buf, int32_t bufsz);
|
|
|
|
/**
|
|
* @ingroup loan
|
|
* @component read_data
|
|
* @brief 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.
|
|
*
|
|
* @param[in] entity the handle of the entity
|
|
*
|
|
* @returns true if shared memory is available, false otherwise
|
|
*/
|
|
DDS_EXPORT bool dds_is_shared_memory_available (const dds_entity_t entity);
|
|
|
|
/**
|
|
* @brief Request a loan of a specified size from an entity.
|
|
* @ingroup loan
|
|
*
|
|
* Borrow a sample of a specified size from the entity, which currently must be a
|
|
* writer. This sample can then be returned using @ref dds_return_loan or can be
|
|
* used to publish data using @ref dds_write or @ref dds_writedispose.
|
|
*
|
|
* @note The function can only be used if dds_is_shared_memory_available is
|
|
* true for the writer.
|
|
*
|
|
* @param[in] writer The entity to request loans from.
|
|
* @param[in] size the requested loan size
|
|
* @param[out] sample Where to store the address of the loaned sample.
|
|
*
|
|
* @returns DDS_RETCODE_OK if successful, DDS_RETCODE_ERROR otherwise
|
|
*/
|
|
DDS_EXPORT dds_return_t dds_request_loan_of_size (dds_entity_t writer, size_t size, void **sample);
|
|
|
|
/**
|
|
* @ingroup deprecated
|
|
* @component read_data
|
|
* @brief Check if a Loan is available to reader/writer
|
|
* @deprecated Use @ref dds_request_loan instead, returns 0 if loan is not available
|
|
*
|
|
* 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.
|
|
*
|
|
* @param[in] entity the handle of the entity
|
|
*
|
|
* @returns loan available or not
|
|
*/
|
|
DDS_DEPRECATED_EXPORT bool dds_is_loan_available (const dds_entity_t entity);
|
|
|
|
/**
|
|
* @ingroup deprecated
|
|
* @component read_data
|
|
* @brief Loan a sample from the writer.
|
|
* @deprecated Use @ref dds_request_loan
|
|
* @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.
|
|
*
|
|
* @param[in] writer the writer to loan the buffer from
|
|
* @param[out] sample the loaned sample
|
|
*
|
|
* @returns DDS_RETCODE_OK if successful, DDS_RETCODE_ERROR otherwise
|
|
*/
|
|
DDS_DEPRECATED_EXPORT dds_return_t dds_loan_sample (dds_entity_t writer, void **sample);
|
|
|
|
#if defined(__cplusplus)
|
|
}
|
|
#endif
|
|
|
|
#endif /* DDS_PUBLIC_LOAN_API_H */
|