Index: trunk/psLib/src/sys/psMemory.h =================================================================== --- trunk/psLib/src/sys/psMemory.h (revision 1441) +++ trunk/psLib/src/sys/psMemory.h (revision 1448) @@ -1,5 +1,2 @@ -#if !defined(PS_MEMORY_H) -#define PS_MEMORY_H - /** @file psMemory.h * @@ -15,9 +12,12 @@ * @ingroup MemoryManagement * - * @version $Revision: 1.27 $ $Name: not supported by cvs2svn $ - * @date $Date: 2004-08-09 23:40:55 $ + * @version $Revision: 1.28 $ $Name: not supported by cvs2svn $ + * @date $Date: 2004-08-10 01:55:34 $ * * Copyright 2004 Maui High Performance Computing Center, University of Hawaii */ + +#if !defined(PS_MEMORY_H) +#define PS_MEMORY_H #include // needed for FILE @@ -63,15 +63,15 @@ typedef struct psMemBlock { - const void *startblock; ///< initialised to p_psMEMMAGIC - struct psMemBlock* previousBlock; ///< previous block in allocation list - struct psMemBlock* nextBlock; ///< next block allocation list - psFreeFcn freeFcn; ///< deallocator. If NULL, use generic deallocation. - 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 - pthread_mutex_t refCounterMutex; ///< mutex to ensure exclusive access to reference counter - psReferenceCount refCounter; ///< how many times pointer is referenced - const void *endblock; ///< initialised to p_psMEMMAGIC + const void *startblock; ///< initialised to p_psMEMMAGIC + struct psMemBlock* previousBlock; ///< previous block in allocation list + struct psMemBlock* nextBlock; ///< next block allocation list + psFreeFcn freeFcn; ///< deallocator. If NULL, use generic deallocation. + 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 + pthread_mutex_t refCounterMutex; ///< mutex to ensure exclusive access to reference counter + psReferenceCount refCounter; ///< how many times pointer is referenced + const void *endblock; ///< initialised to p_psMEMMAGIC } psMemBlock; @@ -82,6 +82,7 @@ * @ingroup memCallback */ -typedef psMemoryId(*psMemAllocateCallback) (const psMemBlock* ptr ///< the psMemBlock just allocated - ); +typedef psMemoryId(*psMemAllocateCallback) ( + const psMemBlock* ptr ///< the psMemBlock just allocated +); /** prototype of memory free callback used by memory functions @@ -90,6 +91,7 @@ * @ingroup memCallback */ -typedef psMemoryId(*psMemFreeCallback) (const psMemBlock* ptr ///< the psMemBlock being freed - ); +typedef psMemoryId(*psMemFreeCallback) ( + const psMemBlock* ptr ///< the psMemBlock being freed +); /** prototype of a callback used in error conditions @@ -100,9 +102,9 @@ * @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 - ); +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 @@ -114,6 +116,7 @@ * @ingroup memCallback */ -typedef void *(*psMemExhaustedCallback) (size_t size // < the size of buffer required - ); +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. @@ -145,14 +148,16 @@ */ #ifdef DOXYGEN -void *psRealloc(void *ptr ///< Pointer to re-allocate - size_t size, ///< Size required - ); -#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 - ); +void *psRealloc( + void *ptr ///< Pointer to re-allocate + size_t size, ///< Size required +); +#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. @@ -166,12 +171,14 @@ */ #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 - ); +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. @@ -194,8 +201,9 @@ * @ingroup memTracing */ -int psMemCheckLeaks(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) - ); +int psMemCheckLeaks( + 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. Scans all currently allocated memory buffers and checks for corruptions, @@ -204,6 +212,7 @@ * @ingroup memTracing */ -int psMemCheckCorruption(bool abort_on_error ///< Abort on detecting corruption? - ); +int psMemCheckCorruption( + bool abort_on_error ///< Abort on detecting corruption? +); /** Return reference counter @@ -211,6 +220,7 @@ * @ingroup memRefCount */ -psReferenceCount psMemGetRefCounter(void *vptr ///< Pointer to get refCounter for - ); +psReferenceCount psMemGetRefCounter( + void *vptr ///< Pointer to get refCounter for +); /** Increment reference counter and return the pointer @@ -219,12 +229,14 @@ */ #ifdef DOXYGEN -void *psMemIncrRefCounter(void *vptr ///< Pointer to increment refCounter, and return - ); -#else - -void *p_psMemIncrRefCounter(void *vptr, ///< Pointer to increment refCounter, and return - const char *file, ///< File of call - int lineno ///< Line number of call - ); +void *psMemIncrRefCounter( + void *vptr ///< Pointer to increment refCounter, and return +); +#else + +void *p_psMemIncrRefCounter( + void *vptr, ///< Pointer to increment refCounter, and return + const char *file, ///< File of call + int lineno ///< Line number of call +); #define psMemIncrRefCounter(vptr) p_psMemIncrRefCounter(vptr, __FILE__, __LINE__) @@ -234,64 +246,127 @@ * * @ingroup memRefCount - */ -#ifdef DOXYGEN -void *psMemDecrRefCounter(void *vptr ///< Pointer to decrement refCounter, and return - ); -#else - -void *p_psMemDecrRefCounter(void *vptr, ///< Pointer to decrement refCounter, and return - const char *file, ///< File of call - int lineno ///< Line number of call - ); + * + * @return void* the pointer deremented in refCount, or NULL if pointer is + * fully dereferenced. + */ +#ifdef DOXYGEN +void* psMemDecrRefCounter( + void* vptr ///< Pointer to decrement refCounter, and return +); +#else + +void *p_psMemDecrRefCounter( + void *vptr, ///< Pointer to decrement refCounter, and return + const char *file, ///< File of call + int lineno ///< Line number of call +); #define psMemDecrRefCounter(vptr) p_psMemDecrRefCounter(vptr, __FILE__, __LINE__) #endif -/** Set callback for problems - * @ingroup memCallback - */ -psMemProblemCallback psMemProblemCallbackSet(psMemProblemCallback func ///< Function to run - ); - -/** Set callback for out-of-memory - * - * @ingroup memCallback - */ -psMemExhaustedCallback psMemExhaustedCallbackSet(psMemExhaustedCallback func ///< Function to run - ); +/** Set callback for problems. + * + * At various occasions, the memory manager can check the state of the memory + * stack. If any of these checks discover that the memory stack is corrupted, + * the psMemProblemCallback is called. + + * @ingroup memCallback + * + * @return psMemProblemCallback old psMemProblemCallback function + */ +psMemProblemCallback psMemProblemCallbackSet( + psMemProblemCallback func ///< Function to run at memory problem detection +); + +/** 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. + * + * @ingroup memCallback + * + * @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 * - * @ingroup memCallback - */ -psMemAllocateCallback psMemAllocateCallbackSet(psMemAllocateCallback func ///< Function to run - ); + * A private variable, p_psMemAllocateID, can be used to trace the allocation + * and freeing of specific memory blocks. If p_psMemAllocateID is set and a + * memory block with that ID is allocated, psMemAllocateCallback is called + * just before memory is returned to the calling function. + * + * @ingroup memCallback + * + * @return psMemAllocateCallback old psMemAllocateCallback function + */ +psMemAllocateCallback psMemAllocateCallbackSet( + psMemAllocateCallback func ///< Function to run at memory allocation of specific mem block +); /** Set call back for when a particular memory block is freed * - * @ingroup memCallback - */ -psMemFreeCallback psMemFreeCallbackSet(psMemFreeCallback func ///< Function to run - ); + * 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. + * + * @ingroup memCallback + * + * @return psMemFreeCallback old psMemFreeCallback function + */ +psMemFreeCallback psMemFreeCallbackSet( + psMemFreeCallback func ///< Function to run at memory free of specific mem block +); /** get next memory ID * * @ingroup memCallback + * + * @return psMemoryId the next memory ID to be used */ psMemoryId psMemGetId(void); -/** set p_psMemAllocateID to id - * - * @ingroup memCallback - */ -psMemoryId psMemAllocateCallbackSetID(psMemoryId id ///< ID to set - ); +/** set p_psMemAllocateID to specific id + * + * A private variable, p_psMemAllocateID, can be used to trace the allocation + * and freeing of specific memory blocks. If p_psMemAllocateID is set and a + * memory block with that ID is allocated, psMemAllocateCallback is called + * just before memory is returned to the calling function. + * + * @ingroup memCallback + * + * @return psMemoryId + * + * @see psMemAllocateCallbackSet + */ +psMemoryId psMemAllocateCallbackSetID( + psMemoryId id ///< ID to set +); /** set p_psMemFreeID to id * - * @ingroup memCallback - */ -psMemoryId psMemFreeCallbackSetID(psMemoryId id ///< ID to set - ); + * 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. + * + * @ingroup memCallback + * + * @return psMemoryId the old p_psMemFreeID + * + * @see psMemFreeCallbackSet + */ +psMemoryId psMemFreeCallbackSetID( + psMemoryId id ///< ID to set +); //@} End of Memory Management Functions @@ -306,12 +381,12 @@ #pragma GCC poison malloc realloc calloc free #else -# 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 -# endif - -# endif +#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 +#endif + +#endif // doxygen skip