RTI Connext DDS Micro
Version 2.4.10
Main Page
Related Pages
Manuals
All
Data Structures
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
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-2015
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
#ifndef RTI_CERT
60
extern
OSAPIDllVariable RTI_BOOL OSAPI_Heap_gv_disabled_alloc;
61
#endif
/* !RTI_CERT */
62
63
/*e \ingroup OSAPI_HeapClass
64
* \brief Allocates zero-initialized memory from the heap.
65
*
66
* \details
67
*
68
* The function allocates `count` elements of size `size`
69
* and sets the memory region to 0.
70
*
71
* NOTE: This operation assumes the specified size to be > 0; this operation
72
* is never used directly but it is only accessed by using one of the other
73
* allocate operations of OSAPI_Heap (e.g. allocate_struct, allocate_array,
74
* allocate_string...); these operations are implemented as macros and accept
75
* a "type" argument which is always converted to a size > 0 using the sizeof
76
* operator.
77
*
78
* \param[in] count The number of elements to allocate.
79
*
80
* \param[in] size The size of the element; size is assumed to be always
81
* greater than 0.
82
*
83
* \return. A pointer to a contiguous memory area guaranteed to be large
84
* enough store `count` elements of size `size`.
85
*
86
* \sa \ref OSAPI_Heap_free
87
*/
88
OSAPIDllExport
void
*
89
OSAPI_Heap_allocate
(RTI_INT32 count,RTI_INT32 size);
90
91
/*e \ingroup OSAPI_HeapClass
92
* \brief Reallocate memory from the heap.
93
*
94
* \param[in] ptr Currently allocated buffer
95
*
96
* \param[in] size The new desired size
97
*
98
* \return. A pointer to a contiguous memory area guaranteed to be large
99
* enough store size bytes, NULL if the reallocation failed.
100
*
101
* \sa \ref OSAPI_Heap_free
102
*/
103
OSAPIDllExport
void
*
104
OSAPI_Heap_realloc
(
void
*ptr,RTI_INT32 size);
105
106
/*e \ingroup OSAPI_HeapClass
107
*
108
* \brief Frees memory allocated from the heap.
109
*
110
* \details
111
*
112
* The function frees memory previously allocated with \ref OSAPI_Heap_allocate
113
* back to the heap.
114
*
115
* \param[in] ptr Pointer to region previous allocated
116
* with \ref OSAPI_Heap_allocate
117
*
118
*
119
* \sa \ref OSAPI_Heap_allocate
120
*/
121
OSAPIDllExport
void
122
OSAPI_Heap_free
(
void
*ptr);
123
124
/*e \ingroup OSAPI_HeapClass
125
\brief Allocates space on the heap for a C structure and
126
initializes the structure with 0's.
127
128
Example:
129
\code
130
struct MyStruct *myStruct;
131
OSAPI_Heap_allocate_struct(&myStruct, struct MyStruct);
132
if (myStruct==NULL) {
133
return;
134
}
135
\endcode
136
137
The returned space must be freed with \ref OSAPI_Heap_free_struct.
138
139
NOTE: This operation is implemented as a macro in order to support the
140
specification of a "type" argument (converted to a size value using the
141
sizeof operator).
142
*/
143
OSAPIDllExport
void
144
OSAPI_Heap_allocate_struct
(TYPE **pointer, TYPE);
145
146
147
/*e \ingroup OSAPI_HeapClass
148
\brief Returns previously allocated
149
(with \ref OSAPI_Heap_allocate_struct) space to the heap.
150
151
@param[in] pointer If NULL, no op.
152
153
Example:
154
\code
155
char *c;
156
OSAPI_Heap_allocate_struct(&c, char);
157
OSAPI_Heap_free_struct(c);
158
\endcode
159
*/
160
OSAPIDllExport
void
161
OSAPI_Heap_free_struct
(TYPE *pointer);
162
163
164
/*e \ingroup OSAPI_HeapClass
165
\brief A static method to allocate space on the heap for an array of C
166
structures; the array is initialized with 0's.
167
168
Example:
169
\code
170
struct MyElement *array;
171
OSAPI_Heap_allocate_struct(&array, 7, struct MyElement);
172
if (array==NULL) {
173
return;
174
}
175
// elements of the array can be accessed as array[i]
176
\endcode
177
178
The returned space must be freed with \ref OSAPI_Heap_free_array.
179
180
NOTE: This operation is implemented as a macro in order to support the
181
specification of a "type" argument (converted to a size value using the
182
sizeof operator).
183
*/
184
OSAPIDllExport
void
185
OSAPI_Heap_allocate_array
(TYPE ** pointer,
int
count,TYPE);
186
187
188
/*e \ingroup OSAPI_HeapClass
189
\brief A static method to return space (that was previously
190
allocated with \ref OSAPI_Heap_allocate_array) to the heap.
191
192
Example:
193
\code
194
char *c;
195
OSAPI_Heap_allocate_array(&c, 1, char);
196
OSAPI_Heap_free_array(c);
197
\endcode
198
199
@param[in] storage If NULL, no op.
200
*/
201
OSAPIDllExport
void
202
OSAPI_Heap_free_array
(TYPE *storage);
203
204
205
/*e \ingroup OSAPI_HeapClass
206
\brief A static method to allocate space on the heap for a string of up to
207
a given size. The string is initialized with 0's.
208
209
Example:
210
\code
211
char* myString;
212
OSAPI_Heap_allocate_string(&myString, 128);
213
\endcode
214
215
@param[out] pointer String buffer.
216
@param[in] size Size in bytes to allocate; this length must not include
217
the string terminator, which is automatically added to the specified value.
218
219
The returned space must be freed with \ref OSAPI_Heap_free_string.
220
*/
221
OSAPIDllExport
void
222
OSAPI_Heap_allocate_string
(
char
**pointer,RTI_UINT32 size);
223
224
/*e \ingroup OSAPI_HeapClass
225
\brief A static method to return space string space to the heap.
226
227
@param[in] pointer If NULL, no op.
228
*/
229
OSAPIDllExport
void
230
OSAPI_Heap_free_string
(
char
*pointer);
231
232
/*e \ingroup OSAPI_HeapClass
233
\brief A static method to allocate a block of memory of the provided
234
size from the heap.
235
236
@post The returned address will be a multiple of 2^alignment; its
237
memory will be initialized with 0's.
238
239
@param[out] buffer
240
@param[in] size > 0
241
@param[in] alignment Power of 2 and >0 or OSAPI_ALIGNMENT_DEFAULT.
242
If the alignment is OSAPI_ALIGNMENT_DEFAULT,
243
the returned pointer will have "default alignment" (meaning that any
244
C-structure can start at the beginning of the buffer).
245
246
The block must be returned to the heap with \ref OSAPI_Heap_free_buffer.
247
*/
248
OSAPIDllExport
void
249
OSAPI_Heap_allocate_buffer
(
char
**buffer,
250
RTI_UINT32 size,
251
OSAPI_Alignment_T alignment);
252
253
#ifndef RTI_CERT
254
/*e \ingroup OSAPI_HeapClass
255
\brief A static method to return a block (that was previously
256
allocated with \ref OSAPI_Heap_allocate_buffer) to the heap.
257
258
@param[in] buffer If NULL, no op.
259
*/
260
OSAPIDllExport
void
261
OSAPI_Heap_free_buffer
(
void
*buffer);
262
#endif
/* !RTI_CERT */
263
264
#ifndef RTI_CERT
265
/*e \ingroup OSAPI_HeapClass
266
\brief Current allocated bytes
267
*/
268
OSAPIDllVariable
extern
RTI_SIZE_T
OSAPI_gv_AllocatedByteCount
;
269
#endif
/* !RTI_CERT */
270
271
#ifndef RTI_CERT
272
/*e \ingroup OSAPI_HeapClass
273
\brief Return current allocated memory
274
275
\mtsafety UNSAFE
276
*/
277
OSAPIDllExport RTI_SIZE_T
278
OSAPI_Heap_get_allocated_byte_count
(
void
);
279
#endif
/* !RTI_CERT */
280
281
#ifndef RTI_CERT
282
/*e \ingroup OSAPI_HeapClass
283
\brief Disable memory allocation
284
285
*/
286
OSAPIDllExport
void
287
OSAPI_Heap_disable_alloc
(
void
);
288
#endif
/* !RTI_CERT */
289
290
#ifdef __cplusplus
291
}
/* extern "C" */
292
#endif
293
294
295
#include "
osapi/osapi_heap_impl.h
"
296
297
#endif
/* osapi_heap_h */
RTI Connext DDS Micro Version 2.4.10
Copyright © Fri Jun 30 2017
Real-Time Innovations, Inc