Changeset 247 for trunk/archive/pslib/include/psMemory.h

Timestamp:

Mar 15, 2004, 3:20:03 PM (22 years ago)

Author:

eugene

Message:

added Doxygen \file and \defgroup entries
some basic reorganization

File:

• trunk/archive/pslib/include/psMemory.h (modified) (6 diffs)

trunk/archive/pslib/include/psMemory.h

@@ -1 +1 @@
 #if !defined(PS_MEMORY_H)
 #define PS_MEMORY_H
-#include <stdio.h>
-/**
- * Book-keeping data for storage allocator.
- *
- * N.b. sizeof(psMemBlock) must be chosen such that if ptr is a pointer
- * returned by malloc, then ((char *)ptr + sizeof(psMemBlock)) is properly
- * aligned for all storage types.
+
+/** \file psMemory.h
+ *  \brief Memory alloc/free routines
+ *  \ingroup SystemGroup
+ */
+
+/** Book-keeping data for storage allocator.
+ *  N.b. sizeof(psMemBlock) must be chosen such that if ptr is a pointer
+ *  returned by malloc, then ((char *)ptr + sizeof(psMemBlock)) is properly
+ *  aligned for all storage types.
  */
 typedef struct {
@@ -18 +21 @@
 } psMemBlock;
 
-/** */
+/** prototype of a basic callback used by memory functions */
 typedef int (*psMemCallback)(const psMemBlock *ptr);
-typedef void (*psMemProblemCallback)(const psMemBlock *ptr,
-                                     const char *file, int lineno);
+
+/** prototype of a callback used in error conditions */
+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);
 
 /*****************************************************************************/
 
-/** Fake for p_psAlloc */
-void *psAlloc(size_t size               //!< Size required
-    );
-/** Fake for p_psRealloc */
-void *psRealloc(void *ptr,              //!< Pointer to re-allocate
-                size_t size             //!< Size required
-    );
-/** Fake for p_psFree */
-void psFree(void *ptr                   //!< Pointer to free
-    );
-
-/** Memory allocation */
+/** Memory allocation. Underlying private function called by macro psAlloc. */
 void *p_psAlloc(size_t size,            //!< Size required
                 const char *file,       //!< File of call
@@ -43 +38 @@
     );
 
-/** Memory re-allocation */
+/** Memory re-allocation.  Underlying private function called by macro psRealloc. */
 void *p_psRealloc(void *ptr,            //!< Pointer to re-allocate
                   size_t size,          //!< Size required
@@ -50 +45 @@
     );
 
-/** Free memory */
+/** Free memory.  Underlying private function called by macro psFree. */
 void p_psFree(void *ptr,                //!< Pointer to free
               const char *file,         //!< File of call
@@ -56 +51 @@
     );
 
-/** psAlloc sends file and line number to p_psAlloc */
+/** Memory allocation. psAlloc sends file and line number to p_psAlloc. */
 #define psAlloc(size) p_psAlloc(size, __FILE__, __LINE__)
-/** psRealloc sends file and line number to p_psRealloc */
+
+/** Memory re-allocation.  psRealloc sends file and line number to p_psRealloc. */
 #define psRealloc(ptr, size) p_psRealloc(ptr, size, __FILE__, __LINE__)
-/** psFree sends file and line number to p_psFree */
+
+/** Free memory.  psFree sends file and line number to p_psFree. */
 #define psFree(size) p_psFree(size, __FILE__, __LINE__)
 
-/*
- * Ensure that any program using malloc/realloc/free will fail to compile
- */
+/** prevent the use of 'malloc'. malloc is re-defined to throw an error in the C preprocessor */
 #define malloc(S) for
+
+/** prevent the use of 'realloc'. realloc is re-defined to throw an error in the C preprocessor */
 #define realloc(P,S) for
+
+/** prevent the use of 'free'. free is re-defined to throw an error in the C preprocessor */
 #define free(P) for
 
@@ -112 +111 @@
 long psMemSetAllocateID(long id);       //!< set p_psMemAllocateID to id
 long psMemSetFreeID(long id);           //!< set p_psMemFreeID to id
+
 #endif