Index: /trunk/psLib/src/Doxyfile =================================================================== --- /trunk/psLib/src/Doxyfile (revision 647) +++ /trunk/psLib/src/Doxyfile (revision 648) @@ -15,5 +15,5 @@ #--------------------------------------------------------------------------- -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded # by quotes) that should identify the project. @@ -833,9 +833,9 @@ #--------------------------------------------------------------------------- -# Configuration options related to the preprocessor -#--------------------------------------------------------------------------- - -# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will -# evaluate all C-preprocessor directives found in the sources and include +# Configuration options related to the preprocessor +#--------------------------------------------------------------------------- + +# If the ENABLE_PREPROCESSING tag is set to YES (the default) Doxygen will +# evaluate all C-preprocessor directives found in the sources and include # files. @@ -874,13 +874,13 @@ # The PREDEFINED tag can be used to specify one or more macro names that -# are defined before the preprocessor is started (similar to the -D option of -# gcc). The argument of the tag is a list of macros of the form: name -# or name=definition (no spaces). If the definition and the = are +# are defined before the preprocessor is started (similar to the -D option of +# gcc). The argument of the tag is a list of macros of the form: name +# or name=definition (no spaces). If the definition and the = are # omitted =1 is assumed. -PREDEFINED = - -# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then -# this tag can be used to specify a list of macro names that should be expanded. +PREDEFINED = DOXYGEN + +# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then +# this tag can be used to specify a list of macro names that should be expanded. # The macro definition that is found in the sources will be used. # Use the PREDEFINED tag if you want to use a different macro definition. Index: /trunk/psLib/src/sys/psMemory.c =================================================================== --- /trunk/psLib/src/sys/psMemory.c (revision 647) +++ /trunk/psLib/src/sys/psMemory.c (revision 648) @@ -8,6 +8,6 @@ * @author Robert Lupton, Princeton University * - * @version $Revision: 1.17 $ $Name: not supported by cvs2svn $ - * @date $Date: 2004-05-11 20:11:17 $ + * @version $Revision: 1.18 $ $Name: not supported by cvs2svn $ + * @date $Date: 2004-05-12 19:05:02 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -20,4 +20,5 @@ #include #include +#include #include "psMemory.h" @@ -34,5 +35,5 @@ * Unique ID for allocated blocks */ -static unsigned long memid = 0; +static psMemoryId memid = 0; /** @@ -62,5 +63,5 @@ const char *file, int lineno) { - if (ptr->refCounter <= 0) { + if (ptr->refCounter < 1) { psError(__func__, "Block %ld allocated at %s:%d freed more than once at %s:%d\n", @@ -95,10 +96,10 @@ * Call the callbacks when these IDs are allocated/freed */ -long p_psMemAllocateID = 0; // notify user this block is allocated -long p_psMemFreeID = 0; // notify user this block is freed - -long psMemAllocateCallbackSetID(long id) // set p_psMemAllocateID to id -{ - long old = p_psMemAllocateID; +psMemoryId p_psMemAllocateID = 0; // notify user this block is allocated +psMemoryId p_psMemFreeID = 0; // notify user this block is freed + +psMemoryId psMemAllocateCallbackSetID(psMemoryId id) // set p_psMemAllocateID to id +{ + psMemoryId old = p_psMemAllocateID; p_psMemAllocateID = id; @@ -106,7 +107,7 @@ } -long psMemFreeCallbackSetID(long id) // set p_psMemFreeID to id -{ - long old = p_psMemFreeID; +psMemoryId psMemFreeCallbackSetID(psMemoryId id) // set p_psMemFreeID to id +{ + psMemoryId old = p_psMemFreeID; p_psMemFreeID = id; @@ -120,14 +121,14 @@ * isn't resignalled) */ -static long memAllocateCallbackDefault(const psMemBlock *ptr) -{ - static int incr = 0; // "p_psMemAllocateID += incr" +static psMemoryId memAllocateCallbackDefault(const psMemBlock *ptr) +{ + static psMemoryId incr = 0; // "p_psMemAllocateID += incr" return incr; } -static long memFreeCallbackDefault(const psMemBlock *ptr) -{ - static int incr = 0; // "p_psMemFreeID += incr" +static psMemoryId memFreeCallbackDefault(const psMemBlock *ptr) +{ + static psMemoryId incr = 0; // "p_psMemFreeID += incr" return incr; @@ -169,5 +170,5 @@ * Return memory ID counter for next block to be allocated */ -int psMemGetId(void) +psMemoryId psMemGetId(void) { return memid + 1; @@ -199,6 +200,11 @@ if (m->startblock != P_PS_MEMMAGIC || m->endblock != P_PS_MEMMAGIC) { - psError(funcName, "psMemCheckCorruption: memory block %ld is corrupted (%p %p)", + psError(funcName, "psMemCheckCorruption: memory block %ld is corrupted (buffer underflow %p %p)", m->id,m->startblock,m->endblock); + return(1); + } + if (*(void**)((int8_t*)(m+1)+m->userMemorySize) != P_PS_MEMMAGIC) { + psError(funcName, "psMemCheckCorruption: memory block %ld is corrupted (buffer overflow, %p)", + m->id,*(void**)((int8_t*)(m+1)+m->userMemorySize)); return(1); } @@ -236,5 +242,5 @@ void *p_psAlloc(size_t size, const char *file, int lineno) { - psMemBlock *ptr = malloc(sizeof(psMemBlock) + size); + psMemBlock *ptr = malloc(sizeof(psMemBlock) + size + sizeof(void*)); if (ptr == NULL) { @@ -246,5 +252,5 @@ } - *(unsigned long*)&ptr->id = ++memid; + *(psMemoryId*)&ptr->id = ++memid; ptr->file = file; *(unsigned int*)&ptr->lineno = lineno; @@ -252,4 +258,6 @@ ptr->endblock = P_PS_MEMMAGIC; ptr->refCounter = 1; // one user so far + ptr->userMemorySize = size; + *(void**)((int8_t*)(ptr+1)+size) = P_PS_MEMMAGIC; // need exclusive access of the memory block list now... @@ -287,5 +295,5 @@ isBlockLast = (ptr == lastMemBlockAllocated); - ptr = (psMemBlock*)realloc(ptr, sizeof(psMemBlock) + size); + ptr = (psMemBlock*)realloc(ptr, sizeof(psMemBlock) + size + sizeof(void*)); if (ptr == NULL) { @@ -293,4 +301,7 @@ size, file, lineno); } + + ptr->userMemorySize = size; + *(void**)((int8_t*)(ptr+1)+size) = P_PS_MEMMAGIC; if (isBlockLast) { @@ -363,5 +374,5 @@ */ int psMemCheckLeaks( - int id0, // don't list blocks with id < id0 + psMemoryId id0, // don't list blocks with id < id0 psMemBlock ***arr, // pointer to array of pointers to leaked blocks, or NULL FILE *fd) // print list of leaks to fd (or NULL) @@ -416,5 +427,5 @@ * Reference counting APIs */ -int psMemGetRefCounter(void *vptr) // return refCounter +psReferenceCount psMemGetRefCounter(void *vptr) // return refCounter { psMemBlock *ptr = ((psMemBlock *)vptr) - 1; Index: /trunk/psLib/src/sys/psMemory.h =================================================================== --- /trunk/psLib/src/sys/psMemory.h (revision 647) +++ /trunk/psLib/src/sys/psMemory.h (revision 648) @@ -12,6 +12,8 @@ * @author Robert Lupton, Princeton University * - * @version $Revision: 1.10 $ $Name: not supported by cvs2svn $ - * @date $Date: 2004-05-11 20:11:17 $ + * @version $Revision: 1.11 $ $Name: not supported by cvs2svn $ + * @date $Date: 2004-05-12 19:05:02 $ + * + * @ingroup SystemGroup System Utilities * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -19,4 +21,32 @@ #include // needed for FILE + + +/** @addtogroup MemoryManagement Memory Management Utilities + * @ingroup SystemGroup + * + * This is the generic memory management system put inbetween the user's high level code and the OS-level + * memory allocation routines. This system adds such features as callback routines for memory error events, + * tracing capabilities, and reference counting. + * @{ + */ + +/** + * @addtogroup memCallback Memory Callbacks + * + * Routines dealing with the creating and setting of memory management callback functions. + */ + +/** + * @addtogroup memRefCount Reference Count + * + * Routines dealing with the reference counting of allocated buffers. + */ + +/// typedef for memory identification numbers. Guaranteed to be some variety of integer. +typedef unsigned long psMemoryId; + +/// typedef for a memory block's reference count. Guaranteed to be some variety of integer. +typedef unsigned long psReferenceCount; /** Book-keeping data for storage allocator. @@ -30,128 +60,222 @@ struct psMemBlock* previousBlock; ///< previous block in allocation list struct psMemBlock* nextBlock; ///< next block allocation list - const unsigned long id; ///< a unique ID for this allocation + size_t userMemorySize; ///< the size of the user-portion of the memory block + const psMemoryId id; ///< a unique ID for this allocation const char* file; ///< set from __FILE__ in e.g. p_psAlloc const int lineno; ///< set from __LINE__ in e.g. p_psAlloc - unsigned int refCounter; ///< how many times pointer is referenced + psReferenceCount refCounter; ///< how many times pointer is referenced const void* endblock; ///< initialised to p_psMEMMAGIC } psMemBlock; -/// prototype of a basic callback used by memory functions -typedef long (*psMemAllocateCallback)(const psMemBlock *ptr); - -/// prototype of memory free callback used by memory functions -typedef long (*psMemFreeCallback)(const psMemBlock *ptr); +/** prototype of a basic callback used by memory functions + * + * @see psMemAllocateCallbackSet + * @ingroup memCallback + */ +typedef psMemoryId (*psMemAllocateCallback)( + const psMemBlock *ptr ///< the psMemBlock just allocated +); + +/** prototype of memory free callback used by memory functions + * + * @see psMemFreeCallbackSet + * @ingroup memCallback + */ +typedef psMemoryId (*psMemFreeCallback)( + const psMemBlock *ptr ///< the psMemBlock being freed +); /** prototype of a callback used in error conditions * - * This callback should never try to call psAlloc or psFree. - * - */ -typedef void (*psMemProblemCallback)(const psMemBlock *ptr, const char *file, int lineno); - -/// prototype of a callback used when memory runs out -typedef void *(*psMemExhaustedCallback)(size_t size); - -/** Private Functions **************************************************************/ -/** \addtogroup sysUtils memory private - * \{ - */ - -/// Memory allocation. Underlying private function called by macro psAlloc. -void* p_psAlloc(size_t size, ///< Size required - const char *file, ///< File of call - int lineno) ///< Line number of call -; - -/// Memory re-allocation. Underlying private function called by macro psRealloc. -void* p_psRealloc(void *ptr, ///< Pointer to re-allocate - size_t size, ///< Size required - const char *file, ///< File of call - int lineno) ///< Line number of call -; - -/// Free memory. Underlying private function called by macro psFree. -void p_psFree(void *ptr, ///< Pointer to free - const char *file, ///< File of call - int lineno) ///< Line number of call -; -/** Public Functions **************************************************************/ -/** \} - * \addtogroup sysUtils memory psLibAPI - * \{ - */ - -/// Check for memory leaks + * This callback should not try to call psAlloc or psFree. + * + * @see psMemProblemCallbackSet + * @ingroup memCallback + */ +typedef void (*psMemProblemCallback)( + const psMemBlock *ptr, ///< the pointer to the problematic memory block. + const char *file, ///< the file in which the problem originated + int lineno ///< the line number in which the problem originated +); + +/** prototype of a callback function used when memory runs out + * + * @return void* pointer to requested buffer of the size size_t, or NULL if memory could not + * be found. + * + * @see psMemExhaustedCallbackSet + * @ingroup memCallback + */ +typedef void *(*psMemExhaustedCallback)( + size_t size //< the size of buffer required +); + +/** Memory allocation. This operates much like malloc(), but is guaranteed to return a non-NULL value. + * + * @return void* pointer to the allocated buffer. This will not be NULL. + * @see psFree + */ +#ifdef DOXYGEN +void* psAlloc( + size_t size ///< Size required +); +#else +void* p_psAlloc( + size_t size, ///< Size required + const char *file, ///< File of call + int lineno ///< Line number of call +); +/// Memory allocation. psAlloc sends file and line number to p_psAlloc. +#define psAlloc(size) p_psAlloc(size, __FILE__, __LINE__) +#endif + + +/** Memory re-allocation. This operates much like realloc(), but is guaranteed to return a non-NULL value. + * + * @return void* pointer to resized buffer. This will not be NULL. + * @see psAlloc, psFree + */ +#ifdef DOXYGEN +void* psRealloc(void *ptr ///< Pointer to re-allocate + ); +#else +void* p_psRealloc(void *ptr, ///< Pointer to re-allocate + size_t size, ///< Size required + const char *file, ///< File of call + int lineno ///< Line number of call + ); + +/// Memory re-allocation. psRealloc sends file and line number to p_psRealloc. +#define psRealloc(ptr, size) p_psRealloc(ptr, size, __FILE__, __LINE__) + +#endif + + +/** Free memory. This operates much like free(). + * + * @see psAlloc, psRealloc + */ +#ifdef DOXYGEN +void psFree(void *ptr, ///< Pointer to free, if NULL, function returns immediately. + ); +#else +void p_psFree(void *ptr, ///< Pointer to free + const char *file, ///< File of call + int lineno ///< Line number of call + ); + +/// Free memory. psFree sends file and line number to p_psFree. +#define psFree(size) p_psFree(size, __FILE__, __LINE__) + +#endif + +/** Check for memory leaks. This scans for allocated memory buffers not freed with an ID not less than id0. + * This is used to check for memory leaks by: + * -# before a block of code to be checked, store the current ID count via psGetMemId + * -# after the block of code to be checked, call this function using the ID stored above. If all + * memory in the block that was allocated has been freed, this call should output nothing and + * return 0. + * + * If memory leaks are found, the Memory Problem callback will be called as well. + * + * return int number of memory blocks found as 'leaks', i.e., the number of currently allocated memory + * blocks above id0 that have not been freed. + * @see psAlloc, psFree, psgetMemId, psMemProblemCallbackSet + */ int psMemCheckLeaks( - int id0, ///< don't list blocks with id < id0 + psMemoryId id0, ///< don't list blocks with id < id0 psMemBlock ***arr, ///< pointer to array of pointers to leaked blocks, or NULL FILE *fd ///< print list of leaks to fd (or NULL) ); -/// Check for memory corruption +/** Check for memory corruption. Scans all currently allocated memory buffers and checks for corruptions, + * i.e., invalid markers that signify a buffer under/overflow. + * + */ int psMemCheckCorruption( int abort_on_error ///< Abort on detecting corruption? ); -/// Return reference counter -int psMemGetRefCounter( +/** Return reference counter + * + * @ingroup memRefCount + */ +psReferenceCount psMemGetRefCounter( void *vptr ///< Pointer to get refCounter for ); -/// Increment reference counter and return the pointer +/** Increment reference counter and return the pointer + * + * @ingroup memRefCount + */ void *psMemIncrRefCounter( void *vptr ///< Pointer to increment refCounter, and return ); -/// Decrement reference counter and return the pointer +/** Decrement reference counter and return the pointer + * + * @ingroup memRefCount + */ void *psMemDecrRefCounter( void *vptr ///< Pointer to decrement refCounter, and return ); -/// Set callback for problems +/** Set callback for problems + * @ingroup memCallback + */ psMemProblemCallback psMemProblemCallbackSet( psMemProblemCallback func ///< Function to run ); -/// Set callback for out-of-memory +/** Set callback for out-of-memory + * + * @ingroup memCallback + */ psMemExhaustedCallback psMemExhaustedCallbackSet( psMemExhaustedCallback func ///< Function to run ); -/// Set call back for when a particular memory block is allocated +/** Set call back for when a particular memory block is allocated + * + * @ingroup memCallback + */ psMemAllocateCallback psMemAllocateCallbackSet( - psMemAllocateCallback func ///< Function to run -); - -/// Set call back for when a particular memory block is freed + psMemAllocateCallback func ///< Function to run +); + +/** Set call back for when a particular memory block is freed + * + * @ingroup memCallback + */ psMemFreeCallback psMemFreeCallbackSet( - psMemFreeCallback func ///< Function to run -); - -/// get next memory ID -int psMemGetId(void) -; - -/// set p_psMemAllocateID to id -long psMemAllocateCallbackSetID( - long id ///< ID to set -); - -/// set p_psMemFreeID to id -long psMemFreeCallbackSetID( - long id ///< ID to set -); - -//@} End of public Functions - -/// Memory allocation. psAlloc sends file and line number to p_psAlloc. -#define psAlloc(size) p_psAlloc(size, __FILE__, __LINE__) - -/// Memory re-allocation. psRealloc sends file and line number to p_psRealloc. -#define psRealloc(ptr, size) p_psRealloc(ptr, size, __FILE__, __LINE__) - -/// Free memory. psFree sends file and line number to p_psFree. -#define psFree(size) p_psFree(size, __FILE__, __LINE__) + psMemFreeCallback func ///< Function to run +); + +/** get next memory ID + * + * @ingroup memCallback + */ +psMemoryId psMemGetId(void); + +/** set p_psMemAllocateID to id + * + * @ingroup memCallback + */ +psMemoryId psMemAllocateCallbackSetID( + psMemoryId id ///< ID to set +); + +/** set p_psMemFreeID to id + * + * @ingroup memCallback + */ +psMemoryId psMemFreeCallbackSetID( + psMemoryId id ///< ID to set +); + +//@} End of Memory Management Functions + +#ifndef DOXYGEN /* @@ -169,3 +293,5 @@ #endif +#endif // doxygen skip + #endif // end of header file Index: /trunk/psLib/src/sysUtils/psMemory.c =================================================================== --- /trunk/psLib/src/sysUtils/psMemory.c (revision 647) +++ /trunk/psLib/src/sysUtils/psMemory.c (revision 648) @@ -8,6 +8,6 @@ * @author Robert Lupton, Princeton University * - * @version $Revision: 1.17 $ $Name: not supported by cvs2svn $ - * @date $Date: 2004-05-11 20:11:17 $ + * @version $Revision: 1.18 $ $Name: not supported by cvs2svn $ + * @date $Date: 2004-05-12 19:05:02 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -20,4 +20,5 @@ #include #include +#include #include "psMemory.h" @@ -34,5 +35,5 @@ * Unique ID for allocated blocks */ -static unsigned long memid = 0; +static psMemoryId memid = 0; /** @@ -62,5 +63,5 @@ const char *file, int lineno) { - if (ptr->refCounter <= 0) { + if (ptr->refCounter < 1) { psError(__func__, "Block %ld allocated at %s:%d freed more than once at %s:%d\n", @@ -95,10 +96,10 @@ * Call the callbacks when these IDs are allocated/freed */ -long p_psMemAllocateID = 0; // notify user this block is allocated -long p_psMemFreeID = 0; // notify user this block is freed - -long psMemAllocateCallbackSetID(long id) // set p_psMemAllocateID to id -{ - long old = p_psMemAllocateID; +psMemoryId p_psMemAllocateID = 0; // notify user this block is allocated +psMemoryId p_psMemFreeID = 0; // notify user this block is freed + +psMemoryId psMemAllocateCallbackSetID(psMemoryId id) // set p_psMemAllocateID to id +{ + psMemoryId old = p_psMemAllocateID; p_psMemAllocateID = id; @@ -106,7 +107,7 @@ } -long psMemFreeCallbackSetID(long id) // set p_psMemFreeID to id -{ - long old = p_psMemFreeID; +psMemoryId psMemFreeCallbackSetID(psMemoryId id) // set p_psMemFreeID to id +{ + psMemoryId old = p_psMemFreeID; p_psMemFreeID = id; @@ -120,14 +121,14 @@ * isn't resignalled) */ -static long memAllocateCallbackDefault(const psMemBlock *ptr) -{ - static int incr = 0; // "p_psMemAllocateID += incr" +static psMemoryId memAllocateCallbackDefault(const psMemBlock *ptr) +{ + static psMemoryId incr = 0; // "p_psMemAllocateID += incr" return incr; } -static long memFreeCallbackDefault(const psMemBlock *ptr) -{ - static int incr = 0; // "p_psMemFreeID += incr" +static psMemoryId memFreeCallbackDefault(const psMemBlock *ptr) +{ + static psMemoryId incr = 0; // "p_psMemFreeID += incr" return incr; @@ -169,5 +170,5 @@ * Return memory ID counter for next block to be allocated */ -int psMemGetId(void) +psMemoryId psMemGetId(void) { return memid + 1; @@ -199,6 +200,11 @@ if (m->startblock != P_PS_MEMMAGIC || m->endblock != P_PS_MEMMAGIC) { - psError(funcName, "psMemCheckCorruption: memory block %ld is corrupted (%p %p)", + psError(funcName, "psMemCheckCorruption: memory block %ld is corrupted (buffer underflow %p %p)", m->id,m->startblock,m->endblock); + return(1); + } + if (*(void**)((int8_t*)(m+1)+m->userMemorySize) != P_PS_MEMMAGIC) { + psError(funcName, "psMemCheckCorruption: memory block %ld is corrupted (buffer overflow, %p)", + m->id,*(void**)((int8_t*)(m+1)+m->userMemorySize)); return(1); } @@ -236,5 +242,5 @@ void *p_psAlloc(size_t size, const char *file, int lineno) { - psMemBlock *ptr = malloc(sizeof(psMemBlock) + size); + psMemBlock *ptr = malloc(sizeof(psMemBlock) + size + sizeof(void*)); if (ptr == NULL) { @@ -246,5 +252,5 @@ } - *(unsigned long*)&ptr->id = ++memid; + *(psMemoryId*)&ptr->id = ++memid; ptr->file = file; *(unsigned int*)&ptr->lineno = lineno; @@ -252,4 +258,6 @@ ptr->endblock = P_PS_MEMMAGIC; ptr->refCounter = 1; // one user so far + ptr->userMemorySize = size; + *(void**)((int8_t*)(ptr+1)+size) = P_PS_MEMMAGIC; // need exclusive access of the memory block list now... @@ -287,5 +295,5 @@ isBlockLast = (ptr == lastMemBlockAllocated); - ptr = (psMemBlock*)realloc(ptr, sizeof(psMemBlock) + size); + ptr = (psMemBlock*)realloc(ptr, sizeof(psMemBlock) + size + sizeof(void*)); if (ptr == NULL) { @@ -293,4 +301,7 @@ size, file, lineno); } + + ptr->userMemorySize = size; + *(void**)((int8_t*)(ptr+1)+size) = P_PS_MEMMAGIC; if (isBlockLast) { @@ -363,5 +374,5 @@ */ int psMemCheckLeaks( - int id0, // don't list blocks with id < id0 + psMemoryId id0, // don't list blocks with id < id0 psMemBlock ***arr, // pointer to array of pointers to leaked blocks, or NULL FILE *fd) // print list of leaks to fd (or NULL) @@ -416,5 +427,5 @@ * Reference counting APIs */ -int psMemGetRefCounter(void *vptr) // return refCounter +psReferenceCount psMemGetRefCounter(void *vptr) // return refCounter { psMemBlock *ptr = ((psMemBlock *)vptr) - 1; Index: /trunk/psLib/src/sysUtils/psMemory.h =================================================================== --- /trunk/psLib/src/sysUtils/psMemory.h (revision 647) +++ /trunk/psLib/src/sysUtils/psMemory.h (revision 648) @@ -12,6 +12,8 @@ * @author Robert Lupton, Princeton University * - * @version $Revision: 1.10 $ $Name: not supported by cvs2svn $ - * @date $Date: 2004-05-11 20:11:17 $ + * @version $Revision: 1.11 $ $Name: not supported by cvs2svn $ + * @date $Date: 2004-05-12 19:05:02 $ + * + * @ingroup SystemGroup System Utilities * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii @@ -19,4 +21,32 @@ #include // needed for FILE + + +/** @addtogroup MemoryManagement Memory Management Utilities + * @ingroup SystemGroup + * + * This is the generic memory management system put inbetween the user's high level code and the OS-level + * memory allocation routines. This system adds such features as callback routines for memory error events, + * tracing capabilities, and reference counting. + * @{ + */ + +/** + * @addtogroup memCallback Memory Callbacks + * + * Routines dealing with the creating and setting of memory management callback functions. + */ + +/** + * @addtogroup memRefCount Reference Count + * + * Routines dealing with the reference counting of allocated buffers. + */ + +/// typedef for memory identification numbers. Guaranteed to be some variety of integer. +typedef unsigned long psMemoryId; + +/// typedef for a memory block's reference count. Guaranteed to be some variety of integer. +typedef unsigned long psReferenceCount; /** Book-keeping data for storage allocator. @@ -30,128 +60,222 @@ struct psMemBlock* previousBlock; ///< previous block in allocation list struct psMemBlock* nextBlock; ///< next block allocation list - const unsigned long id; ///< a unique ID for this allocation + size_t userMemorySize; ///< the size of the user-portion of the memory block + const psMemoryId id; ///< a unique ID for this allocation const char* file; ///< set from __FILE__ in e.g. p_psAlloc const int lineno; ///< set from __LINE__ in e.g. p_psAlloc - unsigned int refCounter; ///< how many times pointer is referenced + psReferenceCount refCounter; ///< how many times pointer is referenced const void* endblock; ///< initialised to p_psMEMMAGIC } psMemBlock; -/// prototype of a basic callback used by memory functions -typedef long (*psMemAllocateCallback)(const psMemBlock *ptr); - -/// prototype of memory free callback used by memory functions -typedef long (*psMemFreeCallback)(const psMemBlock *ptr); +/** prototype of a basic callback used by memory functions + * + * @see psMemAllocateCallbackSet + * @ingroup memCallback + */ +typedef psMemoryId (*psMemAllocateCallback)( + const psMemBlock *ptr ///< the psMemBlock just allocated +); + +/** prototype of memory free callback used by memory functions + * + * @see psMemFreeCallbackSet + * @ingroup memCallback + */ +typedef psMemoryId (*psMemFreeCallback)( + const psMemBlock *ptr ///< the psMemBlock being freed +); /** prototype of a callback used in error conditions * - * This callback should never try to call psAlloc or psFree. - * - */ -typedef void (*psMemProblemCallback)(const psMemBlock *ptr, const char *file, int lineno); - -/// prototype of a callback used when memory runs out -typedef void *(*psMemExhaustedCallback)(size_t size); - -/** Private Functions **************************************************************/ -/** \addtogroup sysUtils memory private - * \{ - */ - -/// Memory allocation. Underlying private function called by macro psAlloc. -void* p_psAlloc(size_t size, ///< Size required - const char *file, ///< File of call - int lineno) ///< Line number of call -; - -/// Memory re-allocation. Underlying private function called by macro psRealloc. -void* p_psRealloc(void *ptr, ///< Pointer to re-allocate - size_t size, ///< Size required - const char *file, ///< File of call - int lineno) ///< Line number of call -; - -/// Free memory. Underlying private function called by macro psFree. -void p_psFree(void *ptr, ///< Pointer to free - const char *file, ///< File of call - int lineno) ///< Line number of call -; -/** Public Functions **************************************************************/ -/** \} - * \addtogroup sysUtils memory psLibAPI - * \{ - */ - -/// Check for memory leaks + * This callback should not try to call psAlloc or psFree. + * + * @see psMemProblemCallbackSet + * @ingroup memCallback + */ +typedef void (*psMemProblemCallback)( + const psMemBlock *ptr, ///< the pointer to the problematic memory block. + const char *file, ///< the file in which the problem originated + int lineno ///< the line number in which the problem originated +); + +/** prototype of a callback function used when memory runs out + * + * @return void* pointer to requested buffer of the size size_t, or NULL if memory could not + * be found. + * + * @see psMemExhaustedCallbackSet + * @ingroup memCallback + */ +typedef void *(*psMemExhaustedCallback)( + size_t size //< the size of buffer required +); + +/** Memory allocation. This operates much like malloc(), but is guaranteed to return a non-NULL value. + * + * @return void* pointer to the allocated buffer. This will not be NULL. + * @see psFree + */ +#ifdef DOXYGEN +void* psAlloc( + size_t size ///< Size required +); +#else +void* p_psAlloc( + size_t size, ///< Size required + const char *file, ///< File of call + int lineno ///< Line number of call +); +/// Memory allocation. psAlloc sends file and line number to p_psAlloc. +#define psAlloc(size) p_psAlloc(size, __FILE__, __LINE__) +#endif + + +/** Memory re-allocation. This operates much like realloc(), but is guaranteed to return a non-NULL value. + * + * @return void* pointer to resized buffer. This will not be NULL. + * @see psAlloc, psFree + */ +#ifdef DOXYGEN +void* psRealloc(void *ptr ///< Pointer to re-allocate + ); +#else +void* p_psRealloc(void *ptr, ///< Pointer to re-allocate + size_t size, ///< Size required + const char *file, ///< File of call + int lineno ///< Line number of call + ); + +/// Memory re-allocation. psRealloc sends file and line number to p_psRealloc. +#define psRealloc(ptr, size) p_psRealloc(ptr, size, __FILE__, __LINE__) + +#endif + + +/** Free memory. This operates much like free(). + * + * @see psAlloc, psRealloc + */ +#ifdef DOXYGEN +void psFree(void *ptr, ///< Pointer to free, if NULL, function returns immediately. + ); +#else +void p_psFree(void *ptr, ///< Pointer to free + const char *file, ///< File of call + int lineno ///< Line number of call + ); + +/// Free memory. psFree sends file and line number to p_psFree. +#define psFree(size) p_psFree(size, __FILE__, __LINE__) + +#endif + +/** Check for memory leaks. This scans for allocated memory buffers not freed with an ID not less than id0. + * This is used to check for memory leaks by: + * -# before a block of code to be checked, store the current ID count via psGetMemId + * -# after the block of code to be checked, call this function using the ID stored above. If all + * memory in the block that was allocated has been freed, this call should output nothing and + * return 0. + * + * If memory leaks are found, the Memory Problem callback will be called as well. + * + * return int number of memory blocks found as 'leaks', i.e., the number of currently allocated memory + * blocks above id0 that have not been freed. + * @see psAlloc, psFree, psgetMemId, psMemProblemCallbackSet + */ int psMemCheckLeaks( - int id0, ///< don't list blocks with id < id0 + psMemoryId id0, ///< don't list blocks with id < id0 psMemBlock ***arr, ///< pointer to array of pointers to leaked blocks, or NULL FILE *fd ///< print list of leaks to fd (or NULL) ); -/// Check for memory corruption +/** Check for memory corruption. Scans all currently allocated memory buffers and checks for corruptions, + * i.e., invalid markers that signify a buffer under/overflow. + * + */ int psMemCheckCorruption( int abort_on_error ///< Abort on detecting corruption? ); -/// Return reference counter -int psMemGetRefCounter( +/** Return reference counter + * + * @ingroup memRefCount + */ +psReferenceCount psMemGetRefCounter( void *vptr ///< Pointer to get refCounter for ); -/// Increment reference counter and return the pointer +/** Increment reference counter and return the pointer + * + * @ingroup memRefCount + */ void *psMemIncrRefCounter( void *vptr ///< Pointer to increment refCounter, and return ); -/// Decrement reference counter and return the pointer +/** Decrement reference counter and return the pointer + * + * @ingroup memRefCount + */ void *psMemDecrRefCounter( void *vptr ///< Pointer to decrement refCounter, and return ); -/// Set callback for problems +/** Set callback for problems + * @ingroup memCallback + */ psMemProblemCallback psMemProblemCallbackSet( psMemProblemCallback func ///< Function to run ); -/// Set callback for out-of-memory +/** Set callback for out-of-memory + * + * @ingroup memCallback + */ psMemExhaustedCallback psMemExhaustedCallbackSet( psMemExhaustedCallback func ///< Function to run ); -/// Set call back for when a particular memory block is allocated +/** Set call back for when a particular memory block is allocated + * + * @ingroup memCallback + */ psMemAllocateCallback psMemAllocateCallbackSet( - psMemAllocateCallback func ///< Function to run -); - -/// Set call back for when a particular memory block is freed + psMemAllocateCallback func ///< Function to run +); + +/** Set call back for when a particular memory block is freed + * + * @ingroup memCallback + */ psMemFreeCallback psMemFreeCallbackSet( - psMemFreeCallback func ///< Function to run -); - -/// get next memory ID -int psMemGetId(void) -; - -/// set p_psMemAllocateID to id -long psMemAllocateCallbackSetID( - long id ///< ID to set -); - -/// set p_psMemFreeID to id -long psMemFreeCallbackSetID( - long id ///< ID to set -); - -//@} End of public Functions - -/// Memory allocation. psAlloc sends file and line number to p_psAlloc. -#define psAlloc(size) p_psAlloc(size, __FILE__, __LINE__) - -/// Memory re-allocation. psRealloc sends file and line number to p_psRealloc. -#define psRealloc(ptr, size) p_psRealloc(ptr, size, __FILE__, __LINE__) - -/// Free memory. psFree sends file and line number to p_psFree. -#define psFree(size) p_psFree(size, __FILE__, __LINE__) + psMemFreeCallback func ///< Function to run +); + +/** get next memory ID + * + * @ingroup memCallback + */ +psMemoryId psMemGetId(void); + +/** set p_psMemAllocateID to id + * + * @ingroup memCallback + */ +psMemoryId psMemAllocateCallbackSetID( + psMemoryId id ///< ID to set +); + +/** set p_psMemFreeID to id + * + * @ingroup memCallback + */ +psMemoryId psMemFreeCallbackSetID( + psMemoryId id ///< ID to set +); + +//@} End of Memory Management Functions + +#ifndef DOXYGEN /* @@ -169,3 +293,5 @@ #endif +#endif // doxygen skip + #endif // end of header file