RTI Connext DDS Micro  Version 2.4.6
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
reda_bufferpool.h
1 /*
2  * FILE: reda_bufferpool.c - BufferPool interface
3  *
4  * Copyright 2008-2015 Real-Time Innovations, Inc.
5  *
6  * No duplications, whole or partial, manual or electronic, may be made
7  * without express written permission. Any such copies, or
8  * revisions thereof, must display this notice unaltered.
9  * This code contains trade secrets of Real-Time Innovations, Inc.
10  *
11  * Modification History
12  * --------------------
13  * 04nov2015,tk MICRO-1505 Reduce memory footprint
14  * 11mar2013,tk MICRO-171/PR#1051
15  * 25may2012,tk Written
16  *
17  */
18 /*ci
19  * \file
20  *
21  * \brief The REDA BufferPool interface provides a platform independent API to
22  * manage a pool of fixed size elements.
23  *
24  * \defgroup REDA_BufferPoolClass REDA BufferPool
25  * \ingroup REDAModule
26  *
27  * \details
28  *
29  * The REDA BufferPool interface defines an API manage a fixed number of
30  * fixed sized elements. It is important to note that the number of elements
31  * in the pool cannot grow beyond what was specified when the pool was created.
32  * Callbacks can be installed to be notified when the buffer pool allocates
33  * a new buffer or free a buffer.
34  */
35 
36 /*ci \addtogroup REDA_BufferPoolClass
37  * @{
38  */
39 #ifndef reda_bufferpool_h
40 #define reda_bufferpool_h
41 
42 #ifndef reda_dll_h
43 #include "reda/reda_dll.h"
44 #endif
45 
46 #ifdef __cplusplus
47 extern "C"
48 {
49 #endif
50 
51 /*ci
52  * \brief REDA_Buffer pool properties specified when a buffer pool is created
53  */
54 struct REDA_BufferPoolProperty
55 {
56  /*ci
57  * \brief The size of an element in the buffer pool. Note that in case the
58  * buffer contains pointers to other memory location, the size must be
59  * the size of the top-level structure only.
60  */
61  RTI_SIZE_T buffer_size;
62 
63  /*ci
64  * \brief The maximum number of buffers managed by the pool
65  */
66  RTI_SIZE_T max_buffers;
67 
68  /*ci
69  * \brief Additional flags to specify the behavior of the pool
70  */
71  RTI_INT32 flags;
72 };
73 
74 /*ci
75  * \def REDA_BUFFERPOOL_FLAG_ARRAY_ALLOC
76  * \brief Create a single array of elements. This could improve memory
77  * utilization for smaller sizes
78  */
79 #define REDA_BUFFERPOOL_FLAG_ARRAY_ALLOC (0x1)
80 
81 /*ci
82  * \def REDA_BufferPoolProperty_INITIALIZER
83  * \brief REDA_BufferPoolProperty initializer
84  */
85 #define REDA_BufferPoolProperty_INITIALIZER \
86 { \
87  0,\
88  0,\
89  0\
90 }
91 
92 /*ci
93  * \def REDA_BUFFERPOOL_UNLIMITED
94  * \brief Constant to indicate an UNLIMITED buffer-pool. Specifying this constant
95  * will result in a run-time error.
96  */
97 #define REDA_BUFFERPOOL_UNLIMITED (0xffffffff)
98 
99 struct REDA_BufferPool;
100 
101 /*ci
102  * \brief Abstract REDA_BufferPool type
103  */
104 typedef struct REDA_BufferPool *REDA_BufferPool_T;
105 
106 /*ci
107  *
108  * \brief REDA_BufferPool initialization function type.
109  *
110  * \details
111  *
112  * For each buffer that is allocated from system memory
113  * REDA buffer calls this function exactly once.
114  *
115  * \param[in] initialize_param Parameter passed to \ref REDA_BufferPool_new
116  * \param[in] buffer Buffer to initialize
117  *
118  */
119 FUNCTION_MUST_TYPEDEF(
120 RTI_BOOL
121 (*REDA_BufferPool_initializeFunc_T)(void *initialize_param, void *buffer)
122 )
123 
124 /*ci
125  *
126  * \brief REDA_BufferPool finalization type
127  *
128  * \details
129  * For each buffer that is returned to system memory REDA buffer calls
130  * this function exactly once
131  *
132  * \param[in] finalize_param Parameter passed to \ref REDA_BufferPool_new
133  * \param[in] buffer Buffer to finalize
134  */
135 FUNCTION_SHOULD_TYPEDEF(
136 RTI_BOOL
137 (*REDA_BufferPool_finalizeFunc_T)(void *finalize_param, void *buffer)
138 )
139 
140 /*ci
141  * \brief Create a new bufferpool
142  *
143  * \param[in] property BufferPool property. Refer to \ref
144  * REDA_BufferPoolProperty for details.
145  * \param[in] initialize_func Buffer initialization function. This function
146  * is called exactly once for each buffer managed by the pool. NULL
147  * is legal, in which case a buffer is not guaranteed to have a
148  * known state.
149  * \param[in] initialize_param Opaque parameter passed to the initialize_func
150  * \param[in] finalize_func Buffer finalizing function. This function is called
151  * exactly once before a buffer before it is returned to system
152  * memory. NULL is legal, in which case the buffer is returned
153  * as is to the system memory.
154  * \param[in] finalize_param Opaque parameter passed to the finalize_func
155  *
156  * \return Pointer to new buffer pool on success, NULL on failure
157  *
158  * \sa REDA_BufferPool_delete
159  *
160  */
161 MUST_CHECK_RETURN REDADllExport REDA_BufferPool_T
162 REDA_BufferPool_new(const char* name,struct REDA_BufferPoolProperty *property,
163  REDA_BufferPool_initializeFunc_T initialize_func,
164  void *initialize_param,
165  REDA_BufferPool_finalizeFunc_T finalize_func,
166  void *finalize_param);
167 
168 #ifndef RTI_CERT
169 /*ci
170  *
171  * \brief Delete a bufferpool
172  *
173  * \details
174  *
175  * Return all buffers managed by the buffer-pool to system memory. It is not
176  * legal to delete a buffer-pool with outstanding buffers.
177  *
178  * \param[in] pool BufferPool to delete
179  *
180  * \return RTI_TRUE on success, RTI_FALSE on failure.
181  *
182  * \sa REDA_BufferPool_delete
183  */
184 SHOULD_CHECK_RETURN REDADllExport RTI_BOOL
185 REDA_BufferPool_delete(REDA_BufferPool_T pool);
186 #endif /* !RTI_CERT */
187 
188 /*ci
189  * \brief Get a buffer from the buffer pool
190  *
191  * \details
192  *
193  * Take a buffer out of the free-pool and return it to the caller for use.
194  * Note that the buffer returned from the pool has only been initialized with
195  * the initialize_func passed to the REDA_BufferPool_new when the pool was
196  * created.
197  *
198  * \param[in] pool BufferPool to get buffer from
199  *
200  * \return pointer to buffer on success, NULL on failure
201  *
202  * \sa REDA_BufferPool_return_buffer
203  */
204 MUST_CHECK_RETURN REDADllExport void*
205 REDA_BufferPool_get_buffer(REDA_BufferPool_T pool);
206 
207 /*ci
208  * \brief Return a buffer to the buffer-pool
209  *
210  * \details
211  *
212  * Return a buffer to the buffer-pool and make it available for future
213  * calls to \ref REDA_BufferPool_get_buffer. Note that the finalize_func
214  * is <em> not </em> called when a buffer is returned to the pool.
215  *
216  * \param[in] pool BufferPool to return buffer to
217  * \param[in] buffer buffer to return to pool
218  *
219  * \return pointer to buffer on success, NULL on failure
220  *
221  * \sa REDA_BufferPool_return_buffer
222  */
223 REDADllExport void
224 REDA_BufferPool_return_buffer(REDA_BufferPool_T pool,void *buffer);
225 
226 #ifdef __cplusplus
227 } /* extern "C" */
228 #endif
229 
230 
231 #endif /* reda_bufferpool_h */
232 
233 /*ci @} */

RTI Connext DDS Micro Version 2.4.6 Copyright © Sun Jan 24 2016 Real-Time Innovations, Inc