lifemaps/qt6-migration-pipeline
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3c80b3c6fc103ed5a7d3c8d7a98feb5f2f44c402
qt6-migration-pipeline/external/rti_connext_dds-7.7.0/include/ndds/reda/reda_fastBuffer.h
T
torstenandCopilot 342ffd3e5c Update submodule to latest BUILD_RTI fixes 
- HandlerMinelayerData: BUILD_RTI Guards für RTI-Abhängigkeiten
- svcTabCommon: Export-Header-Fix via Fallback-Target
- TrainingAreaBase: Stub-Header für BUILD_RTI=OFF
- ddsfts: Include-Pfad und Dependency-Fixes
- BUILD_RTI=OFF Compilation vollständig unterstützt

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Entire-Checkpoint: 01M0JNZA586SACX1PRZ2DJAE5S
2026-08-21 19:30:20 +02:00

1196 lines
43 KiB
C
Raw Blame History

/*
* (c) Copyright, Real-Time Innovations, 2002-2026.
* All rights reserved.
* No duplications, whole or partial, manual or electronic, may be made
* without express written permission. Any such copies, or
* revisions thereof, must display this notice unaltered.
* This code contains trade secrets of Real-Time Innovations, Inc.
*/
#ifndef reda_fastBuffer_h
#define reda_fastBuffer_h
#include "reda/reda_dll.h"
#include "reda/reda_pluggableMemoryAllocator.h"
#include "reda/reda_buffer.h"
#include "osapi/osapi_alignment.h"
#ifdef __cplusplus
extern "C" {
#endif
struct REDAFastBufferPool;
struct REDAFastBufferPoolSet;
struct REDAThresholdBufferPool;
struct REDAUnboundedBufferPool;
/*e \file
\brief Fast memory access routines for FIXED-size buffers.
*/
/*e \defgroup REDAFastBufferPoolClass REDAFastBufferPool
\ingroup REDAModule
\brief FastBuffer provides a pool of FIXED-size memory buffers that can be
used for fast allocation/deallocation at run-time.
The normal memory-allocation routines (such as malloc and free) are
relatively slow routines and may be too time-consuming for real-time
tasks. By using FastBuffer, real-time tasks can access memory quickly.
To use it, first call REDAFastBufferPool_new (typically during
initialization). This will allocate a specified number of buffers,
each of a specified size. At run time, a task can grab a buffer
by calling REDAFastBufferPool_getBuffer and return it by calling
REDAFastBufferPool_returnBuffer.
If, when using getBuffer, the FastBufferPool runs out of buffers,
it will allocate a block of additional buffers. Each block will
have twice the size of the last block allocated.
FastBufferPool_returnBuffer will return the buffer to the FastBufferPool
but will not dynamically return memory to the heap.
\b Example:
\code
struct REDAFastBufferPool *pool;
typedef struct {
...
} *myType, myTypeStorage;
int initialize( void )
{
pool = REDAFastBufferPool_newForStructure(100, 10000, myTypeStorage);
...
}
void task( void )
{
myType var1, var2;
...
var1 = REDAFastBufferPool_getBuffer(pool);
var2 = REDAFastBufferPool_getBuffer(pool);
...
REDAFastBufferPool_returnBuffer(var1);
REDAFastBufferPool_returnBuffer(var2);
...
}
\endcode
*/
/*e \defgroup REDAFastBufferPoolSetClass REDAFastBufferPoolSet
\ingroup REDAModule
\brief FastBufferPoolSet provides access to multiple FastBuffer pools of
FIXED-size memory buffers that can be used for fast allocation/deallocation
at run-time.
*/
/* ===================================================================== */
/*e \ingroup REDAFastBufferPoolClass
\brief Moniker for unbounded pool capacity
@see REDAFastBufferPool_new REDAFastBufferPool_newForStructure
*/
#define REDA_FAST_BUFFER_POOL_UNLIMITED (-1)
/*e \ingroup REDAFastBufferPoolClass
\brief Moniker to indicate the initial,maximal and increment settings have
special values
*/
#define REDA_FAST_BUFFER_POOL_AUTO (-2)
/*e \ingroup REDAFastBufferPoolClass
\brief Moniker to request a buffer of default size with
REDAFastBufferPool_getBufferWithSize when used with dynamic buffer pool.
*/
#define REDA_FAST_BUFFER_POOL_BUFFER_SIZE_AUTO (-1)
/* ----------------------------------------------------------------- */
/*e \ingroup REDAFastBufferPoolClass
@brief Prototypes the function that can be registered to receive notification
when a buffer is physically allocated. This is the place
where the allocated buffer can be initialized.
This method is called either when the fast buffer pool is first created,
or when the fast buffer needs to grow.
@param buffer \b In. Pointer to a single buffer that is newly allocated by
the fast buffer pool.
@param param \b In. The \c bufferInitializeParam specified when the
fast buffer pool was created. See REDAFastBufferPool_new.
@see REDAFastBufferPool_new
*/
typedef RTIBool (
*REDAFastBufferPoolBufferInitializeFunction)(void *buffer, void *param);
/*e \ingroup REDAFastBufferPoolClass
@brief Prototypes the function that can be registered to receive notification
when a buffer is physically freed. This is the place
where resources related to the buffer can be cleaned up.
This method is called when the fast buffer pool is deleted.
@param buffer \b In. Pointer to a single buffer that is previously allocated
by the fast buffer pool.
@param param \b In. The \c bufferFinalizeParam specified when the
fast buffer pool was created. See REDAFastBufferPool_new.
@see REDAFastBufferPool_new
*/
typedef void (
*REDAFastBufferPoolBufferFinalizeFunction)(void *buffer, void *param);
/* ===================================================================== */
/*e \defgroup REDAFastBufferPoolGrowthPropertyClass
REDAFastBufferPoolGrowthProperty
\ingroup REDAFastBufferPoolClass
*/
struct REDAFastBufferPoolGrowthProperty {
/*e The number of buffers that will
be allocated immediately on creation of the FastBufferPool. */
int initial;
/*e Determines to what size the pool can grow.
When REDA_FAST_BUFFER_POOL_UNLIMITED, the pool-size
is only limited by available memory.
In case bufferCountLimit==bufferCountInitial, the pool will allocate its
memory on initialization and not grow dynamically. */
int maximal;
/*e Determines the maximal
number of buffers that will be allocated each time the FastBuffer runs
out of buffers. The FastBuffer is initialized with
initialBufferCount. Each time it runs out of buffers it allocates
numBuffersToAlloc = MIN(2*numBuffers, allocationChunkMaximalBufferCount).
The special value allocationChunkMaximalBufferCount ==
REDA_FAST_BUFFER_POOL_UNLIMITED, indicates that the allocation size
will keep doubling on each allocation until it reaches the
maximalBufferCount.
The value allocationChunkMaximalBufferCount == 0 is only permitted if
initialBufferCount == maximalBufferCount. It is not meaningful to
specify that the buffer pool may grow but then specify that it grow in
increments of zero buffers at a time.
*/
int increment;
};
/*
* Sentinel value indicating that the growth policy of the REDAFastBufferPool
* should be dynamic. We grow faster (doubling) while there are fewer
* buffers being managed in the pool. As the number of buffer being managed by
* the pool grows, we reduce the amount of additional buffers we add each time
* we grow the pool.
*/
#define REDA_FAST_BUFFER_POOL_INCREMENT_DYNAMIC (-2)
/* \ingroup REDAFastBufferPoolGrowthPropertyClass
\brief Used to initialize stack variable.
*/
#define REDA_FAST_BUFFER_POOL_GROWTH_PROPERTY_DEFAULT \
{ 2 /* initial */, \
REDA_FAST_BUFFER_POOL_UNLIMITED /* maximal: unlimited */, \
REDA_FAST_BUFFER_POOL_UNLIMITED /* increment: double */ }
extern REDADllExport int REDAFastBufferPoolGrowthProperty_compare(
struct REDAFastBufferPoolGrowthProperty *l,
struct REDAFastBufferPoolGrowthProperty *r);
/**
* Dynamic allocation is enabled when using the MALLOC plan (PURIFY_TEST)
* and disabled otherwise.
*
* This is the default value of dynamicAlloc.
*/
#define REDA_FAST_BUFFER_POOL_DYNAMIC_ALLOC_AUTO 0
/**
* Enables dynamic allocation.
*/
#define REDA_FAST_BUFFER_POOL_DYNAMIC_ALLOC_ENABLED 1
/**
* Disables dynamic allocation.
*
* Use with caution: when dynamic allocation is disabled, we lose the ability
* to detect unbounded memory growth in the pool when using the MALLOC
* allocation plan.
*/
#define REDA_FAST_BUFFER_POOL_DYNAMIC_ALLOC_DISABLED 2
/*e \defgroup REDAFastBufferPoolPropertyClass REDAFastBufferPoolProperty
\ingroup REDAFastBufferPoolClass
*/
/*e \ingroup REDAFastBufferPoolPropertyClass
@brief public members
*/
struct REDAFastBufferPoolProperty {
/*e control how the fast buffer pool grows */
struct REDAFastBufferPoolGrowthProperty growth;
/*e For Bug #8691 */
int multiThreadedAccess;
/*e For Bug #10224 */
int zeroBufferContent;
/*e For some usage of the fast buffer pool (like in table), we have a
problem of using the fast buffer pool's getBuffer() method to limit
the growth. Instead, we check against a known limit in the higher
layer. But the problem is that we use the maximal field of the
growth property to know what the allowed maximum (plus some heuristic
number). So until we have more confidence that we are exposing all the
property necessary to size the pool, we should just grow this kind
of table ad infinitum. */
int ignoreMaximal;
/*e Configures preallocation versus dynamic allocation */
int dynamicAlloc;
};
/*e \ingroup REDAFastBufferPoolPropertyClass
*/
#define REDA_FAST_BUFFER_POOL_PROPERTY_DEFAULT \
{ \
REDA_FAST_BUFFER_POOL_GROWTH_PROPERTY_DEFAULT, \
0, /* multiThreadedAccess: FALSE */ \
0, /* zeroBufferContent: FALSE*/ \
0, /* ignoreMaximal: FALSE */ \
REDA_FAST_BUFFER_POOL_DYNAMIC_ALLOC_AUTO /* dynamicAlloc: AUTO */ \
}
#define REDA_FAST_BUFFER_POOL_PROPERTY_DEFAULT_W_DYNAMIC_INCREMENT \
{ \
{ \
1 /* initial */, \
REDA_FAST_BUFFER_POOL_UNLIMITED /* maximal: unlimited */, \
REDA_FAST_BUFFER_POOL_INCREMENT_DYNAMIC /* increment: dynamic \
*/ \
}, \
0, /* multiThreadedAccess: FALSE */ \
0, /* zeroBufferContent: FALSE*/ \
0, /* ignoreMaximal: FALSE */ \
REDA_FAST_BUFFER_POOL_DYNAMIC_ALLOC_AUTO /* dynamicAlloc: AUTO */ \
}
/* ===================================================================== */
/*e \ingroup REDAFastBufferPoolClass
@brief Flags of the REDAFastBufferPool.
*/
/* Default REDAFastBufferPoolFlags */
#define REDA_FAST_BUFFER_POOL_FLAGS_NONE (0x00)
/*
* If this flag is enabled, the typeName is parsed and allocated in
* REDAFastBufferPool_newWithParams
* and it should free in REDAFastBufferPool_delete
*/
#define REDA_FAST_BUFFER_POOL_FLAG_USE_IMPLICIT_TYPE_NAME (0x01)
/*
* IMPORTANT: The 0x02 flag is for internal state only. Do not pass it into
* REDAFastBufferPool_newWithParams.
*
* This flag only takes effect if
* REDA_FAST_BUFFER_POOL_FLAG_ALLOW_DELAYED_DESTRUCTION is set.
*
* REDAFastBufferPool_delete will only actually destroy the pool if all buffers
* have been returned. If not all buffers have been returned, the pool will set
* this flag in the flags field.
* If this flag is set and all buffers have been returned,
* REDAFastBufferPool_returnBuffer will also destroy the pool.
* This mechanism enables destruction of the pool to be delayed until all
* of the buffers are returned. The delayed destruction is useful when the
* pool destruction and the buffer return are happening in different
* threads in an undeterministic order.
*/
#define REDA_FAST_BUFFER_POOL_FLAG_READY_FOR_DESTRUCTION (0x02)
/*
* If this flag is enabled,
* - REDAFastBufferPool_delete will only delete the pool if all buffers have
* been returned.
* - REDAFastBufferPool_returnBuffer will delete the pool if all buffers have
* been returned and REDAFastBufferPool_delete was previously called.
*/
#define REDA_FAST_BUFFER_POOL_FLAG_ALLOW_DELAYED_DESTRUCTION (0x04)
typedef RTI_UINT32 REDAFastBufferPoolFlags;
/*e \ingroup REDAFastBufferPoolClass
@brief Creates a fast buffer pool of buffers with specific size
and alignment.
@param bufferSize \b In. Each buffer returned with getBuffer will be of
this size. This must be >= 1.
@param bufferAlignment \b In. Each buffer returned with getBuffer will be
aligned. This must be a positive power of 2.
@return
On failure, it returns NULL if not enough memory.
On success, it returns the fast buffer pool.
@see REDAFastBufferPool_newForStructure REDAFastBufferPool_delete
*/
extern REDADllExport struct REDAFastBufferPool *REDAFastBufferPool_new(
int bufferSize,
RTIOsapiAlignment bufferAlignment,
const struct REDAFastBufferPoolProperty *propertyIn);
/*e \ingroup REDAFastBufferPoolClass
@brief Creates a fast buffer pool of buffers with specific size
and alignment.
Initializes the fast buffer pool and creates an initial set of buffers.
The memory for the new buffer pool is obtained from the heap via "OsapiHeap".
User will be notified when the buffer is created or destroyed.
@param bufferSize \b In. Each buffer returned with getBuffer will be of
this size. This must be >= 1.
@param bufferAlignment \b In. Each buffer returned with getBuffer will be
aligned. This must be a positive power of 2.
@param bufferInitializeFnc \b In. Used to notify application when a
buffer is about the be physically allocated.
See REDAFastBufferPoolBufferInitializeFunction for details.
May be NULL to indicate there is no notification is needed.
@param bufferInitializeParam \b In. Additional parameter to pass to
bufferInitializeFnc.
@param bufferFinalizeFnc \b In. Used to notify application when a
record is about the be physically freed.
See REDAFastBufferPoolBufferFinalizeFunction for details.
May be NULL to indicate there is no notification is needed.
@param bufferFinalizeParam \b In. Additional parameter to pass to
bufferFinalizeFnc.
@param typeName \b In. The name of the type to allocate.
@param flags \b In. The flags of the REDAFastBufferPool.
@return
On failure, it returns NULL if not enough memory.
On success, it returns the fast buffer pool.
@see REDAFastBufferPool_newForStructure REDAFastBufferPool_delete
*/
extern REDADllExport struct REDAFastBufferPool *
REDAFastBufferPool_newWithParams(
int bufferSize,
RTIOsapiAlignment bufferAlignment,
REDAFastBufferPoolBufferInitializeFunction bufferInitializeFnc,
void *bufferInitializeParam,
REDAFastBufferPoolBufferFinalizeFunction bufferFinalizeFnc,
void *bufferFinalizeParam,
const struct REDAFastBufferPoolProperty *propertyIn,
const char *typeName,
REDAFastBufferPoolFlags flags);
/*
* Creates a REDAPluggableMemoryAllocator that uses a REDAFastBufferPool as the
* underlying allocator.
*
* @param bufferSize In. The size of the buffers that should be provided by the
* allocator.
* @param bufferAlignment In. The alignment of the buffers that should be
* provided by the allocator.
* @param poolProperty In. The property used to configure the
* REDAFastBufferPool.
*
* @returns the REDAPluggableMemoryAllocator, or NULL upon failure.
*/
extern REDADllExport struct REDAPluggableMemoryAllocator *
REDAFastBufferPool_newPluggableMemoryAllocator(
RTI_INT32 bufferSize,
RTIOsapiAlignment bufferAlignment,
const struct REDAFastBufferPoolProperty *poolProperty);
/* ===================================================================== */
/*
* @brief Checks if the supplied REDAFastBufferPoolProperty is consistent and
* can be used to create a REDAFastBufferPool.
*
* In order for a REDAFastBufferPoolProperty to be considered consistent, the
* increment field cannot be 0 unless the minimal and maximal are equivalent.
*
* @param property In. The property to check for consistency.
*
* @returns True if the property is consistent.
*/
extern REDADllExport RTIBool REDAFastBufferPoolProperty_isConsistent(
const struct REDAFastBufferPoolProperty *property);
/* ===================================================================== */
/*e \ingroup REDFastBufferPoolClass
@brief Deletes a fast buffer pool.
All buffers obtained from the pool and the pool itself are returned
to the heap and should not be used any more.
*/
extern REDADllExport void REDAFastBufferPool_delete(
struct REDAFastBufferPool *me);
/* ===================================================================== */
/*e \ingroup REDAFastBufferPoolClass
@brief Gets the next available fast buffer.
This routine is extremely fast, and may be called from interrupt service
routines, etc.
@return On failure, it returns NULL
*/
extern REDADllExport void *REDAFastBufferPool_getBufferNoMalloc(
struct REDAFastBufferPool *me);
/* ===================================================================== */
/*e \ingroup REDAFastBufferPoolClass
@brief Gets the next available fast buffer and allocate new space
from the heap if necessary.
Memory is allocated from heap for each sample if the pool supports
dynamic allocation.
If the pool runs out of memory this call WILL GET MORE MEMORY using
RTIOsapiHeap. The call will fail when no more memory can be
allocated from the OsapiHeap or if the total number of buffers
allocated exceeds the bufferCountMaximal.
In case the pool was created with bufferCountInitial==bufferCountMaximal,
no additional memory will be allocated after pool initialization.
If you are using FastBuffer inside interrupt service routines, and
it is critical that malloc not be called use the getBufferNoMalloc
call instead.
This routine is extremely fast EXCEPT when it goes to allocate more pools.
@return On failure, it returns NULL
*/
extern REDADllExport void *REDAFastBufferPool_getBuffer(
struct REDAFastBufferPool *me);
/*e \ingroup REDAFastBufferPoolClass
@brief Gets a buffer of size bufferSize from heap if the pool supports
dynamic allocation. Otherwise it returns a pre allocated buffer.
It returns NULL if the bufferSize is greater than the buffer
size of the pool.
@return On failure, it returns NULL
*/
extern REDADllExport void *REDAFastBufferPool_getBufferWithSize(
struct REDAFastBufferPool *me,
int bufferSize);
/* ===================================================================== */
/*e \ingroup REDAFastBufferPoolClass
@brief Returns a fast buffer to the pool.
FastBufferReturn returns the buffer to the buffer pool. This routine is
also very fast, and may be called from interrupt code.
*/
extern REDADllExport void REDAFastBufferPool_returnBuffer(
struct REDAFastBufferPool *me,
void *buffer);
/* ===================================================================== */
/*e \ingroup REDAFastBufferPoolClass
@brief Returns the size of a single buffer.
This size include additional size added to each buffer for alignment purpose.
*/
extern REDADllExport int REDAFastBufferPool_getBufferSize(
struct REDAFastBufferPool *me);
extern REDADllExport int REDAFastBufferPool_getBufferCount(
struct REDAFastBufferPool *me);
/*e \ingroup REDAFastBufferPoolClass
@brief Get Read-only pointer to the pool's property
*/
extern REDADllExport const struct REDAFastBufferPoolProperty *
REDAFastBufferPool_getProperty(struct REDAFastBufferPool *me);
/* ===================================================================== */
/*e \ingroup REDAFastBufferPoolClass
\brief ONLY FOR DEBUGGING/INFO
This structure will be filled out with a snap-shot of the current state
of the FastBufferPool: can be used for debugging, testing and monitoring.
Usage:
\code
struct REDAFastBufferPoolInfo info;
REDAFastBufferPoolInfo_getInfo(pool, &info);
// now you can use the contents of info
if (info.totalMemoryUsage > 50000) { ... }
\endcode
@todo make optional; put in another library
*/
/*e \ingroup REDAFastBufferPoolClass
@brief public members
*/
struct REDAFastBufferPoolInfo {
/*e ID */
void *id;
/*e Buffer size */
int bufferSize;
/*e Buffer alignment */
int bufferAlignment;
/*e The number of buffers allocated */
int bufferAllocated;
/*e The number of buffers in use */
int bufferInUse;
/*e The maximum number of buffers that may be allocated */
int bufferCountLimit;
};
/*e \ingroup REDAFastBufferPoolClass
@brief Fill out a new info structure
@param pool \b In. The pool about which you want to query. Cannot be NULL
@param info \b Out. A place to put the information. Cannot be NULL
*/
extern REDADllExport void REDAFastBufferPool_getInfo(
struct REDAFastBufferPool *pool,
struct REDAFastBufferPoolInfo *info);
/*e \ingroup REDAFastBufferPoolClass
@brief FastBuffer buffer-usage statistics
This structure is used to return FastBuffer statistics. The FastBuffer
statistics are accumulated across all fast buffers in the same process. To
Get individual statistics on a particular fast buffer use the function
REDAFastBufferPool_getInfo
The statistics count the heap memory consumed by the fast buffers as well as
the memory within the fast buffers that is actually in use by the application.
Counters are also maintained for high and low watermarks as well as the number
of times that the FastBuffer went to the heap to ask or return memory as well
as how many times application asked/returned memory from the fast buffers.
These counters are incremental from the time the counters were last reset.
I.e. the last time the operation REDAFastBuffer_statGet was called.
Note that the statistics count the bytes requested (cumulative sum of the
sizes requested on the calls to RTIOsapiHeap_* functions). The bytes actually
consumed will be slightly greater due to the extra bytes to hold the header
information that supports the statistics (about 16 Bytes per block). The
reason for reporting the requested bytes is that this number will match the
actual allocated bytes when statistics-collection is turned off which is the
typical case for a deployed system.
\b Example:
The following gets the current statistics.
\verbatim
REDAFastBufferStat stat;
REDAFastBuffer_statGet(&stat);
\endverbatim
@see REDAFastBuffer_statGet REDAFastBuffer_statReset
*/
struct REDAFastBufferStat {
/*e current heap used in Bytes */
size_t heapMemCurrentUse;
/*e maximum heap usage in Bytes */
size_t heapMemHighWatermark;
/*e minimum heap usage in Bytes */
size_t heapMemLowWatermark;
/*e number of allocations from the heap (realloc is also counted as an
* alloc) */
int heapMemAllocCount;
/*e number of frees from the heap (realloc is also counted as a free) */
int heapMemFreeCount;
/*e current fast-buffer memory in Bytes */
size_t fbMemCurrentUse;
/*e maximum fast-buffer usage in Bytes */
size_t fbMemHighWatermark;
/*e minimum fast-buffer usage in Bytes */
size_t fbMemLowWatermark;
/*e number of times we asked to get a fast buffer */
int fbMemGetCount;
/*e number of times we returned a fast buffer */
int fbMemReturnCount;
};
/*e \ingroup REDAFastBufferPoolClass
@brief Get a copy of the global statistic counters
aggregating all the FastBuffers in the process.
@param stat \b Out. A place to put the information. Cannot be NULL
@see REDAFastBuffer_statReset RTIOsapiHeap_statGet RTIOsapiHeap_statReset
*/
extern REDADllExport void REDAFastBuffer_statGet(
struct REDAFastBufferStat *stat);
/*e \ingroup REDAFastBufferPoolClass
@brief Reset the global statistic counters
aggregating all the FastBuffers in the process.
@see REDAFastBuffer_statGet RTIOsapiHeap_statGet RTIOsapiHeap_statReset
*/
extern REDADllExport void REDAFastBuffer_statReset(void);
/* ===================================================================== */
/*
* We cannot use MAX_INT as the max bucket, since it isn't really a valid
* bucket (will overflow after alignment, doesn't allow for the optional header
* to be included with buffers).
* This value is the largest possible bucket (allowing for alignment and
* header)
*/
#define REDA_FAST_BUFFER_POOL_SET_MAX_BUCKET (2147483632)
#define REDA_FAST_BUFFER_POOL_SET_PROPERTY_DEFAULT \
{ \
REDA_FAST_BUFFER_POOL_PROPERTY_DEFAULT_W_DYNAMIC_INCREMENT, /* poolProperty \
*/ \
REDA_FAST_BUFFER_POOL_SET_MAX_BUCKET, /* maxBucket */ \
RTI_OSAPI_ALIGNMENT_DEFAULT /* bufferAlignment */ \
}
/* Used to configure the REDAFastBufferPoolSet. */
struct REDAFastBufferPoolSetProperty {
/* The REDAFastBufferPoolProperty to use when creating the
* REDAFastBufferPools */
struct REDAFastBufferPoolProperty poolProperty;
/* Maximum sized REDAFastBufferPool to be created by the
* REDAFastBufferPoolSet */
RTI_INT32 maxBucket;
/* All of the buffers managed by the pool set are aligned to this alignment
*/
RTIOsapiAlignment bufferAlignment;
};
/*
* Creates a REDAFastBufferPoolSet.
*
* @param poolCount In. The number of REDAFastBufferPools to create.
* Note that additional pools will be added to the poolSet as needed.
* @param bufferSizes In. The size of each REDAFastBufferPool to create.
* Can be NULL if poolCount is 0.
* @param property In. The REDAFastBufferPoolSetProperty used to configure the
* REDAFastBufferPoolSet.
*
* @returns The REDAFastBufferPoolSet, or NULL upon failure.
*/
extern REDADllExport struct REDAFastBufferPoolSet *REDAFastBufferPoolSet_new(
RTI_UINT32 poolCount,
const RTI_INT32 *bufferSizes,
const struct REDAFastBufferPoolSetProperty *property);
/*
* Creates a REDAPluggableMemoryAllocator that uses a REDAFastBufferPoolSet as
* the underlying allocator.
*
* @param poolCount In. The initial number of REDAFastBufferPools to create.
* Note that additional pools will be added to the poolSet as needed.
* @param bufferSizes In. The size of the buffers to be provided by each of the
* initial pools. Can be NULL if poolCount is 0.
* @param poolSetProperty In. The property used to configure the
* REDAFastBufferPoolSet.
*
* @returns the REDAPluggableMemoryAllocator, or NULL upon failure.
*/
extern REDADllExport struct REDAPluggableMemoryAllocator *
REDAFastBufferPoolSet_newPluggableMemoryAllocator(
RTI_UINT32 poolCount,
const RTI_INT32 *bufferSizes,
const struct REDAFastBufferPoolSetProperty *poolSetProperty);
/*
* Delete a REDAFastBufferPoolSet.
*
* All buffers obtained from the REDAFastBufferPools managed by this
* REDAFastBufferPoolSet are freed and therefore should no longer be used.
*
* @param me InOut. The REDAFastBufferPoolSet to delete.
*/
extern REDADllExport void REDAFastBufferPoolSet_delete(
struct REDAFastBufferPoolSet *me);
/*
* Obtain a REDAFastBuffer from the REDAFastBufferPoolSet.
*
* This function is responsible for providing a suitably sized buffer. Upon
* success it is guaranteed that the size of the provided buffer >= requested
* bufferSize.
*
* REDAFastBufferPoolSet_getBuffer tries to be intelligent about where it takes
* the buffers from. It will add new REDAFastBufferPools to the
* REDAFastBufferPoolSet as needed. The two cases in which additional
* REDAFastBufferPools may be added are:
* - The requested bufferSize cannot be provided by any of the
* REDAFastBufferPools currently being managed by the REDAFastBufferPoolSet.
* - The requested bufferSize is much smaller than the REDAFastBufferPool that
* would be used to provide the buffer. We want to avoid large chunks of
* memory being used by something that we know doesn't require it.
* See REDAFastBufferPoolSet_getSuitableBufferPoolNode for the implementation
* of how we check whether or not there are any REDAFastBufferPools currently
* being managed by the REDAFastBufferPoolSet which are suitable for the
* requested bufferSize.
*
* The REDAFastBufferPools that are added to the REDAFastBufferPoolSet are added
* in buckets.
* For example, if there are currently no REDAFastBufferPools in the
* REDAFastBufferPoolSet and the user does:
* REDAFastBufferPoolSet_getBuffer(poolSet, 800);
* REDAFastBufferPoolSet_getBuffer(poolSet, 850);
* We will only add a single pool. The implementation of the function used to
* calculate these buckets is REDAFastBufferPoolSet_getBufferSizeBucket.
*
* @param me InOut. The REDAFastBufferPoolSet.
* @param bufferSize In. The size of the buffer to obtain.
*
* @returns The buffer, or NULL upon failure.
*/
extern REDADllExport void *REDAFastBufferPoolSet_getBuffer(
struct REDAFastBufferPoolSet *me,
RTI_INT32 bufferSize);
/*
* Return a REDAFastBuffer to a REDAFastBufferPoolSet.
*
* @param me InOut. The REDAFastBufferPoolSet.
* @param buffer InOut. The buffer to return.
*/
extern REDADllExport void REDAFastBufferPoolSet_returnBuffer(
struct REDAFastBufferPoolSet *me,
void *buffer);
/*
* Obtain the bucket for a provided bufferSize.
*
* @param poolSetProperty In. The property of the poolSet to use in order to
* obtain the bucket.
* @param bufferSize In. The bufferSize for which we will obtain the bucket.
*
* @returns the calculated bucket size, or -1 upon error.
*/
extern REDADllExport RTI_INT32 REDAFastBufferPoolSet_getBufferSizeBucket(
const struct REDAFastBufferPoolSetProperty *poolSetProperty,
RTI_INT32 bufferSize);
#define REDAFastBufferPoolSetInfo_INITIALIZER \
{ \
0, /* poolCount */ \
NULL /* infos */ \
}
/*
* Statistics about the REDAFastBufferPools currently being managed by
* the REDAFastBufferPoolSet.
*/
struct REDAFastBufferPoolSetInfo {
/* The number of REDAFastBufferPoolInfos in the array */
RTI_UINT32 infoCount;
/* Array of REDAFastBufferPoolInfo, one per pool */
struct REDAFastBufferPoolInfo *infos;
};
/*
* Get information about the current state of the REDAFastBufferPools managed by
* this REDAFastBufferPoolSet.
*
* The snapshot of the current state of the pools is provided as an array in
* the info parameter. It must be returned/freed via a call to
* REDAFastBufferPoolSet_returnInfo.
*
* @param me In. The REDAFastBufferPoolSet.
* @param info Out. The REDAFastBufferPoolSetInfo to store the statistics in.
*
* @returns RTI_TRUE on success, otherwise RTI_FALSE.
*/
extern REDADllExport RTIBool REDAFastBufferPoolSet_getInfo(
const struct REDAFastBufferPoolSet *me,
struct REDAFastBufferPoolSetInfo *info);
/*
* Frees the memory of the statistical information about the REDAFastBufferPools
* managed by this REDAFastBufferPoolSet obtained via
* REDAFastBufferPoolSet_getInfo.
*
* @param info InOut. The REDAFastBufferPoolSetInfo to free.
*/
extern REDADllExport void REDAFastBufferPoolSet_returnInfo(
struct REDAFastBufferPoolSetInfo *info);
/*
* Get the number of REDAFastBufferPools being managed by this
* REDAFastBufferPoolSet.
*
* @param me In. The REDAFastBufferPoolSet.
*
* @returns the number of REDAFastBufferPools being managed by this
* REDAFastBufferPoolSet.
*/
extern REDADllExport RTI_UINT32
REDAFastBufferPoolSet_getPoolCount(const struct REDAFastBufferPoolSet *me);
/*
* Get the maxBucket configured for this REDAFastBufferPoolSet.
*
* @param me In. The REDAFastBufferPoolSet.
*
* @returns the maxBucket.
*/
extern REDADllExport RTI_INT32
REDAFastBufferPoolSet_getMaxBucket(const struct REDAFastBufferPoolSet *me);
/*
* Get the current maximum bucket size that has been allocated.
*
* This returns the size of the largest buffer pool that has been created
* by this pool set so far, not the maximum possible size (maxBucket).
*
* @param me In. The REDAFastBufferPoolSet.
*
* @returns the size of the largest currently allocated buffer pool,
* or -1 if the pool set is NULL or if getting info fails.
*/
extern REDADllExport RTI_INT32
REDAFastBufferPoolSet_getCurrentMaxBucket(const struct REDAFastBufferPoolSet *me);
/*
* Creates a new REDAFastBufferPool and adds it to the
* REDAFastBufferPoolSet.
*
* @param me InOut. The REDAFastBufferPoolSet to which we want to add
* the new pool.
* @param bufferSize In. The size of the buffers that the new
* REDAFastBufferPool should provide.
*
* @returns RTI_TRUE on success.
*/
extern REDADllExport RTIBool REDAFastBufferPoolSet_addPool(
struct REDAFastBufferPoolSet *me,
RTI_INT32 bufferSize);
/* ===================================================================== */
/*
* Configures how dynamic memory allocation is handled by the
* REDAThresholdBufferPool. Dynamic memory allocations occur when a buffer
* larger than the threshold is requested from the pool.
*/
enum REDAThresholdBufferPoolDynamicMemoryAllocation {
/* Dynamic memory allocations are not allowed. The Threshold buffer pool
* will behave as a regular buffer pool and the get buffer operation will
* fail if the requested size is larger than the threshold */
REDA_THRESHOLD_BUFFER_POOL_DYNAMIC_MEMORY_ALLOCATION_DISABLED,
/* Dynamic memory allocations are always allowed */
REDA_THRESHOLD_BUFFER_POOL_DYNAMIC_MEMORY_ALLOCATION_ENABLED,
/* Dynamic memory allocations are allowed, but the dynamic pool will only
* be created when the first buffer larger than the threshold is
* requested */
REDA_THRESHOLD_BUFFER_POOL_DYNAMIC_MEMORY_ALLOCATION_LAZY
};
typedef struct REDAThresholdBufferPoolProperty {
/*
* The fixed size pool will be created with a buffer with this size. Any
* buffers requested from the pool with a size greater than this threshold
* value will be dynamically allocated.
*
* threshold ==
* 0 : all buffers are dynamically allocated
* finite value : buffers may be preallocated or dynamically allocated
*/
int threshold;
/*
* Controls whether dynamic memory allocation is enabled, disabled, or
* lazy (allocate the pool when the first buffer is requested that exceeds
* the threshold).
*/
enum REDAThresholdBufferPoolDynamicMemoryAllocation
dynamicMemoryAllocationMode;
/* The alignment of the buffers allocated by this pool */
RTIOsapiAlignment bufferAlignment;
/* control how the underlying fast buffer pools behave */
struct REDAFastBufferPoolProperty fastBufferPoolProperty;
} REDAThresholdBufferPoolProperty;
/*
* Indicates whether the buffer returned by the pool came from the fixed size
* pool or the dynamic pool, or was already returned.
*/
typedef enum REDAThresholdBufferKind {
REDA_THRESHOLD_FIXED_SIZE_BUFFER = 0x5E555551,
REDA_THRESHOLD_DYNAMIC_BUFFER = 0x5E555552,
REDA_THRESHOLD_FREED_BUFFER = 0x7b9b9b9b
} REDAThresholdBufferKind;
typedef struct REDAThresholdBufferHeader {
REDAThresholdBufferKind signature;
} REDAThresholdBufferHeader;
/*e \ingroup REDThresholdBufferPoolClass
*
* @brief Gets the header size add by the threshold buffer pool.
*
* @param alignment Input aligned used on the calculation. The header is always
* aligned.
*/
extern REDADllExport unsigned int REDAThresholdBufferPool_getHeaderSize(
unsigned int alignment);
/*e \ingroup REDThresholdBufferPoolClass
*
* @brief Get the buffer signature that represent the way in which this buffer
* has been allocated.
*
* @param buffer \b In. that has been allocated by the Threshold buffer pool.
*/
extern REDADllExport REDAThresholdBufferKind
REDAThresholdBufferPool_getBufferSignature(void *buffer);
/*e \ingroup REDThresholdBufferPoolClass
*
* @brief Set the buffer signature that represent the way in which this buffer
* has been allocated.
*
* @param buffer \b In. allocated by the Threshold buffer pool.
* @param signature \b In. Kind of the allocation (Dynamic or static) done by
* the threshold buffer pool.
*/
extern REDADllExport void REDAThresholdBufferPool_setBufferSignature(
void *buffer,
REDAThresholdBufferKind signature);
/* clang-format off */
#define REDA_THRESHOLD_BUFFER_POOL_PROPERTY_DEFAULT { \
0, /* threshold */ \
REDA_THRESHOLD_BUFFER_POOL_DYNAMIC_MEMORY_ALLOCATION_ENABLED, \
RTI_OSAPI_ALIGNMENT_DEFAULT, /* bufferAlignment */ \
REDA_FAST_BUFFER_POOL_PROPERTY_DEFAULT \
}
/* clang-format on */
/* REDAThresholdBufferPoolClass
*
* @brief Creates a threshold buffer pool.
*
* @param property The threshold buffer pool property. Includes information
* such as the threshold value and max number of buffers and the
* properties for the underlying fast buffer pools
*
* @return
* On failure, it returns NULL if not enough memory.
* On success, it returns the threshold buffer pool.
*/
extern REDADllExport struct REDAThresholdBufferPool *
REDAThresholdBufferPool_new(
const struct REDAThresholdBufferPoolProperty *property);
/*e \ingroup REDThresholdBufferPoolClass
*
* @brief Deletes a threshold buffer pool.
*
* Any buffers that were obtained from the Fixed Size pool will be returned.
* Any dynamically allocated buffers will be leaked, the threshold buffer pool
* does not keep track of these ones.
*/
extern REDADllExport void REDAThresholdBufferPool_delete(
struct REDAThresholdBufferPool *me);
/* REDAThresholdBufferPoolClass
*
* @pre bufferSize >= 1
*
* @brief Gets a buffer with at least size bufferSize. If bufferSize is greater
* than the threshold value that the pool was created with the buffer
* will have size bufferSize and be dynamically allocated, otherwise
* it will be obtained from a preallocated pool of buffers created with
* the threshold size.
*
* @return On failure, it returns NULL
*/
extern REDADllExport void *REDAThresholdBufferPool_getBuffer(
struct REDAThresholdBufferPool *me,
int bufferSize);
/* REDAThresholdBufferPoolClass
*
* @brief Returns a buffer to the corresponding pool (dynamic pool or fixed size
* pool). Uses a header added to the buffers to determine which pool to
* return to
*/
extern REDADllExport void REDAThresholdBufferPool_returnBuffer(
struct REDAThresholdBufferPool *me,
void *buffer);
/* \ingroup REDAThresholdBufferPoolClass
*
* Creates a REDAPluggableMemoryAllocator that uses a REDAThresholdBufferPool as
* the underlying allocator.
*
* @param property The threshold buffer pool property. Includes information
* such as the threshold value and max number of buffers and the
* properties for the underlying fast buffer pools
* @return the REDAPluggableMemoryAllocator, or NULL upon failure.
*/
extern REDADllExport struct REDAPluggableMemoryAllocator *
REDAThresholdBufferPool_newPluggableMemoryAllocator(
const struct REDAThresholdBufferPoolProperty *property);
/* ===================================================================== */
/*e \ingroup REDAUnboundedBufferPoolClass
*
* @brief Creates an unbounded buffer pool. See the definition of struct
* REDAUnboundedBufferPool in unboundedBufferPool.c for an explanation of what
* an unbounded buffer pool is.
*
* @param numberOfBuffers \b In. The maximum number of the buffers that can be
* created by this pool
* @param initialRequestedBufferSize \b In. If greater than zero, all
* numberOfBuffers are allocated to this size.
*
* @return
* On failure, it returns NULL if not enough memory.
* On success, it returns the unbounded buffer pool.
*/
extern REDADllExport struct REDAUnboundedBufferPool *
REDAUnboundedBufferPool_new(
RTI_INT32 numberOfBuffers,
RTI_INT32 initialRequestedBufferSize);
/*e \ingroup REDAUnboundedBufferPoolClass
*
* @brief Deletes an unbounded buffer pool.
*
* @param self \b InOut. The REDAUnboundedBufferPool to delete.
*
* Any allocated buffers are freed. There is no need for the caller to return
* buffers before calling this function.
*/
extern REDADllExport void REDAUnboundedBufferPool_delete(
struct REDAUnboundedBufferPool *self);
/*e \ingroup REDAUnboundedBufferPoolClass
*
* @pre bufferSize >= 1
*
* @brief Gets a buffer of at least the requested buffer size. If there are no
* free buffers, it returns NULL and an exception is logged. If there are no
* free buffers that are large enough for the requested buffer size, one of the
* free buffers will be grown to the requested buffer size. Note that the
* returned buffer is not zeroed out and may contain contents from a previous
* usage.
*
* @param self \b InOut. The REDAUnboundedBufferPool from which we get the
* buffer.
* @param requestedBufferSize \b In. The size of the buffer to get.
*
* @return On failure, it returns NULL, otherwise it returns the buffer
*/
extern REDADllExport void *REDAUnboundedBufferPool_getBuffer(
struct REDAUnboundedBufferPool *self,
RTI_INT32 requestedBufferSize);
/*e \ingroup REDAUnboundedBufferPoolClass
*
* @brief Returns a buffer to the pool. This does not cause a deallocation,
* so it is very fast. It is not necessary to return buffers before calling
* REDAUnboundedBufferPool_delete, however the buffer must not be used after
* it is returned.
*
* @param self \b InOut. The REDAUnboundedBufferPool from which we got the
* buffer.
* @param buffer \b InOut. The buffer to return.
*/
extern REDADllExport void REDAUnboundedBufferPool_returnBuffer(
struct REDAUnboundedBufferPool *self,
void *buffer);
/* forward declare for REDAUnboundedBufferPool_getStats */
struct REDAUnboundedBufferPoolStats;
/*e \ingroup REDAUnboundedBufferPoolClass
*
* @brief Populates the stats struct with a snapshot of the current statistics
* for the unbounded buffer pool.
*
* @param self \b In. The REDAUnboundedBufferPool from which we get the stats.
* @param buffer \b Out. The stats structure to populate.
*/
extern REDADllExport void REDAUnboundedBufferPool_getStats(
const struct REDAUnboundedBufferPool *self,
struct REDAUnboundedBufferPoolStats *stats);
/*e \ingroup REDAUnboundedBufferPoolClass
*
* @brief Initializes an unbounded buffer pool with a specified number of
* buffers and initial buffer size.
*
* @param self \b InOut. The REDAUnboundedBufferPool to initialize.
* @param numberOfBuffers \b In. The maximum number of the buffers that can be
* created by this pool
* @param initialRequestedBufferSize \b In. If greater than zero, all
* numberOfBuffers are allocated to this size.
*
* @return RTI_TRUE on success, RTI_FALSE on failure.
*/
extern REDADllExport RTIBool REDAUnboundedBufferPool_initialize(
struct REDAUnboundedBufferPool *self,
RTI_INT32 numberOfBuffers,
RTI_INT32 initialRequestedBufferSize);
/*e \ingroup REDAUnboundedBufferPoolClass
*
* @brief Finalizes the unbounded buffer pool by freeing all allocated buffers
* and the buffer array itself. Does not free the pool struct itself.
*
* @param self \b InOut. The REDAUnboundedBufferPool to finalize.
*/
extern REDADllExport void REDAUnboundedBufferPool_finalize(
struct REDAUnboundedBufferPool *self);
/*
* Creates a REDAPluggableMemoryAllocator that uses a REDAUnboundedBufferPool as
* the underlying allocator.
*
* @param numberOfBuffers \b In. The maximum number of the buffers that can be
* created by this pool
* @param initialRequestedBufferSize \b In. If greater than zero, all
* numberOfBuffers are allocated to this size.
*
* @returns the REDAPluggableMemoryAllocator, or NULL upon failure.
*/
extern REDADllExport struct REDAPluggableMemoryAllocator *
REDAUnboundedBufferPool_newPluggableMemoryAllocator(
RTI_INT32 numberOfBuffers,
RTI_INT32 initialRequestedBufferSize);
#ifdef __cplusplus
} /* extern "C" */
#endif
#include "reda/reda_fastBuffer_impl.h"
#endif /* reda_fastBuffer_h */
Reference in new issue View Git Blame Copy Permalink