- code refined
authorJan Hutter <jhutter@hsr.ch>
Fri, 25 Nov 2005 08:10:38 +0000 (08:10 -0000)
committerJan Hutter <jhutter@hsr.ch>
Fri, 25 Nov 2005 08:10:38 +0000 (08:10 -0000)
- documentation cleaned

Source/charon/utils/allocator.c
Source/charon/utils/allocator.h

index a56369f..e6b0eba 100644 (file)
@@ -1,9 +1,7 @@
 /**
  * @file allocator.c
  * 
- * @brief Memory allocation with LEAK_DETECTION support
- * 
- * Thread-save implementation 
+ * @brief Implementation of allocator_t.
  */
 
 /*
 
 #ifdef LEAK_DETECTIVE
 
+
 typedef union memory_hdr_t memory_hdr_t;
 
 /**
- * Header of each allocated memory area
+ * Header of each allocated memory area.
  * 
- * Used to detect memory leaks
+ * Ideas stolen from pluto's defs.c.
+ * 
+ * Used to detect memory leaks.
  */
 union memory_hdr_t {
-    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
+        * Informations
         */
-       memory_hdr_t *older, *newer;
-    } info;    /* info */
+    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;
     /**
      * force maximal alignment ?
      */
     unsigned long junk;        
 };
 
+typedef struct private_allocator_t private_allocator_t;
+
 /**
  * @brief Private allocator_t object.
  * 
  * Contains private variables of allocator_t object.
  */
-typedef struct private_allocator_t private_allocator_t;
-
 struct private_allocator_t
 {
        /**
@@ -79,14 +83,14 @@ struct private_allocator_t
        allocator_t public;
        
        /**
-        * Global list of allocations
+        * Global list of allocations.
         * 
-        * Thread-save through mutex
+        * Thread-save through mutex.
         */
        memory_hdr_t *allocations;
 
        /**
-        * Mutex used to make sure, all functions are thread-save
+        * Mutex used to make sure, all functions are thread-save.
         */
        pthread_mutex_t mutex;
        
@@ -98,17 +102,16 @@ struct private_allocator_t
         * @param bytes                 number of bytes to allocate
         * @param file          filename from which the memory is allocated
         * @param line          line number in specific file
-        * @param use_mutex If FALSE no mutex is used for allocation
+        * @param use_mutex if FALSE no mutex is used for allocation
         * @return              
-        *                              - pointer to allocated memory area if successful
-        *                              - NULL otherwise
+        *                                      - pointer to allocated memory area
+        *                                      - NULL if out of ressources
         */ 
        void * (*allocate_special) (private_allocator_t *this,size_t bytes, char * file,int line, bool use_mutex);
 };
 
 /**
- * Implements private_allocator_t's function allocate_special. 
- * See #private_allocator_s.allocate_special for description.
+ * Implementation of private_allocator_t.allocate_special. 
  */
 static void *allocate_special(private_allocator_t *this,size_t bytes, char * file,int line, bool use_mutex)
 {
@@ -147,8 +150,7 @@ static void *allocate_special(private_allocator_t *this,size_t bytes, char * fil
 }
 
 /**
- * Implements allocator_t's function allocate. 
- * See #allocator_s.allocate for description.
+ * Implementation of allocator_t.allocate. 
  */
 static void * allocate(allocator_t *allocator,size_t bytes, char * file,int line)
 {
@@ -157,8 +159,7 @@ static void * allocate(allocator_t *allocator,size_t bytes, char * file,int line
 }
 
 /**
- * Implements allocator_t's function allocate_as_chunk. 
- * See #allocator_s.allocate_as_chunk for description.
+ * Implementation of allocator_t.allocate_as_chunk. 
  */
 static chunk_t allocate_as_chunk(allocator_t *allocator,size_t bytes, char * file,int line)
 {
@@ -169,9 +170,8 @@ static chunk_t allocate_as_chunk(allocator_t *allocator,size_t bytes, char * fil
        return new_chunk;
 }
 
-/*
- * Implements allocator_t's free_pointer function. 
- * See #allocator_s.free_pointer for description.
+/**
+ * Implementation of allocator_t.free_pointer. 
  */
 static void free_pointer(allocator_t *allocator, void * pointer)
 {
@@ -204,9 +204,8 @@ static void free_pointer(allocator_t *allocator, void * pointer)
     free(allocated_memory);
 }
 
-/*
- * Implements allocator_t's reallocate function. 
- * See #allocator_s.reallocate for description.
+/**
+ * Implementation of allocator_t.reallocate. 
  */
 static void * reallocate(allocator_t *allocator, void * old, size_t bytes, char * file,int line)
 {
@@ -239,9 +238,8 @@ static void * reallocate(allocator_t *allocator, void * old, size_t bytes, char
        return new_space;
 }
 
-/*
- * Implements allocator_t's clone_bytes function. 
- * See #allocator_s.clone_bytes for description.
+/**
+ * Implementation of allocator_t.clone_bytes. 
  */
 static void * clone_bytes(allocator_t *allocator,void * to_clone, size_t bytes, char * file, int line)
 {
@@ -265,9 +263,8 @@ static void * clone_bytes(allocator_t *allocator,void * to_clone, size_t bytes,
        return new_space;
 }
 
-/*
- * Implements allocator_t's report_memory_leaks allocate. 
- * See #allocator_s.report_memory_leaks for description.
+/**
+ * Implementation of allocator_t.allocator_report_memory_leaks. 
  */
 static void allocator_report_memory_leaks(allocator_t *allocator)
 {
@@ -297,7 +294,7 @@ static void allocator_report_memory_leaks(allocator_t *allocator)
 }
 
 /** 
- * Only initiation of allocator object.
+ * Only Initiation of allocator object.
  * 
  * All allocation macros use this object.
  */
@@ -317,6 +314,9 @@ allocator_t *global_allocator = &(allocator.public);
 #else /* !LEAK_DETECTION */
 
 
+/*
+ * Described in header
+ */
 chunk_t allocator_alloc_as_chunk(size_t bytes)
 {
        chunk_t new_chunk;
@@ -326,12 +326,18 @@ chunk_t allocator_alloc_as_chunk(size_t bytes)
 
 }
 
+/*
+ * Described in header
+ */
 void * allocator_realloc(void * old, size_t newsize)
 {
        void *data = realloc(old,newsize);
        return data;
 } 
 
+/*
+ * Described in header
+ */
 void * allocator_clone_bytes(void * pointer, size_t size)
 {
        
@@ -344,13 +350,15 @@ void * allocator_clone_bytes(void * pointer, size_t size)
        return (data);
 }
 
-
-void allocator_free_chunk(chunk_t chunk)
+/*
+ * Described in header
+ */
+void allocator_free_chunk(chunk_t *chunk)
 {
-       free(chunk.ptr);                
+       free(chunk->ptr);
+       chunk->ptr = NULL;
+       chunk->len = 0;
 }
 
 
 #endif /* LEAK_DETECTION */
-
-
index e262372..b011121 100644 (file)
@@ -1,9 +1,7 @@
 /**
  * @file allocator.h
  * 
- * @brief Memory allocation with LEAK_DETECTION support
- * 
- * Thread-save implementation 
+ * @brief Interface of allocator_t.
  */
 
 /*
 
 
 /**
- * Macro to allocate a special type
+ * Macro to allocate a special type.
  * 
- * @param thing        object on which a sizeof is performed
+ * @param thing                object on which a sizeof is performed
  * @return 
- *                     - Pointer to allocated memory if successful
- *                     - NULL otherwise
+ *                                     - Pointer to allocated memory
+ *                                     - NULL if out of ressources.
+ * 
+ * @ingroup utils
  */
 #define allocator_alloc_thing_as_chunk(thing) (allocator_alloc_as_chunk(sizeof(thing)))
 
 /**
- * Macro to allocate a special type as chunk_t
+ * Macro to allocate a special type as chunk_t.
  * 
- * @param thing        object on which a sizeof is performed
+ * @param thing                object on which a sizeof is performed
  * @return 
- *                     - chunk_t pointing to allocated memory if successful
- *                     - chunk_t containing empty pointer
+ *                                     - chunk_t pointing to allocated memory if successful
+ *                                     - chunk_t containing empty pointer if out of ressources
+ *
+ * @ingroup utils
  */
 #define allocator_alloc_thing(thing) (allocator_alloc(sizeof(thing)))
 
@@ -58,6 +60,7 @@
        /**
         *@brief Allocater object use to detect memory leaks.
         *
+        * @ingroup utils
         */
        struct allocator_t {
        
@@ -73,8 +76,8 @@
                 * @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
+                *                              - pointer to allocated memory area
+                *                              - NULL if out of ressources
                 */ 
                void * (*allocate) (allocator_t *this,size_t bytes, char * file,int line);
 
                 * Allocates memory with LEAK_DETECTION and 
                 * returns an chunk pointing to an empy data area filled with zeros.
                 * 
-                * @warning             Use this function not directly, only with assigned macros 
-                *                              #allocator_alloc_as_chunk and #allocator_alloc_thing_as_chunk.
+                * @warning             Use this function not directly, only with assigned 
+                *                              macros #allocator_alloc_as_chunk and 
+                *                              #allocator_alloc_thing_as_chunk.
                 * 
                 * @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              
-                *                              - pointer to allocated memory area if successful
-                *                              - NULL otherwise
+                *                              - pointer to allocated memory area
+                *                              - NULL if out of ressources
                 */ 
                chunk_t (*allocate_as_chunk) (allocator_t *this,size_t bytes, char * file,int line);
        
                /**
                 * Reallocates 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 macro 
-                *                              #allocator_realloc
+                *                              #allocator_realloc.
                 * 
                 * @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              - pointer to reallocated memory area if successful
-                *                              - NULL otherwise
+                * @return              
+                *                              - pointer to reallocated memory area
+                *                              - NULL if out of ressources
                 */ 
                void * (*reallocate) (allocator_t *this,void * old, size_t bytes, char * file, int line);
                
                /**
-                * Clones memory with LEAK_DETECTION and 
-                * returns a cloned data area.
+                * Clones memory with LEAK_DETECTION and returns a cloned data area.
                 * 
                 * @warning             Use this function not directly, only with assigned macro 
-                *                              #allocator_clone_bytes
+                *                              #allocator_clone_bytes.
                 * 
                 * @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              - pointer to reallocated memory area if successful
-                *                              - NULL otherwise
+                * @return              
+                *                              - pointer to reallocated memory area if successful
+                *                              - NULL if out of ressources
                 */ 
                void * (*clone_bytes) (allocator_t *this,void * to_clone, size_t bytes, char * file, int line);         
                                
                /**
-                * Frees memory with LEAK_DETECTION
+                * Frees memory with LEAK_DETECTION.
                 * 
                 * @warning             Use this function not directly, only with assigned macro 
-                *                              #allocator_free
+                *                              #allocator_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
+                * Report memory leaks to stderr.
                 *
                 * @warning             Use this function not directly, only with assigned macro 
                 *                              #report_memory_leaks
 
        
        /**
-        * Macro to allocate some memory
+        * Macro to allocate some memory.
+        * 
+        * See #allocator_t.allocate for description.
         * 
-        * @see #allocator_s.allocate for description
+        * @ingroup utils
         */
        #define allocator_alloc(bytes) (global_allocator->allocate(global_allocator,bytes,__FILE__,__LINE__))
        
        /**
-        * Macro to allocate some memory for a chunk_t
+        * Macro to allocate some memory for a chunk_t.
+        * 
+        * See #allocator_t.allocate_as_chunk for description.
         * 
-        * @see #allocator_s.allocate_as_chunk for description
+        * @ingroup utils
         */
        #define allocator_alloc_as_chunk(bytes) (global_allocator->allocate_as_chunk(global_allocator,bytes,__FILE__,__LINE__))
        
        /**
-        * Macro to reallocate some memory
+        * Macro to reallocate some memory.
         * 
-        * @see #allocator_s.reallocate for description
+        * See #allocator_s.reallocate for description.
+        * 
+        * @ingroup utils
         */
        #define allocator_realloc(old,bytes) (global_allocator->reallocate(global_allocator,old,bytes,__FILE__, __LINE__))
        
        /**
-        * Macro to clone some memory
+        * Macro to clone some memory.
+        * 
+        * See #allocator_s.*clone_bytes  for description.
         * 
-        * @see #allocator_s.*clone_bytes  for description
+        * @ingroup utils
         */
        #define allocator_clone_bytes(old,bytes) (global_allocator->clone_bytes(global_allocator,old,bytes,__FILE__, __LINE__))
        
        /**
-        * Macro to free some memory
+        * Macro to free some memory.
         * 
-        * @see #allocator_s.free for description
+        * See #allocator_s.free for description.
+        *
+        * @ingroup utils
         */
        #define allocator_free(pointer) (global_allocator->free_pointer(global_allocator,pointer))
        /**
-        * Macro to free a chunk
+        * Macro to free a chunk.
         */
        #define allocator_free_chunk(chunk){    \
-               global_allocator->free_pointer(global_allocator,chunk.ptr);                     \
-               chunk.ptr = NULL;                               \
-               chunk.len = 0;                                  \
+               global_allocator->free_pointer(global_allocator,(chunk)->ptr);                  \
+               (chunk)->ptr = NULL;                            \
+               (chunk)->len = 0;                                       \
        }
        /**
-        * Macro to report memory leaks
+        * Macro to report memory leaks.
+        * 
+        * See #allocator_s.report_memory_leaks for description.
         * 
-        * @see #allocator_s.report_memory_leaks for description
+        * @ingroup utils
         */
        #define report_memory_leaks(void) (global_allocator->report_memory_leaks(global_allocator))
 #else
-
+       /**
+        * Macro to allocate some memory.
+        *
+        * @ingroup utils
+        */
        #define allocator_alloc(bytes) (malloc(bytes))  
+
+       /**
+        * Allocate some memory as chunk.
+        * 
+        * @ingroup utils
+        */
        chunk_t allocator_alloc_as_chunk(size_t bytes);
+
+       /**
+        * Reallocate some memory.
+        * 
+        * @ingroup utils
+        */
        void * allocator_realloc(void * old, size_t newsize);
+       
+       /**
+        * Free allocated memory.
+        * 
+        * @ingroup utils
+        */
        #define allocator_free(pointer) (free(pointer))
+       
+       /**
+        * Clone bytes.
+        *
+        *
+        * @param pointer       pointer to read data from
+        * @param size          number of bytes to clone
+        * 
+        * @ingroup utils
+        */
        void * allocator_clone_bytes(void * pointer, size_t size);
-       void allocator_free_chunk(chunk_t chunk);
+       
+       /**
+        * Frees memory used by chunk.
+        * 
+        * @param chunk         pointer of chunk to free
+        * 
+        * @ingroup utils
+        */
+       void allocator_free_chunk(chunk_t *chunk);
+       
+       /**
+        * Report memory leaks.
+        * 
+        * @ingroup utils
+        */
        #define report_memory_leaks(void) {}
 #endif