150 lines
5.0 KiB
C
150 lines
5.0 KiB
C
/*
|
|
* Copyright(c) 2021 ZettaScale Technology and others
|
|
*
|
|
* 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
|
|
*/
|
|
|
|
#ifndef DDS_DATA_ALLOCATOR_H
|
|
#define DDS_DATA_ALLOCATOR_H
|
|
|
|
/**
|
|
* @defgroup data_allocator (Data Allocator)
|
|
* @ingroup dds
|
|
* A quick-and-dirty provisional interface
|
|
*/
|
|
|
|
#include "dds/dds.h"
|
|
#include "dds/ddsrt/attributes.h"
|
|
#include "dds/export.h"
|
|
|
|
#if defined (__cplusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
// macOS' mutexes require quite a lot of space, but it is not quite enough
|
|
// to make this system-dependent
|
|
#define DDS_DATA_ALLOCATOR_MAX_SIZE (12 * sizeof (void *))
|
|
|
|
/**
|
|
* @ingroup data_allocator
|
|
* @brief Data Allocator structure
|
|
* Contains internal details about the data allocator for a given entity
|
|
*/
|
|
typedef struct dds_data_allocator {
|
|
dds_entity_t entity; /**< to which entity this allocator is attached */
|
|
union {
|
|
unsigned char bytes[DDS_DATA_ALLOCATOR_MAX_SIZE]; /**< internal details */
|
|
void *align_ptr; /**< internal details */
|
|
uint64_t align_u64; /**< internal details */
|
|
} opaque; /**< internal details */
|
|
} dds_data_allocator_t;
|
|
|
|
/**
|
|
* @ingroup data_allocator
|
|
* @brief Initialize an object for performing allocations/frees in the context of a reader/writer
|
|
*
|
|
* The operation will fall back to standard heap allocation if nothing better is available.
|
|
*
|
|
* @param[in] entity the handle of the entity
|
|
* @param[out] data_allocator opaque allocator object to initialize
|
|
*
|
|
* @returns success or a generic error indication
|
|
*
|
|
* @retval DDS_RETCODE_OK
|
|
* the allocator object was successfully initialized
|
|
* @retval DDS_RETCODE_BAD_PARAMETER
|
|
* entity is invalid, data_allocator is a null pointer
|
|
* @retval DDS_RETCODE_PRECONDITION_NOT_MET
|
|
* Cyclone DDS is not initialized
|
|
* @retval DDS_RETCODE_ILLEGAL_OPERATION
|
|
* operation not supported on this entity
|
|
*/
|
|
DDS_EXPORT dds_return_t dds_data_allocator_init (dds_entity_t entity, dds_data_allocator_t *data_allocator);
|
|
|
|
/**
|
|
* @ingroup data_allocator
|
|
* @brief Initialize an object for performing standard allocations/frees on the heap
|
|
*
|
|
* @param[out] data_allocator opaque allocator object to initialize
|
|
*
|
|
* @returns success or a generic error indication
|
|
*
|
|
* @retval DDS_RETCODE_OK
|
|
* the allocator object was successfully initialized
|
|
* @retval DDS_RETCODE_BAD_PARAMETER
|
|
* entity is invalid, data_allocator is a null pointer
|
|
* @retval DDS_RETCODE_PRECONDITION_NOT_MET
|
|
* Cyclone DDS is not initialized
|
|
* @retval DDS_RETCODE_ILLEGAL_OPERATION
|
|
* operation not supported on this entity
|
|
*/
|
|
DDS_EXPORT dds_return_t dds_data_allocator_init_heap (dds_data_allocator_t *data_allocator);
|
|
|
|
/**
|
|
* @ingroup data_allocator
|
|
* @brief Finalize a previously initialized allocator object
|
|
*
|
|
* @param[in,out] data_allocator object to finalize
|
|
*
|
|
* @returns success or an error indication
|
|
*
|
|
* @retval DDS_RETCODE_OK
|
|
* the data was successfully finalized
|
|
* @retval DDS_RETCODE_BAD_PARAMETER
|
|
* data_allocator does not reference a valid entity
|
|
* @retval DDS_RETCODE_PRECONDITION_NOT_MET
|
|
* Cyclone DDS is not initialized
|
|
*/
|
|
DDS_EXPORT dds_return_t dds_data_allocator_fini (dds_data_allocator_t *data_allocator);
|
|
|
|
/**
|
|
* @ingroup data_allocator
|
|
* @brief Allocate memory using the given allocator
|
|
*
|
|
* @param[in,out] data_allocator initialized allocator object
|
|
* @param[in] size minimum number of bytes to allocate with suitable alignment
|
|
*
|
|
* @returns a pointer to unaliased, uninitialized memory of at least the requested size, or NULL
|
|
*/
|
|
DDS_EXPORT void *dds_data_allocator_alloc (dds_data_allocator_t *data_allocator, size_t size)
|
|
ddsrt_attribute_warn_unused_result ddsrt_attribute_malloc;
|
|
|
|
/**
|
|
* @ingroup data_allocator
|
|
* @brief Release memory using the given allocator
|
|
*
|
|
* @param[in,out] data_allocator initialized allocator object
|
|
* @param[in] ptr memory to free
|
|
*
|
|
* @returns success or an error indication
|
|
*
|
|
* @retval DDS_RETCODE_OK
|
|
* the memory was successfully released
|
|
* @retval DDS_RETCODE_BAD_PARAMETER
|
|
* data_allocator does not reference a valid entity
|
|
* @retval DDS_RETCODE_PRECONDITION_NOT_MET
|
|
* dds_data_allocator already finalized
|
|
*/
|
|
DDS_EXPORT dds_return_t dds_data_allocator_free (dds_data_allocator_t *data_allocator, void *ptr);
|
|
|
|
#ifndef DOXYGEN_SHOULD_SKIP_THIS
|
|
/// @note This function declaration is deprecated here and has been moved to
|
|
/// dds_loan_api.h.
|
|
DDS_EXPORT bool dds_is_loan_available(const dds_entity_t entity);
|
|
|
|
/// @note This function declaration is deprecated here and has been moved to
|
|
/// dds_loan_api.h.
|
|
DDS_EXPORT bool is_loan_available(const dds_entity_t entity);
|
|
#endif
|
|
|
|
#if defined (__cplusplus)
|
|
}
|
|
#endif
|
|
#endif
|