Index: trunk/psLib/src/sys/psMemory.h =================================================================== --- trunk/psLib/src/sys/psMemory.h (revision 11672) +++ trunk/psLib/src/sys/psMemory.h (revision 11674) @@ -15,6 +15,6 @@ * @ingroup MemoryManagement * - * @version $Revision: 1.66 $ $Name: not supported by cvs2svn $ - * @date $Date: 2007-02-07 00:36:02 $ + * @version $Revision: 1.67 $ $Name: not supported by cvs2svn $ + * @date $Date: 2007-02-07 01:15:49 $ * * Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii @@ -28,5 +28,5 @@ #include // needed for FILE -#include // we need a mutex to make this stuff thread safe. +#include // mutexes #include // for uint32_t #include @@ -58,23 +58,24 @@ typedef struct psMemBlock { - const uint32_t startblock; ///< initialised to p_psMEMMAGIC - struct psMemBlock* previousBlock; ///< previous block in allocation list - struct psMemBlock* nextBlock; ///< next block allocation list - psFreeFunc freeFunc; ///< deallocator. If NULL, use generic deallocation. - size_t userMemorySize; ///< the size of the user-portion of the memory block - const psMemId id; ///< a unique ID for this allocation - const pthread_t tid; ///< set from pthread_self(); - const char *file; ///< set from __FILE__ in e.g. p_psAlloc - const unsigned int lineno; ///< set from __LINE__ in e.g. p_psAlloc - const char *func; ///< set from __func__ + const uint32_t startblock; ///< initialised to p_psMEMMAGIC + struct psMemBlock *previousBlock; ///< previous block in allocation list + struct psMemBlock *nextBlock; ///< next block allocation list + psFreeFunc freeFunc; ///< deallocator. If NULL, use generic deallocation. + size_t userMemorySize; ///< the size of the user-portion of the memory block + const psMemId id; ///< a unique ID for this allocation + const pthread_t tid; ///< set from pthread_self(); + const char *file; ///< set from __FILE__ in e.g. p_psAlloc + const unsigned int lineno; ///< set from __LINE__ in e.g. p_psAlloc + const char *func; ///< set from __func__ + #ifdef HAVE_BACKTRACE - const void **backtrace; ///< set from backtrace() - const size_t backtraceSize; ///< set from bracktrace() + const void **backtrace; ///< set from backtrace() + const size_t backtraceSize; ///< set from bracktrace() #endif // ifdef HAVE_BACKTRACE - psReferenceCount refCounter; ///< how many times pointer is referenced - bool persistent; ///< marks if this non-user persistent data like error stack, etc. - const uint32_t endblock; ///< initialised to p_psMEMMAGIC + psReferenceCount refCounter; ///< how many times pointer is referenced + bool persistent; ///< marks if this non-user persistent data like error stack, etc. + const uint32_t endblock; ///< initialised to p_psMEMMAGIC } psMemBlock; @@ -85,5 +86,5 @@ */ typedef psMemId(*psMemAllocCallback) ( - const psMemBlock* ptr ///< the psMemBlock just allocated + const psMemBlock *ptr ///< the psMemBlock just allocated ); @@ -93,5 +94,5 @@ */ typedef psMemId(*psMemFreeCallback) ( - const psMemBlock* ptr ///< the psMemBlock being freed + const psMemBlock *ptr ///< the psMemBlock being freed ); @@ -103,21 +104,23 @@ */ typedef void (*psMemProblemCallback) ( - psMemBlock* ptr, ///< the pointer to the problematic memory block. - const char *file, ///< the file in which the problem originated - unsigned int lineno ///< the line number in which the problem originated + const char *file, ///< File of caller + unsigned int lineno, ///< Line number of caller + const char *func, ///< Function name of caller + psMemBlock *ptr ///< the pointer to the problematic memory block. ); /** 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. + * @return void * pointer to requested buffer of the size size_t, or NULL if + * memory could not be found. * * @see psMemExhaustedCallbackSet */ typedef void *(*psMemExhaustedCallback) ( - size_t size ///< the size of buffer required + size_t size ///< the size of buffer required ); -/** Memory allocation. This operates much like malloc(), but is guaranteed to return a non-NULL value. +/** 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. @@ -125,552 +128,515 @@ */ #ifdef DOXYGEN - void *psAlloc( size_t size ///< Size required ); - #else // #ifdef DOXYGEN - -#ifdef __GNUC__ void *p_psAlloc( - size_t size, ///< Size required const char *file, ///< File of caller unsigned int lineno, ///< Line number of caller - const char *func ///< Function name of caller + const char *func, ///< Function name of caller + size_t size ///< Size required + #ifdef __GNUC__ ) __attribute__((malloc)); # else // __GNUC__ - void *p_psAlloc( - size_t size, ///< Size required - const char *file, ///< File of caller - unsigned int lineno, ///< Line number of caller - const char *func ///< Function name of caller - ); -#endif // __GNUC__ - -/// Memory allocation. psAlloc sends file and line number to p_psAlloc. -#ifndef SWIG -#define psAlloc(size) \ -p_psAlloc(size, __FILE__, __LINE__, __func__) -#endif // ! SWIG - -#endif // ! DOXYGEN - - -/** Set the deallocator routine - * - * A deallocator routine can optionally be assigned to a memory block to - * ensure that associated memory blocks also get freed, e.g., memory buffers - * referenced within a struct. - * - */ -#ifdef DOXYGEN - -void psMemSetDeallocator( - void *ptr, ///< the memory block to operate on - psFreeFunc freeFunc ///< the function to be executed at deallocation -); - -#else // ifdef DOXYGEN - -void p_psMemSetDeallocator( - void *ptr, ///< the memory block to operate on - psFreeFunc freeFunc, ///< the function to be executed at deallocation - const char *file, ///< File of caller - unsigned int lineno, ///< Line number of caller - const char *func ///< Function name of caller -); - -#ifndef SWIG -#define psMemSetDeallocator(ptr, freeFunc) \ -p_psMemSetDeallocator(ptr, freeFunc, __FILE__, __LINE__, __func__); -#endif // ! SWIG - -#endif // ifdef DOXYGEN - - -/** Get the deallocator routine - * - * This function returns the deallocator for a memory block. A deallocator - * routine can optionally be assigned to a memory block to ensure that - * associated memory blocks also get freed, e.g., memory buffers referenced - * within a struct. - * - * @return psFreeFunc the routine to be called at deallocation. - */ -#ifdef DOXYGEN - -psFreeFunc psMemGetDeallocator( - void *ptr ///< the memory block -); - -#else // ifdef DOXYGEN - -psFreeFunc p_psMemGetDeallocator( - void *ptr, ///< the memory block - const char *file, ///< File of caller - unsigned int lineno, ///< Line number of caller - const char *func ///< Function name of caller -); - -#ifndef SWIG -#define psMemGetDeallocator(ptr) \ -p_psMemGetDeallocator(ptr, __FILE__, __LINE__, __func__) -#endif // ! SWIG - -#endif // ifdef DOXYGEN - - -/** Activate or Deactivate thread safety and mutex locking in the memory management. - * - * psMemThreadSafety shall turn on thread safety in the memory management functions if - * safe is true, and deactivate all mutex locking in the memory management functions if - * safe is false. The function shall return the previous value of the thread safety. - * Note that the default behaviour of the library shall be for the locking to be performed. - * - * @return bool: The previous value of the thread safety. - */ -bool psMemSetThreadSafety( - bool safe ///< boolean for turning on/off thread safety -); - -/** Get the current state of thread safety and mutex locking in the memory management. - * - * psMemGetThreadSafety shall return the current state of thread safety in the memory management system. - * - * @return bool: The current state of thread safety. - */ -bool psMemGetThreadSafety(void); - - -/** Set the memory as persistent so that it is ignored when detecting memory leaks. - * - * Used to mark a memory block as persistent data within the library, - * i.e., non user-level data used to hold psLib's state or cache data. Such - * examples of this class of memory is psTrace's trace-levels and dynamic - * error codes. - * - * Memory marked as persistent is excluded from memory leak checks. - * - */ -#ifdef DOXYGEN - -void psMemSetPersistent( - void *ptr, ///< the memory block to operate on - bool value, ///< true if memory is persistent, otherwise false -); - -#else // #ifdef DOXYGEN - -void p_psMemSetPersistent( - void *ptr, ///< the memory block to operate on - bool value, ///< true if memory is persistent, otherwise false - const char *file, ///< File of caller - unsigned int lineno, ///< Line number of caller - const char *func ///< Function name of caller -); - -#ifndef SWIG -#define psMemSetPersistent(ptr, value) \ -p_psMemSetPersistent(ptr, value, __FILE__, __LINE__, __func__); -#endif // ! SWIG - -#endif // DOXYGEN - - -/** Set whether allocated memory is persistent - * - * Set whether allocated memory is persistent. The defeault is false. - * - * @return bool: The previous value of whether all allocated memory is persistent - */ -bool p_psMemAllocatePersistent(bool is_persistent); ///< Should all memory allocated be persistent? - - -/** Get the memory's persistent flag. - * - * Checks if a memory block has been marked as persistent by - * p_psMemSetPresistent. - * - * Memory marked as persistent is excluded from memory leak checks. - * - * @return bool true if memory is marked persistent, otherwise false. - */ -#ifdef DOXYGEN - -bool psMemGetPersistent( - void *ptr, ///< the memory block to check. -); -#else // ifdef DOXYGEN - -bool p_psMemGetPersistent( - void *ptr, ///< the memory block to check. - const char *file, ///< File of caller - unsigned int lineno, ///< Line number of caller - const char *func ///< Function name of caller -); - -#ifndef SWIG -#define psMemGetPersistent(ptr) \ -p_MemGetPersistent(ptr, __FILE__, __LINE__, __func__); -#endif // ! SWIG - -#endif // DOXYGEN - - -/** 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 - size_t size ///< Size required -); -#else // #ifdef DOXYGEN -#ifdef __GNUC__ -void *p_psRealloc( - void *ptr, ///< Pointer to re-allocate - size_t size, ///< Size required - const char *file, ///< File of caller - unsigned int lineno, ///< Line number of caller - const char *func ///< Function name of caller -) __attribute__((malloc)); -# else // __GNUC__ - void *p_psRealloc( - void *ptr, ///< Pointer to re-allocate - size_t size, ///< Size required + ); + #endif // __GNUC__ + + /// Memory allocation. psAlloc sends file and line number to p_psAlloc. + #ifndef SWIG + #define psAlloc(size) \ + p_psAlloc(__FILE__, __LINE__, __func__, size) + #endif // ! SWIG + #endif // ! DOXYGEN + + + /** Set the deallocator routine + * + * A deallocator routine can optionally be assigned to a memory block to + * ensure that associated memory blocks also get freed, e.g., memory buffers + * referenced within a struct. + * + */ + #ifdef DOXYGEN + void psMemSetDeallocator( + void *ptr, ///< the memory block to operate on + psFreeFunc freeFunc ///< the function to be executed at deallocation + ); + #else // ifdef DOXYGEN + void p_psMemSetDeallocator( const char *file, ///< File of caller unsigned int lineno, ///< Line number of caller - const char *func ///< Function name of caller - ); -#endif // __GNUC__ - -/// Memory re-allocation. psRealloc sends file and line number to p_psRealloc. -#ifndef SWIG -#define psRealloc(ptr, size) \ -p_psRealloc(ptr, size, __FILE__, __LINE__, __func__) -#endif // ! SWIG - -#endif // ! DOXYGEN - - -/** 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 // #ifdef DOXYGEN - -/// Free memory. psFree sends file and line number to p_psFree. -#ifndef SWIG -#define psFree(ptr) \ -p_psMemDecrRefCounter((void **)ptr, __FILE__, __LINE__, __func__); -#endif // ! SWIG - -#endif // ! DOXYGEN - - -/** 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 - */ -#ifdef DOXYGEN -int psMemCheckLeaks( - psMemId id0, ///< don't list blocks with id < id0 - psMemBlock ***array, ///< pointer to array of pointers to leaked blocks, or NULL - FILE * fd, ///< print list of leaks to fd (or NULL) - bool persistence ///< make check across all object even persistent ones -); -#else // ifdef DOXYGEN -int p_psMemCheckLeaks( - psMemId id0, ///< don't list blocks with id < id0 - psMemBlock ***array, ///< pointer to array of pointers to leaked blocks, or NULL - FILE * fd, ///< print list of leaks to fd (or NULL) - bool persistence, ///< make check across all object even persistent ones - const char *file, ///< File of caller - unsigned int lineno, ///< Line number of caller - const char *func ///< Function name of caller -); -#ifndef SWIG -#define psMemCheckLeaks(id0, array, fd, persistence) \ -p_psMemCheckLeaks(id0, array, fd, persistence, __FILE__, __LINE__, __func__) -#endif // ifndef SWIG -#endif // ifdef DOXYGEN - - -/** Check for memory corruption. Scans all currently allocated memory buffers and checks for corruptions, - * i.e., invalid markers that signify a buffer under/overflow. - * - * @return int - * - */ -#ifdef DOXYGEN -int psMemCheckCorruption( - FILE *output, ///< FILE to write corrupted blocks too - bool abort_on_error ///< Abort on detecting corruption? -); -#else // ifdef DOXYGEN -int p_psMemCheckCorruption( - FILE *output, ///< FILE to write corrupted blocks too - bool abort_on_error, ///< Abort on detecting corruption? - const char *file, ///< File of caller - unsigned int lineno, ///< Line number of caller - const char *func ///< Function name of caller -); -#ifndef SWIG -#define psMemCheckCorruption(output, abort_on_error) \ -p_psMemCheckCorruption(output, abort_on_error, __FILE__, __LINE__, __func__) -#endif // ifndef SWIG -#endif // ifdef DOXYGEN - - -/** Return reference counter - * - * @return psReferenceCount - * - */ -#ifdef DOXYGEN - -psReferenceCount psMemGetRefCounter( - void *ptr ///< Pointer to get refCounter for -); - -#else // ifdef DOXYGEN - -psReferenceCount p_psMemGetRefCounter( - void *ptr, ///< Pointer to get refCounter for - const char *file, ///< File of call - unsigned int lineno, ///< Line number of call - const char *func ///< Function name of caller -); - -#ifndef SWIG -#define psMemGetRefCounter(ptr) \ -p_psMemGetRefCounter(ptr, __FILE__, __LINE__, __func__) -#endif // !SWIG - -#endif // !DOXYGEN - - -/** Increment reference counter and return the pointer - * - * @return void * - * - */ -#ifdef DOXYGEN - -void *psMemIncrRefCounter( - void *ptr ///< Pointer to increment refCounter, and return -); -#else // ifdef DOXYGEN - -void *p_psMemIncrRefCounter( - void *ptr, ///< Pointer to increment refCounter, and return - const char *file, ///< File of call - unsigned int lineno, ///< Line number of call - const char *func ///< Function name of caller -); - -#ifndef SWIG -#define psMemIncrRefCounter(ptr) \ -p_psMemIncrRefCounter(ptr, __FILE__, __LINE__, __func__) -#endif // !SWIG - -#endif // !DOXYGEN - - -/** Decrement reference counter and return the pointer - * - * - * @return void * the pointer deremented in refCount, or NULL if pointer is - * fully dereferenced. - */ -#ifdef DOXYGEN - -void *psMemDecrRefCounter( - void *ptr ///< Pointer to decrement refCounter, and return -); - -#else // DOXYGEN - -void *p_psMemDecrRefCounter( - void *ptr, ///< Pointer to decrement refCounter, and return - const char *file, ///< File of call - unsigned int lineno, ///< Line number of call - const char *func ///< Function name of caller -); - -#ifndef SWIG -#define psMemDecrRefCounter(ptr) \ -p_psMemDecrRefCounter(ptr, __FILE__, __LINE__, __func__) -#endif // !SWIG - -#endif // !DOXYGEN - -#if 0 // psMemSetRefCounter -/** Set reference counter and return the pointer - * - * @return void * the pointer with refCount set, or NULL if pointer is - * fully dereferenced. - */ -#ifdef DOXYGEN -void * psMemSetRefCounter( - void * ptr, ///< Pointer to decrement refCounter, and return - psReferenceCount count ///< New reference count -); -#else // DOXYGEN -void * p_psMemSetRefCounter( - void * vptr, ///< Pointer to decrement refCounter, and return - psReferenceCount count, ///< New reference count - const char *file, ///< File of call - psS32 lineno ///< Line number of call -); - -#ifndef SWIG -#define psMemSetRefCounter(vptr, count) p_psMemSetRefCounter(vptr, count, __FILE__, __LINE__) -#endif // !SWIG - -#endif // !DOXYGEN -#endif // psMemSetRefCounter - -/** Set callback for out-of-memory. - * - * If not enough memory is available to satisfy a request by psAlloc or - * psRealloc, these functions attempt to find an alternative solution by - * calling the psMemExhaustedCallback, a function which may be set by the - * programmer in appropriate circumstances, rather than immediately fail. - * The typical use of such a feature may be when a program needs a large - * chunk of memory to do an operation, but the exact size is not critical. - * This feature gives the programmer the opportunity to make a smaller - * request and try again, limiting the size of the operating buffer. - * - * @return psMemExhaustedCallback old psMemExhaustedCallback function - */ -psMemExhaustedCallback psMemExhaustedCallbackSet( - psMemExhaustedCallback func ///< Function to run at memory exhaustion -); - -/** Set call back for when a particular memory block is allocated - * - * A private variable, p_psMemAllocID, can be used to trace the allocation - * and freeing of specific memory blocks. If p_psMemAllocID is set and a - * memory block with that ID is allocated, psMemAllocCallback is called - * just before memory is returned to the calling function. - * - * @return psMemAllocCallback old psMemAllocCallback function - */ -psMemAllocCallback psMemAllocCallbackSet( - psMemAllocCallback func ///< Function to run at memory allocation of specific mem block -); - -/** Set call back for when a particular memory block is freed - * - * A private variable, p_psMemFreeID, can be used to trace the freeing of - * specific memory blocks. If p_psMemFreeID is set and the memory block with - * the ID is about to be freed, the psMemFreeCallback callback is called just - * before the memory block is freed. - * - * @return psMemFreeCallback old psMemFreeCallback function - */ -psMemFreeCallback psMemFreeCallbackSet( - psMemFreeCallback func ///< Function to run at memory free of specific mem block -); - -/** get next memory ID - * - * @return psMemId the next memory ID to be used - */ -psMemId psMemGetId(void); - -/** get the last memory ID used - * - * @return psMemId the last memory ID used - */ -psMemId psMemGetLastId(void); - -/** set p_psMemAllocID to specific id - * - * A private variable, p_psMemAllocID, can be used to trace the allocation - * and freeing of specific memory blocks. If p_psMemAllocID is set and a - * memory block with that ID is allocated, psMemAllocCallback is called - * just before memory is returned to the calling function. - * - * @return psMemId - * - * @see psMemAllocCallbackSet - */ -psMemId psMemAllocCallbackSetID( - psMemId id ///< ID to set -); - -/** set p_psMemFreeID to id - * - * A private variable, p_psMemFreeID, can be used to trace the freeing of - * specific memory blocks. If p_psMemFreeID is set and the memory block with - * the ID is about to be freed, the psMemFreeCallback callback is called just - * before the memory block is freed. - * - * @return psMemId the old p_psMemFreeID - * - * @see psMemFreeCallbackSet - */ -psMemId psMemFreeCallbackSetID( - psMemId id ///< ID to set -); - - -/** return statistics on memory usage - * - * @return the total amount of memory owned by psLib; if non-NULL also provide - * a breakdown into allocated and allocated-and-persistent - */ -size_t psMemStats(const bool print, ///< print details as they're found? - size_t *allocated, ///< memory that's currently allocated (but not persistent) - size_t *persistent); ///< persistent memory that's currently allocated - -/** print detailed information about a psMemBlock - * - * This function prints a detailed description of a psMemBlock to output. - * - * @return the return status of fprintf() - */ -int psMemBlockPrint( - FILE *output, ///< FILE to write information too - const psMemBlock *memBlock ///< psMemBlock to be examined -); - - -/// @} end of SysUtils - -#ifndef DOXYGEN - -/* - * Ensure that any program using malloc/realloc/free will fail to compile - */ -#ifndef PS_ALLOW_MALLOC -#ifdef __GNUC__ -#pragma GCC poison malloc realloc calloc free -#else // __GNUC__ -#define malloc(S) _Pragma("error Use of malloc is not allowed. Use psAlloc instead.") -#define realloc(P,S) _Pragma("error Use of realloc is not allowed. Use psRealloc instead.") -#define calloc(S) _Pragma("error Use of calloc is not allowed. Use psAlloc instead.") -#define free(P) _Pragma("error Use of free is not allowed. Use psFree instead.") -#endif // ! __GNUC__ -#endif // #ifndef PS_ALLOW_MALLOC - -#endif // #ifndef DOXYGEN -#endif // #ifndef PS_MEMORY_H + const char *func, ///< Function name of caller + void *ptr, ///< the memory block to operate on + psFreeFunc freeFunc ///< the function to be executed at deallocation + ); + #ifndef SWIG + #define psMemSetDeallocator(ptr, freeFunc) \ + p_psMemSetDeallocator(__FILE__, __LINE__, __func__, ptr, freeFunc) + #endif // ! SWIG + #endif // ifdef DOXYGEN + + + /** Get the deallocator routine + * + * This function returns the deallocator for a memory block. A deallocator + * routine can optionally be assigned to a memory block to ensure that + * associated memory blocks also get freed, e.g., memory buffers referenced + * within a struct. + * + * @return psFreeFunc the routine to be called at deallocation. + */ + #ifdef DOXYGEN + psFreeFunc psMemGetDeallocator( + void *ptr ///< the memory block + ); + #else // ifdef DOXYGEN + psFreeFunc p_psMemGetDeallocator( + const char *file, ///< File of caller + unsigned int lineno, ///< Line number of caller + const char *func, ///< Function name of caller + void *ptr ///< the memory block + ); + #ifndef SWIG + #define psMemGetDeallocator(ptr) \ + p_psMemGetDeallocator(__FILE__, __LINE__, __func__, ptr) + #endif // ! SWIG + #endif // ifdef DOXYGEN + + + /** Activate or Deactivate thread safety and mutex locking in the memory + * management. + * + * psMemThreadSafety shall turn on thread safety in the memory management + * functions if safe is true, and deactivate all mutex locking in the memory + * management functions if safe is false. The function shall return the + * previous value of the thread safety. Note that the default behaviour of + * the library shall be for the locking to be performed. + * + * @return bool: The previous value of the thread safety. + */ + bool psMemSetThreadSafety( + bool safe ///< boolean for turning on/off thread safety + ); + + /** Get the current state of thread safety and mutex locking in the memory + * management. + * + * psMemGetThreadSafety shall return the current state of thread safety in the + * memory management system. + * + * @return bool: The current state of thread safety. + */ + bool psMemGetThreadSafety(void); + + + /** Set the memory as persistent so that it is ignored when detecting memory + * leaks. + * + * Used to mark a memory block as persistent data within the library, + * i.e., non user-level data used to hold psLib's state or cache data. Such + * examples of this class of memory is psTrace's trace-levels and dynamic + * error codes. + * + * Memory marked as persistent is excluded from memory leak checks. + * + */ + #ifdef DOXYGEN + void psMemSetPersistent( + void *ptr, ///< the memory block to operate on + bool value, ///< true if memory is persistent, otherwise false + ); + #else // #ifdef DOXYGEN + void p_psMemSetPersistent( + const char *file, ///< File of caller + unsigned int lineno, ///< Line number of caller + const char *func, ///< Function name of caller + void *ptr, ///< the memory block to operate on + bool value ///< true if memory is persistent, otherwise false + ); + #ifndef SWIG + #define psMemSetPersistent(ptr, value) \ + p_psMemSetPersistent(__FILE__, __LINE__, __func__, ptr, value) + #endif // ! SWIG + #endif // DOXYGEN + + + /** Set whether allocated memory is persistent + * + * Set whether allocated memory is persistent. The defeault is false. + * + * @return bool: The previous value of whether all allocated memory is + * persistent + */ + bool p_psMemAllocatePersistent(bool is_persistent); ///< Should all memory allocated be persistent? + + + /** Get the memory's persistent flag. + * + * Checks if a memory block has been marked as persistent by + * p_psMemSetPresistent. + * + * Memory marked as persistent is excluded from memory leak checks. + * + * @return bool true if memory is marked persistent, otherwise false. + */ + #ifdef DOXYGEN + bool psMemGetPersistent( + void *ptr, ///< the memory block to check. + ); + #else // ifdef DOXYGEN + bool p_psMemGetPersistent( + const char *file, ///< File of caller + unsigned int lineno, ///< Line number of caller + const char *func, ///< Function name of caller + void *ptr ///< the memory block to check. + ); + #ifndef SWIG + #define psMemGetPersistent(ptr) \ + p_psMemGetPersistent(__FILE__, __LINE__, __func__, ptr) + #endif // ! SWIG + #endif // DOXYGEN + + + /** 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 + size_t size ///< Size required + ); + #else // #ifdef DOXYGEN + void *p_psRealloc( + const char *file, ///< File of caller + unsigned int lineno, ///< Line number of caller + const char *func, ///< Function name of caller + void *ptr, ///< Pointer to re-allocate + size_t size ///< Size required + #ifdef __GNUC__ + ) __attribute__((malloc)); + # else // __GNUC__ + ); + #endif // __GNUC__ + #ifndef SWIG + #define psRealloc(ptr, size) \ + p_psRealloc(__FILE__, __LINE__, __func__, ptr, size) + #endif // ! SWIG + #endif // ! DOXYGEN + + + /** 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 // #ifdef DOXYGEN + /// Free memory. psFree sends file and line number to p_psFree. + #ifndef SWIG + #define psFree(ptr) \ + psMemDecrRefCounter(ptr) + #endif // ! SWIG + #endif // ! DOXYGEN + + + /** 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 + */ + #ifdef DOXYGEN + int psMemCheckLeaks( + psMemId id0, ///< don't list blocks with id < id0 + psMemBlock ***array, ///< pointer to array of pointers to leaked blocks, or NULL + FILE * fd, ///< print list of leaks to fd (or NULL) + bool persistence ///< make check across all object even persistent ones + ); + #else // ifdef DOXYGEN + int p_psMemCheckLeaks( + const char *file, ///< File of caller + unsigned int lineno, ///< Line number of caller + const char *func, ///< Function name of caller + psMemId id0, ///< don't list blocks with id < id0 + psMemBlock ***array, ///< pointer to array of pointers to leaked blocks, or NULL + FILE * fd, ///< print list of leaks to fd (or NULL) + bool persistence ///< make check across all object even persistent ones + ); + #ifndef SWIG + #define psMemCheckLeaks(id0, array, fd, persistence) \ + p_psMemCheckLeaks(__FILE__, __LINE__, __func__, id0, array, fd, persistence) + #endif // ifndef SWIG + #endif // ifdef DOXYGEN + + + /** Check for memory corruption. Scans all currently allocated memory buffers + * and checks for corruptions, i.e., invalid markers that signify a buffer + * under/overflow. + * + * @return int + * + */ + #ifdef DOXYGEN + int psMemCheckCorruption( + FILE *output, ///< FILE to write corrupted blocks too + bool abort_on_error ///< Abort on detecting corruption? + ); + #else // ifdef DOXYGEN + int p_psMemCheckCorruption( + const char *file, ///< File of caller + unsigned int lineno, ///< Line number of caller + const char *func, ///< Function name of caller + FILE *output, ///< FILE to write corrupted blocks too + bool abort_on_error ///< Abort on detecting corruption? + ); + #ifndef SWIG + #define psMemCheckCorruption(output, abort_on_error) \ + p_psMemCheckCorruption(__FILE__, __LINE__, __func__, output, abort_on_error) + #endif // ifndef SWIG + #endif // ifdef DOXYGEN + + + /** Return reference counter + * + * @return psReferenceCount + * + */ + #ifdef DOXYGEN + psReferenceCount psMemGetRefCounter( + void *ptr ///< Pointer to get refCounter for + ); + + #else // ifdef DOXYGEN + psReferenceCount p_psMemGetRefCounter( + const char *file, ///< File of call + unsigned int lineno, ///< Line number of call + const char *func, ///< Function name of caller + void *ptr ///< Pointer to get refCounter for + ); + #ifndef SWIG + #define psMemGetRefCounter(ptr) \ + p_psMemGetRefCounter(__FILE__, __LINE__, __func__, ptr) + #endif // !SWIG + #endif // !DOXYGEN + + + /** Increment reference counter and return the pointer + * + * @return void * + * + */ + #ifdef DOXYGEN + void *psMemIncrRefCounter( + void *ptr ///< Pointer to increment refCounter, and return + ); + #else // ifdef DOXYGEN + void *p_psMemIncrRefCounter( + const char *file, ///< File of call + unsigned int lineno, ///< Line number of call + const char *func, ///< Function name of caller + void *ptr ///< Pointer to increment refCounter, and return + ); + #ifndef SWIG + #define psMemIncrRefCounter(ptr) \ + p_psMemIncrRefCounter(__FILE__, __LINE__, __func__, ptr) + #endif // !SWIG + #endif // !DOXYGEN + + + /** Decrement reference counter and return the pointer + * + * + * @return void * the pointer deremented in refCount, or NULL if pointer is + * fully dereferenced. + */ + #ifdef DOXYGEN + void *psMemDecrRefCounter( + void *ptr ///< Pointer to decrement refCounter, and return + ); + #else // DOXYGEN + void *p_psMemDecrRefCounter( + const char *file, ///< File of call + unsigned int lineno, ///< Line number of call + const char *func, ///< Function name of caller + void *ptr ///< Pointer to decrement refCounter, and return + ); + #ifndef SWIG + #define psMemDecrRefCounter(ptr) \ + p_psMemDecrRefCounter(__FILE__, __LINE__, __func__, ptr) + #endif // !SWIG + #endif // !DOXYGEN + + + #if 0 // psMemSetRefCounter + /** Set reference counter and return the pointer + * + * @return void * the pointer with refCount set, or NULL if pointer is + * fully dereferenced. + */ + #ifdef DOXYGEN + void * psMemSetRefCounter( + void * ptr, ///< Pointer to decrement refCounter, and return + psReferenceCount count ///< New reference count + ); + #else // DOXYGEN + void * p_psMemSetRefCounter( + void * vptr, ///< Pointer to decrement refCounter, and return + psReferenceCount count, ///< New reference count + const char *file, ///< File of call + psS32 lineno ///< Line number of call + ); + + #ifndef SWIG + #define psMemSetRefCounter(vptr, count) p_psMemSetRefCounter(vptr, count, __FILE__, __LINE__) + #endif // !SWIG + + #endif // !DOXYGEN + #endif // psMemSetRefCounter + + /** Set callback for out-of-memory. + * + * If not enough memory is available to satisfy a request by psAlloc or + * psRealloc, these functions attempt to find an alternative solution by + * calling the psMemExhaustedCallback, a function which may be set by the + * programmer in appropriate circumstances, rather than immediately fail. + * The typical use of such a feature may be when a program needs a large + * chunk of memory to do an operation, but the exact size is not critical. + * This feature gives the programmer the opportunity to make a smaller + * request and try again, limiting the size of the operating buffer. + * + * @return psMemExhaustedCallback old psMemExhaustedCallback function + */ + psMemExhaustedCallback psMemExhaustedCallbackSet( + psMemExhaustedCallback func ///< Function to run at memory exhaustion + ); + + + /** Set call back for when a particular memory block is allocated + * + * A private variable, p_psMemAllocID, can be used to trace the allocation + * and freeing of specific memory blocks. If p_psMemAllocID is set and a + * memory block with that ID is allocated, psMemAllocCallback is called + * just before memory is returned to the calling function. + * + * @return psMemAllocCallback old psMemAllocCallback function + */ + psMemAllocCallback psMemAllocCallbackSet( + psMemAllocCallback func ///< Function to run at memory allocation of specific mem block + ); + + + /** Set call back for when a particular memory block is freed + * + * A private variable, p_psMemFreeID, can be used to trace the freeing of + * specific memory blocks. If p_psMemFreeID is set and the memory block with + * the ID is about to be freed, the psMemFreeCallback callback is called just + * before the memory block is freed. + * + * @return psMemFreeCallback old psMemFreeCallback function + */ + psMemFreeCallback psMemFreeCallbackSet( + psMemFreeCallback func ///< Function to run at memory free of specific mem block + ); + + + /** get next memory ID + * + * @return psMemId the next memory ID to be used + */ + psMemId psMemGetId(void); + + + /** get the last memory ID used + * + * @return psMemId the last memory ID used + */ + psMemId psMemGetLastId(void); + + + /** set p_psMemAllocID to specific id + * + * A private variable, p_psMemAllocID, can be used to trace the allocation + * and freeing of specific memory blocks. If p_psMemAllocID is set and a + * memory block with that ID is allocated, psMemAllocCallback is called + * just before memory is returned to the calling function. + * + * @return psMemId + * + * @see psMemAllocCallbackSet + */ + psMemId psMemAllocCallbackSetID( + psMemId id ///< ID to set + ); + + + /** set p_psMemFreeID to id + * + * A private variable, p_psMemFreeID, can be used to trace the freeing of + * specific memory blocks. If p_psMemFreeID is set and the memory block with + * the ID is about to be freed, the psMemFreeCallback callback is called just + * before the memory block is freed. + * + * @return psMemId the old p_psMemFreeID + * + * @see psMemFreeCallbackSet + */ + psMemId psMemFreeCallbackSetID( + psMemId id ///< ID to set + ); + + + /** return statistics on memory usage + * + * @return the total amount of memory owned by psLib; if non-NULL also provide + * a breakdown into allocated and allocated-and-persistent + */ + size_t psMemStats(const bool print, ///< print details as they're found? + size_t *allocated, ///< memory that's currently allocated (but not persistent) + size_t *persistent); ///< persistent memory that's currently allocated + + /** print detailed information about a psMemBlock + * + * This function prints a detailed description of a psMemBlock to output. + * + * @return the return status of fprintf() + */ + int psMemBlockPrint( + FILE *output, ///< FILE to write information too + const psMemBlock *memBlock ///< psMemBlock to be examined + ); + + + /// @} end of SysUtils + + #ifndef DOXYGEN + + /* + * Ensure that any program using malloc/realloc/free will fail to compile + */ + #ifndef PS_ALLOW_MALLOC + #ifdef __GNUC__ + #pragma GCC poison malloc realloc calloc free + #else // __GNUC__ + #define malloc(S) _Pragma("error Use of malloc is not allowed. Use psAlloc instead.") + #define realloc(P,S) _Pragma("error Use of realloc is not allowed. Use psRealloc instead.") + #define calloc(S) _Pragma("error Use of calloc is not allowed. Use psAlloc instead.") + #define free(P) _Pragma("error Use of free is not allowed. Use psFree instead.") + #endif // ! __GNUC__ + #endif // #ifndef PS_ALLOW_MALLOC + + #endif // #ifndef DOXYGEN + #endif // #ifndef PS_MEMORY_H