RTI Connext Micro  Version 2.4.1.0
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
osapi_heap.h
Go to the documentation of this file.
1 /*
2  * FILE: osapi_heap.h - Heap interface definition
3  *
4  * (c) Copyright, Real-Time Innovations, 2008-2014
5  *
6  * All rights reserved.
7  *
8  * No duplications, whole or partial, manual or electronic, may be made
9  * without express written permission. Any such copies, or
10  * revisions thereof, must display this notice unaltered.
11  * This code contains trade secrets of Real-Time Innovations, Inc.
12  *
13  * Modification History
14  * --------------------
15  * 29apr2014,as MICRO-775 Remove unused OSAPI_Heap_reallocate_string
16  * 28apr2014,as MICRO-228 (Verocel PR#1407) Document that allocation operations
17  * of OSAPI_Heap always expect a size greater than 0.
18  * 22sep2008,tk Written
19  */
20 /*ce
21  * \file
22  * \brief Heap interface definition
23  */
24 #ifndef osapi_heap_h
25 #define osapi_heap_h
26 
27 #ifndef osapi_dll_h
28 #include "osapi/osapi_dll.h"
29 #endif
30 #ifndef osapi_types_h
31 #include "osapi/osapi_types.h"
32 #endif
33 
34 #ifdef __cplusplus
35 extern "C"
36 {
37 #endif
38 
39 #define TYPE RTI_UINT32
40 
41 /*e \defgroup OSAPI_HeapClass OSAPI Heap
42  * \ingroup OSAPIModule
43  */
44 
45 /*ce \ingroup OSAPI_HeapClass
46  @brief The OSAPIAlignment is the alignment in bytes; an address
47  is aligned when it is a positive integer multiple of the alignment
48 */
49 typedef RTI_INT32 OSAPI_Alignment_T;
50 
51 /*e \ingroup OSAPIAlignmentClass
52  @brief Certain methods allow a default alignment: this should
53  be an alignment that follows the "malloc" alignment of
54  the architecture (aligned sufficiently to store any C-structure
55  efficiently).
56 */
57 #define OSAPI_ALIGNMENT_DEFAULT (-1)
58 
59 /*e \ingroup OSAPI_HeapClass
60  * \brief Allocates zero-initialized memory from the heap.
61  *
62  * \details
63  *
64  * The function allocates `count` elements of size `size`
65  * and sets the memory region to 0.
66  *
67  * NOTE: This operation assumes the specified size to be > 0; this operation
68  * is never used directly but it is only accessed by using one of the other
69  * allocate operations of OSAPI_Heap (e.g. allocate_struct, allocate_array,
70  * allocate_string...); these operations are implemented as macros and accept
71  * a "type" argument which is always converted to a size > 0 using the sizeof
72  * operator.
73  *
74  * \param[in] count The number of elements to allocate.
75  *
76  * \param[in] size The size of the element; size is assumed to be always
77  * greater than 0.
78  *
79  * \return. A pointer to a contiguous memory area guaranteed to be large
80  * enough store `count` elements of size `size`.
81  *
82  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Heap_free
83  */
84 OSAPIDllExport void*
85 OSAPI_Heap_allocate(RTI_INT32 count,RTI_INT32 size);
86 
87 /*e \ingroup OSAPI_HeapClass
88  *
89  * \brief Frees memory allocated from the heap.
90  *
91  * \details
92  *
93  * The function frees memory previously allocated with \ref OSAPI_Heap_allocate
94  * back to the heap.
95  *
96  * \param[in] ptr Pointer to region previous allocated
97  * with \ref OSAPI_Heap_allocate
98  *
99  *
100  * \sa \ref OSAPIPortingIntroClass, \ref OSAPI_Heap_allocate
101  */
102 OSAPIDllExport void
103 OSAPI_Heap_free(void *ptr);
104 
105 /*e \ingroup OSAPI_HeapClass
106  \brief Allocates space on the heap for a C structure and
107  initializes the structure with 0's.
108 
109  Example:
110  \code
111  struct MyStruct *myStruct;
112  OSAPI_Heap_allocate_struct(&myStruct, struct MyStruct);
113  if (myStruct==NULL) {
114  return;
115  }
116  \endcode
117 
118  The returned space must be freed with \ref OSAPI_Heap_free_struct.
119 
120  NOTE: This operation is implemented as a macro in order to support the
121  specification of a "type" argument (converted to a size value using the
122  sizeof operator).
123 */
124 OSAPIDllExport void
125 OSAPI_Heap_allocate_struct(TYPE **pointer, TYPE);
126 
127 
128 /*e \ingroup OSAPI_HeapClass
129  \brief Returns previously allocated
130  (with \ref OSAPI_Heap_allocate_struct) space to the heap.
131 
132  @param[in] pointer If NULL, no op.
133 
134  Example:
135  \code
136  char *c;
137  OSAPI_Heap_allocate_struct(&c, char);
138  OSAPI_Heap_free_struct(c);
139  \endcode
140  */
141 OSAPIDllExport void
142 OSAPI_Heap_free_struct(TYPE *pointer);
143 
144 
145 /*e \ingroup OSAPI_HeapClass
146  \brief A static method to allocate space on the heap for an array of C
147  structures; the array is initialized with 0's.
148 
149  Example:
150  \code
151  struct MyElement *array;
152  OSAPI_Heap_allocate_struct(&array, 7, struct MyElement);
153  if (array==NULL) {
154  return;
155  }
156  // elements of the array can be accessed as array[i]
157  \endcode
158 
159  The returned space must be freed with \ref OSAPI_Heap_free_array.
160 
161  NOTE: This operation is implemented as a macro in order to support the
162  specification of a "type" argument (converted to a size value using the
163  sizeof operator).
164 */
165 OSAPIDllExport void
166 OSAPI_Heap_allocate_array(TYPE ** pointer, int count,TYPE);
167 
168 
169 /*e \ingroup OSAPI_HeapClass
170  \brief A static method to return space (that was previously
171  allocated with \ref OSAPI_Heap_allocate_array) to the heap.
172 
173  Example:
174  \code
175  char *c;
176  OSAPI_Heap_allocate_array(&c, 1, char);
177  OSAPI_Heap_free_array(c);
178  \endcode
179 
180  @param[in] storage If NULL, no op.
181  */
182 OSAPIDllExport void
183 OSAPI_Heap_free_array(TYPE *storage);
184 
185 
186 /*e \ingroup OSAPI_HeapClass
187  \brief A static method to allocate space on the heap for a string of up to
188  a given size. The string is initialized with 0's.
189 
190  Example:
191  \code
192  char* myString;
193  OSAPI_Heap_allocate_string(&myString, 128);
194  \endcode
195 
196  @param[out] pointer String buffer.
197  @param[in] size Size in bytes to allocate; this length must not include
198  the string terminator, which is automatically added to the specified value.
199 
200  The returned space must be freed with \ref OSAPI_Heap_free_string.
201  */
202 OSAPIDllExport void
203 OSAPI_Heap_allocate_string(char **pointer,RTI_UINT32 size);
204 
205 /*e \ingroup OSAPI_HeapClass
206  \brief A static method to return space string space to the heap.
207 
208  @param[in] pointer If NULL, no op.
209  */
210 OSAPIDllExport void
211 OSAPI_Heap_free_string(char *pointer);
212 
213 /*e \ingroup OSAPI_HeapClass
214  \brief A static method to allocate a block of memory of the provided
215  size from the heap.
216 
217  @post The returned address will be a multiple of 2^alignment; its
218  memory will be initialized with 0's.
219 
220  @param[out] buffer
221  @param[in] size > 0
222  @param[in] alignment Power of 2 and >0 or OSAPI_ALIGNMENT_DEFAULT.
223  If the alignment is OSAPI_ALIGNMENT_DEFAULT,
224  the returned pointer will have "default alignment" (meaning that any
225  C-structure can start at the beginning of the buffer).
226 
227  The block must be returned to the heap with \ref OSAPI_Heap_free_buffer.
228 */
229 OSAPIDllExport void
230 OSAPI_Heap_allocate_buffer(char **buffer,
231  RTI_UINT32 size,
232  OSAPI_Alignment_T alignment);
233 
234 /*e \ingroup OSAPI_HeapClass
235  \brief A static method to return a block (that was previously
236  allocated with \ref OSAPI_Heap_allocate_buffer) to the heap.
237 
238  @param[in] buffer If NULL, no op.
239 */
240 OSAPIDllExport void
241 OSAPI_Heap_free_buffer(void *buffer);
242 
243 /*e \ingroup OSAPI_HeapClass
244  \brief Current allocated bytes
245 */
246 OSAPIDllVariable extern RTI_SIZE_T OSAPI_gv_AllocatedByteCount;
247 
248 /*e \ingroup OSAPI_HeapClass
249  \brief Return current allocated memory
250 
251  \mtsafety UNSAFE
252 */
253 OSAPIDllExport RTI_SIZE_T
255 
256 #ifdef __cplusplus
257 } /* extern "C" */
258 #endif
259 
260 
261 #include "osapi/osapi_heap_impl.h"
262 
263 #endif /* osapi_heap_h */

RTI Connext Micro Version 2.4.1.0 Copyright © Thu Nov 20 2014 Real-Time Innovations, Inc