157 lines
4.1 KiB
C
157 lines
4.1 KiB
C
/*
|
|
* Copyright(c) 2006 to 2019 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
|
|
*/
|
|
/* TODO: do we really need to expose this as an API? */
|
|
|
|
/** @file
|
|
*
|
|
* @brief DDS C Allocation API
|
|
*
|
|
* This header file defines the public API of allocation convenience functions
|
|
* in the Eclipse Cyclone DDS C language binding.
|
|
*/
|
|
#ifndef DDS_ALLOC_H
|
|
#define DDS_ALLOC_H
|
|
|
|
#include <stddef.h>
|
|
|
|
#include "dds/export.h"
|
|
|
|
#if defined (__cplusplus)
|
|
extern "C" {
|
|
#endif
|
|
|
|
struct dds_topic_descriptor;
|
|
struct dds_sequence;
|
|
|
|
/**
|
|
* @anchor DDS_FREE_KEY_BIT
|
|
* @ingroup alloc
|
|
* @brief Instruction to free all keyfields in sample
|
|
*/
|
|
#define DDS_FREE_KEY_BIT 0x01
|
|
|
|
/**
|
|
* @anchor DDS_FREE_CONTENTS_BIT
|
|
* @ingroup alloc
|
|
* @brief Instruction to free all non-keyfields in sample
|
|
*/
|
|
#define DDS_FREE_CONTENTS_BIT 0x02
|
|
|
|
/**
|
|
* @anchor DDS_FREE_ALL_BIT
|
|
* @ingroup alloc
|
|
* @brief Instruction to free outer sample
|
|
*/
|
|
#define DDS_FREE_ALL_BIT 0x04
|
|
|
|
/**
|
|
* @brief Freeing operation type
|
|
* @ingroup alloc
|
|
* What part of a sample to free
|
|
*/
|
|
typedef enum
|
|
{
|
|
DDS_FREE_ALL = DDS_FREE_KEY_BIT | DDS_FREE_CONTENTS_BIT | DDS_FREE_ALL_BIT, /**< free full sample */
|
|
DDS_FREE_CONTENTS = DDS_FREE_KEY_BIT | DDS_FREE_CONTENTS_BIT, /**< free all sample contents, but leave sample pointer intact */
|
|
DDS_FREE_KEY = DDS_FREE_KEY_BIT /**< free only the keyfields in a sample */
|
|
}
|
|
dds_free_op_t;
|
|
|
|
/**
|
|
* @brief DDS Allocator
|
|
* @ingroup alloc
|
|
* C-Style allocator API
|
|
*/
|
|
typedef struct dds_allocator
|
|
{
|
|
void * (*malloc) (size_t size); /**< behave like C malloc */
|
|
void * (*realloc) (void *ptr, size_t size); /**< behave like C realloc, may be null */
|
|
void (*free) (void *ptr); /**< behave like C free */
|
|
}
|
|
dds_allocator_t;
|
|
|
|
/**
|
|
* @brief Perform an alloc() with the default allocator.
|
|
*
|
|
* @param[in] size number of bytes
|
|
* @returns new pointer or NULL if out of memory
|
|
*/
|
|
DDS_EXPORT void * dds_alloc (size_t size);
|
|
|
|
/**
|
|
* @brief Perform a realloc() with the default allocator.
|
|
*
|
|
* @param[in] ptr previously alloc()'ed pointer
|
|
* @param[in] size new size
|
|
* @return new pointer or NULL if out of memory
|
|
*/
|
|
DDS_EXPORT void * dds_realloc (void * ptr, size_t size);
|
|
|
|
/**
|
|
* @brief Perform a realloc() with the default allocator. Zero out memory.
|
|
*
|
|
* @param[in] ptr previously alloc()'ed pointer
|
|
* @param[in] size new size
|
|
* @return new pointer or NULL if out of memory
|
|
*/
|
|
DDS_EXPORT void * dds_realloc_zero (void * ptr, size_t size);
|
|
|
|
/**
|
|
* @brief Perform a free() on a memory fragment allocated with the default allocator.
|
|
*
|
|
* @param[in] ptr previously alloc()'ed pointer
|
|
*/
|
|
DDS_EXPORT void dds_free (void * ptr);
|
|
|
|
#ifndef DOXYGEN_SHOULD_SKIP_THIS
|
|
typedef void * (*dds_alloc_fn_t) (size_t);
|
|
typedef void * (*dds_realloc_fn_t) (void *, size_t);
|
|
typedef void (*dds_free_fn_t) (void *);
|
|
#endif // DOXYGEN_SHOULD_SKIP_THIS
|
|
|
|
/**
|
|
* @brief Allocated a string with size, accounting for the null terminator.
|
|
*
|
|
* @param[in] size number of characters
|
|
* @returns newly allocated string or NULL if out of memory
|
|
*/
|
|
DDS_EXPORT char * dds_string_alloc (size_t size);
|
|
|
|
/**
|
|
* @brief Duplicate a null-terminated string
|
|
*
|
|
* @param[in] str string to duplicate
|
|
* @returns newly allocated duplicate string, or NULL if out of memory
|
|
*/
|
|
DDS_EXPORT char * dds_string_dup (const char * str);
|
|
|
|
/**
|
|
* @brief Free a string, equivalent to dds_free
|
|
*
|
|
* @param[in] str string to free
|
|
*/
|
|
DDS_EXPORT void dds_string_free (char * str);
|
|
|
|
/**
|
|
* @brief Free (parts of) a sample according to the \ref dds_free_op_t
|
|
*
|
|
* @param[in] sample sample to free
|
|
* @param[in] desc topic descriptor of the type this sample was created from.
|
|
* @param[in] op Which parts of the sample to free.
|
|
*/
|
|
DDS_EXPORT void dds_sample_free (void * sample, const struct dds_topic_descriptor * desc, dds_free_op_t op);
|
|
|
|
#if defined (__cplusplus)
|
|
}
|
|
#endif
|
|
#endif
|