RTI Connext DDS Micro
Version 2.4.6
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
/*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
#ifndef RTI_CERT
235
/*e \ingroup OSAPI_HeapClass
236
\brief A static method to return a block (that was previously
237
allocated with \ref OSAPI_Heap_allocate_buffer) to the heap.
238
239
@param[in] buffer If NULL, no op.
240
*/
241
OSAPIDllExport
void
242
OSAPI_Heap_free_buffer
(
void
*buffer);
243
#endif
/* !RTI_CERT */
244
245
#ifndef RTI_CERT
246
/*e \ingroup OSAPI_HeapClass
247
\brief Current allocated bytes
248
*/
249
OSAPIDllVariable
extern
RTI_SIZE_T
OSAPI_gv_AllocatedByteCount
;
250
#endif
/* !RTI_CERT */
251
252
#ifndef RTI_CERT
253
/*e \ingroup OSAPI_HeapClass
254
\brief Return current allocated memory
255
256
\mtsafety UNSAFE
257
*/
258
OSAPIDllExport RTI_SIZE_T
259
OSAPI_Heap_get_allocated_byte_count
(
void
);
260
#endif
/* !RTI_CERT */
261
262
#ifndef RTI_CERT
263
/*e \ingroup OSAPI_HeapClass
264
\brief Disable memory allocation
265
266
*/
267
OSAPIDllExport
void
268
OSAPI_Heap_disable_alloc
(
void
);
269
#endif
/* !RTI_CERT */
270
271
#ifdef __cplusplus
272
}
/* extern "C" */
273
#endif
274
275
276
#include "
osapi/osapi_heap_impl.h
"
277
278
#endif
/* osapi_heap_h */
RTI Connext DDS Micro Version 2.4.6
Copyright © Mon Jan 25 2016
Real-Time Innovations, Inc