- source code documented
authorJan Hutter <jhutter@hsr.ch>
Thu, 10 Nov 2005 08:16:47 +0000 (08:16 -0000)
committerJan Hutter <jhutter@hsr.ch>
Thu, 10 Nov 2005 08:16:47 +0000 (08:16 -0000)
Source/charon/allocator.c
Source/charon/allocator.h

index bf35ad6..2fe5fc6 100644 (file)
 
 #ifdef LEAK_DETECTIVE
 
+/**
+ * Header of each allocated memory area
+ * 
+ * Used to detect memory leaks
+ */
 typedef union memory_hdr_u memory_hdr_t;
 
 union memory_hdr_u {
     struct {
+       /**
+        * Filename withing memory was allocated
+        */
        const char *filename;
+       /**
+        * Line number in given file
+        */
        size_t line;
+       /**
+        * Allocated memory size. Needed for reallocation
+        */
        size_t size_of_memory;
+       /**
+        * Link to the previous and next memory area
+        */
        memory_hdr_t *older, *newer;
     } info;    /* info */
-    unsigned long junk;        /* force maximal alignment */
+    /**
+     * force maximal alignment ?
+     */
+    unsigned long junk;        
 };
 
 /**
- * private allocator_t object
+ * @brief Private allocator_t object.
+ * 
+ * Contains private variables of allocator_t object.
  */
 typedef struct private_allocator_s private_allocator_t;
 
 struct private_allocator_s
 {
        /**
-        * public part of an allocator_t object
+        * Public part of an allocator_t object.
         */
        allocator_t public;
        
        /**
-        * global list of allocations
+        * Global list of allocations
         * 
-        * thread-save through mutex
+        * Thread-save through mutex
         */
        memory_hdr_t *allocations;
 
        /**
-        * Mutex to ensure, all functions are thread-save
+        * Mutex used to make sure, all functions are thread-save
         */
        pthread_mutex_t mutex;
-       
 };
 
 
 /**
- * implements allocator_t's function allocate
+ * Implements allocator_t's function allocate. 
+ * See #allocator_s.allocate for description.
  */
 static void * allocate(allocator_t *allocator,size_t bytes, char * file,int line)
 {
@@ -108,8 +130,9 @@ static void * allocate(allocator_t *allocator,size_t bytes, char * file,int line
     return (allocated_memory+1);
 }
 
-/**
- * implements allocator_t's function free_pointer
+/*
+ * Implements allocator_t's free_pointer allocate. 
+ * See #allocator_s.free_pointer for description.
  */
 static void free_pointer(allocator_t *allocator, void * pointer)
 {
@@ -142,8 +165,9 @@ static void free_pointer(allocator_t *allocator, void * pointer)
     free(allocated_memory);
 }
 
-/**
- * implements allocator_t's function reallocate
+/*
+ * Implements allocator_t's reallocate allocate. 
+ * See #allocator_s.reallocate for description.
  */
 static void * reallocate(allocator_t *allocator, void * old, size_t bytes, char * file,int line)
 {
@@ -171,8 +195,9 @@ static void * reallocate(allocator_t *allocator, void * old, size_t bytes, char
        return new_space;
 }
 
-/**
- * implements allocator_t's function report_memory_leaks
+/*
+ * Implements allocator_t's report_memory_leaks allocate. 
+ * See #allocator_s.report_memory_leaks for description.
  */
 static void allocator_report_memory_leaks(allocator_t *allocator)
 {
@@ -201,6 +226,11 @@ static void allocator_report_memory_leaks(allocator_t *allocator)
     pthread_mutex_unlock( &(this->mutex));
 }
 
+/** 
+ * Only initiation of allocator object.
+ * 
+ * All allocation macros use this object.
+ */
 static private_allocator_t allocator = {
        public: {allocate: allocate,
                         free_pointer: free_pointer,
@@ -210,7 +240,6 @@ static private_allocator_t allocator = {
        mutex: PTHREAD_MUTEX_INITIALIZER
 };
 
-//allocator.public.allocate = (void *) (allocator_t *,size_t, char *,int) allocate;
 
 
 allocator_t *global_allocator = &(allocator.public);
index bd719f2..20a7ab1 100644 (file)
@@ -1,5 +1,5 @@
 /**
- * @file allocator.c
+ * @file allocator.h
  * 
  * @brief Memory allocation with LEAK_DETECTION support
  * 
 
 
 /**
- * Function to allocate a special type
+ * Macro to allocate a special type
  * 
- * @param thing object on it a sizeof is performed
+ * @param thing        object on which a sizeof is performed
+ * @return 
+ *                     - Pointer to allocated memory if successful
+ *                     - NULL otherwise
  */
 #define allocator_alloc_thing(thing) (allocator_alloc(sizeof(thing)))
 
 #ifdef LEAK_DETECTIVE
 
+       /**
+        * @brief Allocater object use to detect memory leaks.
+        * 
+        */
        typedef struct allocator_s allocator_t;
-       
+
        struct allocator_s {
        
                /**
                 * Allocates memory with LEAK_DETECTION and 
-                * returns an empty data area filled with zeros
+                * returns an empty data area filled with zeros.
                 * 
-                * @warning use this function not directly, only with assigned macros 
-                * allocator_alloc and allocator_alloc_thing
+                * @warning             Use this function not directly, only with assigned macros 
+                *                              #allocator_alloc and #allocator_alloc_thing.
                 * 
-                * @param this allocator_t object
+                * @param this  allocator_t object
                 * @param bytes number of bytes to allocate
-                * @param file filename from which the memory is allocated
-                * @param line line number in specific file
-                * @return allocated memory area
+                * @param file  filename from which the memory is allocated
+                * @param line  line number in specific file
+                * @return              
+                *                              - pointer to allocated memory area if successful
+                *                              - NULL otherwise
                 */ 
                void * (*allocate) (allocator_t *this,size_t bytes, char * file,int line);
        
                 * Reallocates memory with LEAK_DETECTION and 
                 * returns an empty data area filled with zeros
                 * 
-                * @warning use this function not directly, only with assigned macro 
-                * allocator_realloc
+                * @warning             Use this function not directly, only with assigned macro 
+                *                              #allocator_realloc
                 * 
-                * @param this allocator_t object
-                * @param old pointer to the old data area
+                * @param this  allocator_t object
+                * @param old   pointer to the old data area
                 * @param bytes number of bytes to allocate
-                * @param file filename from which the memory is allocated
-                * @param line line number in specific file
-                * @return reallocated memory area
+                * @param file  filename from which the memory is allocated
+                * @param line  line number in specific file
+                * @return              - pointer to reallocated memory area if successful
+                *                              - NULL otherwise
                 */ 
                void * (*reallocate) (allocator_t *this,void * old, size_t bytes, char * file, int line);
                /**
                 * Frees memory with LEAK_DETECTION
                 * 
-                * @warning use this function not directly, only with assigned macro 
-                * allocator_free
+                * @warning             Use this function not directly, only with assigned macro 
+                *                              #allocator_free
                 * 
-                * @param this allocator_t object
-                * @param pointer pointer to the data area to free
+                * @param this          allocator_t object
+                * @param pointer       pointer to the data area to free
                 */ 
                void (*free_pointer) (allocator_t *this,void * pointer);
                
                /**
                 * Report memory leaks to stderr
                 *
-                * @warning use this function not directly, only with assigned macro 
-                * report_memory_leaks
+                * @warning             Use this function not directly, only with assigned macro 
+                *                              #report_memory_leaks
                 * 
-                * @param this allocator_t object
+                * @param this          allocator_t object
                 */
                void (*report_memory_leaks) (allocator_t *this);
        };
 
        #ifndef ALLOCATOR_C_
+               
+               /**
+                * @brief Global allocater_t object.
+                * 
+                * Only accessed over macros.
+                */
                extern allocator_t *global_allocator;
        #endif
        
+       /**
+        * Macro to allocate some memory
+        * 
+        * @see #allocator_s.allocate for description
+        */
        #define allocator_alloc(bytes) (global_allocator->allocate(global_allocator,bytes,__FILE__,__LINE__))
+       /**
+        * Macro to reallocate some memory
+        * 
+        * @see #allocator_s.reallocate for description
+        */
        #define allocator_realloc(old,bytes) (global_allocator->reallocate(global_allocator,old,bytes,__FILE__, __LINE__))
+       /**
+        * Macro to free some memory
+        * 
+        * @see #allocator_s.free for description
+        */
        #define allocator_free(pointer) (global_allocator->free_pointer(global_allocator,pointer))
+       /**
+        * Macro to free a chunk
+        */
        #define allocator_free_chunk(chunk){    \
                global_allocator->free_pointer(global_allocator,chunk.ptr);                     \
                chunk.ptr = NULL;                               \
                chunk.len = 0;                                  \
        }
+       /**
+        * Macro to report memory leaks
+        * 
+        * @see #allocator_s.report_memory_leaks for description
+        */
        #define report_memory_leaks(void) global_allocator->report_memory_leaks(global_allocator);
 #else
        #define allocator_alloc(bytes) (malloc(bytes))