1/*---------------------------------------------------------------------------*
2 *  pmemory.h  *
3 *                                                                           *
4 *  Copyright 2007, 2008 Nuance Communciations, Inc.                               *
5 *                                                                           *
6 *  Licensed under the Apache License, Version 2.0 (the 'License');          *
7 *  you may not use this file except in compliance with the License.         *
8 *                                                                           *
9 *  You may obtain a copy of the License at                                  *
10 *      http://www.apache.org/licenses/LICENSE-2.0                           *
11 *                                                                           *
12 *  Unless required by applicable law or agreed to in writing, software      *
13 *  distributed under the License is distributed on an 'AS IS' BASIS,        *
14 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. *
15 *  See the License for the specific language governing permissions and      *
16 *  limitations under the License.                                           *
17 *                                                                           *
18 *---------------------------------------------------------------------------*/
19
20#ifndef PMEMORY_H
21#define PMEMORY_H
22
23
24
25/* #define PMEM_MAP_TRACE */
26
27#include "PortPrefix.h"
28#include "ptypes.h"
29#include "pstdio.h"
30#include <stddef.h>
31#include <stdlib.h>
32
33/**
34 * @addtogroup PmemoryModule PMemory API functions
35 * Library for basic memory management.
36 * Call PMemInit() to initialize and PmemShutdown() to shutdown module.
37 *
38 * @{
39 */
40
41/**
42 * Returns macro to string format.
43 */
44#define _VAL(x) #x
45/**
46 * Converts a digit to a string.
47 */
48#define _STR(x) _VAL(x)
49
50#ifndef offsetof
51#define offsetof(type, member) ((size_t) &(((type *)0)->member))
52#endif
53
54/**
55 * \<static_cast\> implementation for C.
56 */
57#define STATIC_CAST(self, subClass, member) ((subClass*) (((char*) self) - (offsetof(subClass, member))))
58
59
60#define USE_STDLIB_MALLOC
61
62#ifdef USE_STDLIB_MALLOC
63
64#define MALLOC(n, tag) malloc(n)
65#define CALLOC(m, n, tag) calloc(m, n)
66#define CALLOC_CLR(m, n, tag) calloc(m, n)
67#define REALLOC(p, n) realloc(p, n)
68#define FREE(p) free(p)
69#define NEW(type, tag) ((type*)MALLOC(sizeof(type), tag))
70#define NEW_ARRAY(type, n, tag) ((type*)CALLOC(n, sizeof(type), tag))
71
72#define PMemInit() ESR_SUCCESS
73#define PMemShutdown() ESR_SUCCESS
74#define PMemSetLogFile(f) ESR_NOT_SUPPORTED
75#define PMemDumpLogFile() ESR_NOT_SUPPORTED
76#define PMemSetLogEnabled(b) ESR_NOT_SUPPORTED
77#define PMemLogFree(p) (free(p), ESR_SUCCESS)
78#define PMemReport(f) ESR_NOT_SUPPORTED
79#define PMemorySetPoolSize(n) ESR_NOT_SUPPORTED
80#define PMemoryGetPoolSize(p) ESR_NOT_SUPPORTED
81
82#else
83
84#ifdef DISABLE_MALLOC
85#define malloc #error
86#define calloc #error
87#define realloc #error
88#define free #error
89#endif
90
91/*
92 * PMEM_MAP_TRACE is not defined by default.
93 * It is up to user to define PMEM_MAP_TRACE;
94 * define in either makefile or here for test purpose.
95 */
96
97#ifdef PMEM_MAP_TRACE
98/**
99 * Portable malloc()
100 */
101#define MALLOC(nbBytes, tag) (pmalloc(nbBytes, tag, L(__FILE__), __LINE__))
102#else
103/**
104 * Portable malloc()
105 */
106#define MALLOC(nbBytes, tag) (pmalloc(nbBytes))
107#endif
108
109#ifdef PMEM_MAP_TRACE
110/**
111 * Portable calloc()
112 */
113#define CALLOC(nbElem, elemSize, tag) (pcalloc(nbElem,  elemSize  , tag, L(__FILE__), __LINE__))
114#define CALLOC_CLR(nbElem, elemSize, tag) (pcalloc(nbElem,  elemSize  , tag, L(__FILE__), __LINE__))
115#else
116/**
117 * Portable calloc()
118 */
119#define CALLOC(nbElem, elemSize, tag) (pcalloc(nbElem,  elemSize))
120#define CALLOC_CLR(nbElem, elemSize, tag) (pcalloc(nbElem,  elemSize))
121#endif
122
123#ifdef PMEM_MAP_TRACE
124/**
125 * Portable realloc()
126 */
127#define REALLOC(ptr, newSize) (prealloc(ptr, newSize, L(__FILE__), __LINE__))
128#else
129/**
130 * Portable realloc()
131 */
132#define REALLOC(ptr, newSize) (prealloc(ptr, newSize))
133#endif
134
135/**
136 * Portable new()
137 */
138#define NEW(type, tag) ((type*) MALLOC(sizeof(type), tag))
139
140/**
141 * Allocates a new array
142 */
143#define NEW_ARRAY(type, nbElem, tag) ((type *) CALLOC(nbElem, sizeof(type), tag))
144
145#ifdef PMEM_MAP_TRACE
146/**
147 * Portable free()
148 */
149#define FREE(ptr) pfree(ptr, L(__FILE__), __LINE__)
150#else
151/**
152 * Portable free()
153 */
154#define FREE(ptr) pfree(ptr)
155#endif
156
157/**
158 * @}
159 */
160
161/**
162 * Allocates specified number of bytes, similar to malloc but initializes the
163 * memory to 0.
164 *
165 * @param nbBytes The number of bytes to allocate.
166 *
167 * @param tag     The tag associated with the memory for reporting.
168 *
169 * @param file The file name in which the function is invoked.  Should be the
170 * __FILE__ macro.
171 *
172 * @param line The line at which the function is invoked.  Should be the
173 * __LINE__ macro.
174 **/
175#ifdef PMEM_MAP_TRACE
176PORTABLE_API void *pmalloc(size_t nbBytes, const LCHAR* tag, const LCHAR* file, int line);
177#else
178PORTABLE_API void *pmalloc(size_t nbBytes);
179#endif
180
181/**
182 * Allocate an array of items, similar to calloc.
183 *
184 * @param nbItems  The number items to allocate.
185 *
186 * @param itemSize The size of each item.
187 *
188 * @param tag      The tag associated with the memory for reporting.
189 *
190 * @param file The file name in which the function is invoked.  Should be the
191 * __FILE__ macro.
192 *
193 * @param line The line at which the function is invoked.  Should be the
194 * __LINE__ macro.
195 *
196 **/
197#ifdef PMEM_MAP_TRACE
198PORTABLE_API void *pcalloc(size_t nbItems, size_t itemSize, const LCHAR* tag, const LCHAR* file, int line);
199#else
200PORTABLE_API void *pcalloc(size_t nbItems, size_t itemSize);
201#endif
202
203/**
204 * Reallocates data.  Similar to realloc.
205 *
206 * @param ptr A pointer previously allocated by pmalloc, pcalloc or prealloc.
207 *
208 * @param newSize The new size required.
209 *
210 * @param file The file name in which the function is invoked.  Should be the
211 * __FILE__ macro.
212 *
213 * @param line The line at which the function is invoked.  Should be the
214 * __LINE__ macro.
215 *
216 **/
217#ifdef PMEM_MAP_TRACE
218PORTABLE_API void *prealloc(void* ptr, size_t newSize, const LCHAR* file, int line);
219#else
220PORTABLE_API void *prealloc(void* ptr, size_t newSize);
221#endif
222
223/**
224 * Frees data allocated through pmalloc, pcalloc or realloc.
225 *
226 * @param ptr A pointer previously allocated by pmalloc, pcalloc or prealloc.
227 *
228 * @param file The file name in which the function is invoked.  Should be the
229 * __FILE__ macro.
230 *
231 * @param line The line at which the function is invoked.  Should be the
232 * __LINE__ macro.
233 *
234 **/
235#ifdef PMEM_MAP_TRACE
236PORTABLE_API void pfree(void* ptr, const LCHAR* file, int line);
237#else
238PORTABLE_API void pfree(void* ptr);
239#endif
240
241/**
242 * @addtogroup PmemoryModule PMemory API functions
243 * Library for basic memory management.
244 * Call PMemInit() to initialize and PmemShutdown() to shutdown module.
245 *
246 * @{
247 */
248
249/**
250 * Initializes the memory management API.
251 *
252 * @return ESR_INVALID_STATE if the PMem module is already initialized or an internal error occurs
253 */
254PORTABLE_API ESR_ReturnCode PMemInit(void);
255
256/**
257 * Shutdowns the memory management API.  pmemReport is invoked with the same
258 * file that was provided to pmemInit.
259 *
260 * @return ESR_INVALID_STATE if the PMem module is not initialized
261 */
262PORTABLE_API ESR_ReturnCode PMemShutdown(void);
263
264/**
265 * Enables low-level logging to file. This logs individual memory allocations and
266 * deallocations. On shutdown, pmemDumpLogFile() will be invoked.
267 *
268 * @param file A file in which logging of memory related operations should be
269 *    performed. If NULL, no logging is performed.
270 * @return ESR_INVALID_STATE if the PMem module is not initialized
271 */
272PORTABLE_API ESR_ReturnCode PMemSetLogFile(PFile* file);
273
274/**
275 * Dumps memory report to the log file, closes it and disables logging.
276 *
277 * @return ESR_INVALID_STATE if the PMem module is not initialized or an internal error occurs
278 */
279PORTABLE_API ESR_ReturnCode PMemDumpLogFile(void);
280
281/**
282 * Enables/disables memory logging. This is useful for hiding allocations/deallocation
283 * from pmemReport() and other reporting mechanisms, simply disable logging prior
284 * to hidden operations and reenable it thereafter.
285 *
286 * @param value True if logging should be enabled
287 * @return ESR_SUCCESS
288 */
289PORTABLE_API ESR_ReturnCode PMemSetLogEnabled(ESR_BOOL value);
290
291/**
292 * Hide memory allocation from pmemReport() by pretending the memory was deallocating. This is used to hide
293 * memory leaks from pmemReport(), which is useful for internal variables which are deallocated after the
294 * final call to pmemReport() occurs.
295 *
296 * @param ptr Address of memory allocation that should be hidden
297 * @return ESR_SUCCESS
298 */
299PORTABLE_API ESR_ReturnCode PMemLogFree(void* ptr);
300
301/**
302 * Generates a report of the memory allocation.
303 *
304 * @param file A file in which the report is generated.  If set to NULL, the
305 * report will be generated in the same file as that was provided to pmemInit.
306 * Therefore, it is possible that no report is generated if the function is
307 * invoked with NULL and pmemInit was also invoked with NULL.
308 * @return ESR_WRITE_ERROR if an error occurs while writing to the file
309 */
310PORTABLE_API ESR_ReturnCode PMemReport(PFile* file);
311
312/**
313 * Allow user to set the memory pool size when S2G uses its own memory management.
314 * It should be called before PMemInit()
315 * The predefined (default) size is 3M for S2G
316 *
317 * @param size the memory pool size in byte
318 * @return ESR_NOT_SUPPORTED if S2G uses native memory management; ESR_INVALID_STATE if it is called after PMemInit()
319 */
320PORTABLE_API ESR_ReturnCode PMemorySetPoolSize(size_t size);
321
322/**
323 * Get the memory pool size when S2G uses its own memory management
324 *
325 * @param size the memory pool size in byte
326 * @return ESR_NOT_SUPPORTED if S2G uses native memory management
327 */
328PORTABLE_API ESR_ReturnCode PMemoryGetPoolSize(size_t *size);
329
330/**
331 * @}
332 */
333
334#endif
335
336#endif
337