Changeset 648 for trunk/psLib/src/sys/psMemory.h
- Timestamp:
- May 12, 2004, 9:05:02 AM (22 years ago)
- File:
-
- 1 edited
-
trunk/psLib/src/sys/psMemory.h (modified) (4 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/psLib/src/sys/psMemory.h
r639 r648 12 12 * @author Robert Lupton, Princeton University 13 13 * 14 * @version $Revision: 1.10 $ $Name: not supported by cvs2svn $ 15 * @date $Date: 2004-05-11 20:11:17 $ 14 * @version $Revision: 1.11 $ $Name: not supported by cvs2svn $ 15 * @date $Date: 2004-05-12 19:05:02 $ 16 * 17 * @ingroup SystemGroup System Utilities 16 18 * 17 19 * Copyright 2004 Maui High Performance Computing Center, University of Hawaii … … 19 21 20 22 #include <stdio.h> // needed for FILE 23 24 25 /** @addtogroup MemoryManagement Memory Management Utilities 26 * @ingroup SystemGroup 27 * 28 * This is the generic memory management system put inbetween the user's high level code and the OS-level 29 * memory allocation routines. This system adds such features as callback routines for memory error events, 30 * tracing capabilities, and reference counting. 31 * @{ 32 */ 33 34 /** 35 * @addtogroup memCallback Memory Callbacks 36 * 37 * Routines dealing with the creating and setting of memory management callback functions. 38 */ 39 40 /** 41 * @addtogroup memRefCount Reference Count 42 * 43 * Routines dealing with the reference counting of allocated buffers. 44 */ 45 46 /// typedef for memory identification numbers. Guaranteed to be some variety of integer. 47 typedef unsigned long psMemoryId; 48 49 /// typedef for a memory block's reference count. Guaranteed to be some variety of integer. 50 typedef unsigned long psReferenceCount; 21 51 22 52 /** Book-keeping data for storage allocator. … … 30 60 struct psMemBlock* previousBlock; ///< previous block in allocation list 31 61 struct psMemBlock* nextBlock; ///< next block allocation list 32 const unsigned long id; ///< a unique ID for this allocation 62 size_t userMemorySize; ///< the size of the user-portion of the memory block 63 const psMemoryId id; ///< a unique ID for this allocation 33 64 const char* file; ///< set from __FILE__ in e.g. p_psAlloc 34 65 const int lineno; ///< set from __LINE__ in e.g. p_psAlloc 35 unsigned int refCounter; ///< how many times pointer is referenced66 psReferenceCount refCounter; ///< how many times pointer is referenced 36 67 const void* endblock; ///< initialised to p_psMEMMAGIC 37 68 } 38 69 psMemBlock; 39 70 40 /// prototype of a basic callback used by memory functions 41 typedef long (*psMemAllocateCallback)(const psMemBlock *ptr); 42 43 /// prototype of memory free callback used by memory functions 44 typedef long (*psMemFreeCallback)(const psMemBlock *ptr); 71 /** prototype of a basic callback used by memory functions 72 * 73 * @see psMemAllocateCallbackSet 74 * @ingroup memCallback 75 */ 76 typedef psMemoryId (*psMemAllocateCallback)( 77 const psMemBlock *ptr ///< the psMemBlock just allocated 78 ); 79 80 /** prototype of memory free callback used by memory functions 81 * 82 * @see psMemFreeCallbackSet 83 * @ingroup memCallback 84 */ 85 typedef psMemoryId (*psMemFreeCallback)( 86 const psMemBlock *ptr ///< the psMemBlock being freed 87 ); 45 88 46 89 /** prototype of a callback used in error conditions 47 90 * 48 * This callback should never try to call psAlloc or psFree. 49 * 50 */ 51 typedef void (*psMemProblemCallback)(const psMemBlock *ptr, const char *file, int lineno); 52 53 /// prototype of a callback used when memory runs out 54 typedef void *(*psMemExhaustedCallback)(size_t size); 55 56 /** Private Functions **************************************************************/ 57 /** \addtogroup sysUtils memory private 58 * \{ 59 */ 60 61 /// Memory allocation. Underlying private function called by macro psAlloc. 62 void* p_psAlloc(size_t size, ///< Size required 63 const char *file, ///< File of call 64 int lineno) ///< Line number of call 65 ; 66 67 /// Memory re-allocation. Underlying private function called by macro psRealloc. 68 void* p_psRealloc(void *ptr, ///< Pointer to re-allocate 69 size_t size, ///< Size required 70 const char *file, ///< File of call 71 int lineno) ///< Line number of call 72 ; 73 74 /// Free memory. Underlying private function called by macro psFree. 75 void p_psFree(void *ptr, ///< Pointer to free 76 const char *file, ///< File of call 77 int lineno) ///< Line number of call 78 ; 79 /** Public Functions **************************************************************/ 80 /** \} 81 * \addtogroup sysUtils memory psLibAPI 82 * \{ 83 */ 84 85 /// Check for memory leaks 91 * This callback should not try to call psAlloc or psFree. 92 * 93 * @see psMemProblemCallbackSet 94 * @ingroup memCallback 95 */ 96 typedef void (*psMemProblemCallback)( 97 const psMemBlock *ptr, ///< the pointer to the problematic memory block. 98 const char *file, ///< the file in which the problem originated 99 int lineno ///< the line number in which the problem originated 100 ); 101 102 /** prototype of a callback function used when memory runs out 103 * 104 * @return void* pointer to requested buffer of the size size_t, or NULL if memory could not 105 * be found. 106 * 107 * @see psMemExhaustedCallbackSet 108 * @ingroup memCallback 109 */ 110 typedef void *(*psMemExhaustedCallback)( 111 size_t size //< the size of buffer required 112 ); 113 114 /** Memory allocation. This operates much like malloc(), but is guaranteed to return a non-NULL value. 115 * 116 * @return void* pointer to the allocated buffer. This will not be NULL. 117 * @see psFree 118 */ 119 #ifdef DOXYGEN 120 void* psAlloc( 121 size_t size ///< Size required 122 ); 123 #else 124 void* p_psAlloc( 125 size_t size, ///< Size required 126 const char *file, ///< File of call 127 int lineno ///< Line number of call 128 ); 129 /// Memory allocation. psAlloc sends file and line number to p_psAlloc. 130 #define psAlloc(size) p_psAlloc(size, __FILE__, __LINE__) 131 #endif 132 133 134 /** Memory re-allocation. This operates much like realloc(), but is guaranteed to return a non-NULL value. 135 * 136 * @return void* pointer to resized buffer. This will not be NULL. 137 * @see psAlloc, psFree 138 */ 139 #ifdef DOXYGEN 140 void* psRealloc(void *ptr ///< Pointer to re-allocate 141 ); 142 #else 143 void* p_psRealloc(void *ptr, ///< Pointer to re-allocate 144 size_t size, ///< Size required 145 const char *file, ///< File of call 146 int lineno ///< Line number of call 147 ); 148 149 /// Memory re-allocation. psRealloc sends file and line number to p_psRealloc. 150 #define psRealloc(ptr, size) p_psRealloc(ptr, size, __FILE__, __LINE__) 151 152 #endif 153 154 155 /** Free memory. This operates much like free(). 156 * 157 * @see psAlloc, psRealloc 158 */ 159 #ifdef DOXYGEN 160 void psFree(void *ptr, ///< Pointer to free, if NULL, function returns immediately. 161 ); 162 #else 163 void p_psFree(void *ptr, ///< Pointer to free 164 const char *file, ///< File of call 165 int lineno ///< Line number of call 166 ); 167 168 /// Free memory. psFree sends file and line number to p_psFree. 169 #define psFree(size) p_psFree(size, __FILE__, __LINE__) 170 171 #endif 172 173 /** Check for memory leaks. This scans for allocated memory buffers not freed with an ID not less than id0. 174 * This is used to check for memory leaks by: 175 * -# before a block of code to be checked, store the current ID count via psGetMemId 176 * -# after the block of code to be checked, call this function using the ID stored above. If all 177 * memory in the block that was allocated has been freed, this call should output nothing and 178 * return 0. 179 * 180 * If memory leaks are found, the Memory Problem callback will be called as well. 181 * 182 * return int number of memory blocks found as 'leaks', i.e., the number of currently allocated memory 183 * blocks above id0 that have not been freed. 184 * @see psAlloc, psFree, psgetMemId, psMemProblemCallbackSet 185 */ 86 186 int psMemCheckLeaks( 87 int id0,///< don't list blocks with id < id0187 psMemoryId id0, ///< don't list blocks with id < id0 88 188 psMemBlock ***arr, ///< pointer to array of pointers to leaked blocks, or NULL 89 189 FILE *fd ///< print list of leaks to fd (or NULL) 90 190 ); 91 191 92 /// Check for memory corruption 192 /** Check for memory corruption. Scans all currently allocated memory buffers and checks for corruptions, 193 * i.e., invalid markers that signify a buffer under/overflow. 194 * 195 */ 93 196 int psMemCheckCorruption( 94 197 int abort_on_error ///< Abort on detecting corruption? 95 198 ); 96 199 97 /// Return reference counter 98 int psMemGetRefCounter( 200 /** Return reference counter 201 * 202 * @ingroup memRefCount 203 */ 204 psReferenceCount psMemGetRefCounter( 99 205 void *vptr ///< Pointer to get refCounter for 100 206 ); 101 207 102 /// Increment reference counter and return the pointer 208 /** Increment reference counter and return the pointer 209 * 210 * @ingroup memRefCount 211 */ 103 212 void *psMemIncrRefCounter( 104 213 void *vptr ///< Pointer to increment refCounter, and return 105 214 ); 106 215 107 /// Decrement reference counter and return the pointer 216 /** Decrement reference counter and return the pointer 217 * 218 * @ingroup memRefCount 219 */ 108 220 void *psMemDecrRefCounter( 109 221 void *vptr ///< Pointer to decrement refCounter, and return 110 222 ); 111 223 112 /// Set callback for problems 224 /** Set callback for problems 225 * @ingroup memCallback 226 */ 113 227 psMemProblemCallback psMemProblemCallbackSet( 114 228 psMemProblemCallback func ///< Function to run 115 229 ); 116 230 117 /// Set callback for out-of-memory 231 /** Set callback for out-of-memory 232 * 233 * @ingroup memCallback 234 */ 118 235 psMemExhaustedCallback psMemExhaustedCallbackSet( 119 236 psMemExhaustedCallback func ///< Function to run 120 237 ); 121 238 122 /// Set call back for when a particular memory block is allocated 239 /** Set call back for when a particular memory block is allocated 240 * 241 * @ingroup memCallback 242 */ 123 243 psMemAllocateCallback psMemAllocateCallbackSet( 124 psMemAllocateCallback func ///< Function to run 125 ); 126 127 /// Set call back for when a particular memory block is freed 244 psMemAllocateCallback func ///< Function to run 245 ); 246 247 /** Set call back for when a particular memory block is freed 248 * 249 * @ingroup memCallback 250 */ 128 251 psMemFreeCallback psMemFreeCallbackSet( 129 psMemFreeCallback func ///< Function to run 130 ); 131 132 /// get next memory ID 133 int psMemGetId(void) 134 ; 135 136 /// set p_psMemAllocateID to id 137 long psMemAllocateCallbackSetID( 138 long id ///< ID to set 139 ); 140 141 /// set p_psMemFreeID to id 142 long psMemFreeCallbackSetID( 143 long id ///< ID to set 144 ); 145 146 //@} End of public Functions 147 148 /// Memory allocation. psAlloc sends file and line number to p_psAlloc. 149 #define psAlloc(size) p_psAlloc(size, __FILE__, __LINE__) 150 151 /// Memory re-allocation. psRealloc sends file and line number to p_psRealloc. 152 #define psRealloc(ptr, size) p_psRealloc(ptr, size, __FILE__, __LINE__) 153 154 /// Free memory. psFree sends file and line number to p_psFree. 155 #define psFree(size) p_psFree(size, __FILE__, __LINE__) 252 psMemFreeCallback func ///< Function to run 253 ); 254 255 /** get next memory ID 256 * 257 * @ingroup memCallback 258 */ 259 psMemoryId psMemGetId(void); 260 261 /** set p_psMemAllocateID to id 262 * 263 * @ingroup memCallback 264 */ 265 psMemoryId psMemAllocateCallbackSetID( 266 psMemoryId id ///< ID to set 267 ); 268 269 /** set p_psMemFreeID to id 270 * 271 * @ingroup memCallback 272 */ 273 psMemoryId psMemFreeCallbackSetID( 274 psMemoryId id ///< ID to set 275 ); 276 277 //@} End of Memory Management Functions 278 279 #ifndef DOXYGEN 156 280 157 281 /* … … 169 293 #endif 170 294 295 #endif // doxygen skip 296 171 297 #endif // end of header file
Note:
See TracChangeset
for help on using the changeset viewer.
