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 176 PORTABLE_API void *pmalloc(size_t nbBytes, const LCHAR* tag, const LCHAR* file, int line); 177 #else 178 PORTABLE_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 198 PORTABLE_API void *pcalloc(size_t nbItems, size_t itemSize, const LCHAR* tag, const LCHAR* file, int line); 199 #else 200 PORTABLE_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 218 PORTABLE_API void *prealloc(void* ptr, size_t newSize, const LCHAR* file, int line); 219 #else 220 PORTABLE_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 236 PORTABLE_API void pfree(void* ptr, const LCHAR* file, int line); 237 #else 238 PORTABLE_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 */ 254 PORTABLE_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 */ 262 PORTABLE_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 */ 272 PORTABLE_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 */ 279 PORTABLE_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 */ 289 PORTABLE_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 */ 299 PORTABLE_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 */ 310 PORTABLE_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 */ 320 PORTABLE_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 */ 328 PORTABLE_API ESR_ReturnCode PMemoryGetPoolSize(size_t *size); 329 330 /** 331 * @} 332 */ 333 334 #endif 335 336 #endif 337