Comments on heap.h

heap.h

@@ -1,3 +1,10 @@
+/**
+ * \file 	heap.h
+ * \author 	Ioannis Koutras (joko@microlab.ntua.gr)
+ * \date 	September, 2011
+ * \brief 	Basic structures needed for the dmmlib allocator.
+ */
+
 #ifndef HEAP_H
 #define HEAP_H
 
@@ -8,60 +15,83 @@
 
 #include "block_header.h"
 
+/**
+ * \brief The number of the heaps.
+ */
 #define NUM_HEAPS 4
 
 /**
- * A structure to represent a maptable node
+ * \brief A structure to represent a maptable node.
  */
 typedef struct maptable_node_s {
-	unsigned int size; /**< the size of the blocks of the fixed list */
-	void *fixed_list_head; /**< pointer to the head node of the fixed list */
-	struct maptable_node_s *next; /**< pointer to the next node of the maptable */
+	unsigned int size; /**< \brief The size of the blocks of the fixed
+			     list. */
+	void *fixed_list_head; /**< \brief Pointer to the head node of the
+				 fixed list. */
+	struct maptable_node_s *next; /**< \brief Pointer to the next node of
+					the maptable. */
 } maptable_node_t;
 
+/**
+ * \brief Statistics data structure.
+ */
 typedef struct dmmstats_s {
-	uint32_t max_mem_allocated; /**< maximum total memory allocated */
-	uint32_t max_mem_requested; /**< maximum total memory requested */
-	uint32_t mem_allocated; /**< total memory currently allocated */
-	uint32_t mem_requested; /**< total memory currently requested */
-	uint32_t mem_reserved; /**< total memory currently reserved */
-	uint32_t live_objects; /**< number of live objects */
-	uint32_t read_mem_accesses; /**< number of read accesses */
-	uint32_t write_mem_accesses; /**< number of write accesses */
-	uint32_t num_malloc; /**< number of malloc()'s served */
-	uint32_t num_free; /**< number of free()'s served */
+	uint32_t max_mem_allocated; /**< \brief Maximum total memory
+				      allocated. */
+	uint32_t max_mem_requested; /**< \brief Maximum total memory
+				      requested. */
+	uint32_t mem_allocated; /**< \brief Total memory currently
+				  allocated. */
+	uint32_t mem_requested; /**< \brief Total memory currently
+				  requested. */
+	uint32_t mem_reserved; /**< \brief Total memory currently
+				 reserved. */
+	uint32_t live_objects; /**< \brief Number of live objects. */
+	uint32_t read_mem_accesses; /**< \brief Number of read accesses. */
+	uint32_t write_mem_accesses; /**< \brief Number of write accesses. */
+	uint32_t num_malloc; /**< \brief Number of malloc()'s served. */
+	uint32_t num_free; /**< \brief Number of free()'s served. */
 } dmmstats_t;
 
 /**
- * A structure to represent tunable parameters of a heap
+ * \brief A structure to represent tunable parameters of a heap
  */
 typedef struct dmmknobs_s {
-	int32_t max_coalesce_size; /**< maximum coalesce size; -1 if coalescing
-				     is not supported */
-	float frag_threshold; /**< fragmentation threshold to enable
-				coalescing or not */ 
-	uint32_t mem_threshold; /**< memory size threshold */
-	uint32_t min_split_size; // FIXME to be investigated if needed
-	float empty_threshold; // FIXME to be investigated if needed
+	/** \brief Maximum coalesce size; -1 If coalescing is not supported */
+	int32_t max_coalesce_size;
+	float frag_threshold; /**< \brief Fragmentation threshold to enable
+				coalescing or not. */ 
+	uint32_t mem_threshold; /**< \brief Memory size threshold. */
+	uint32_t min_split_size; /**< \brief Minimum split size. */
+	float empty_threshold; /**< FIXME Need to find explanation \brief Empty
+				 Threshold */
+	/*
 	uint32_t percentage; // FIXME to be investigated if needed
 	char frag_state; //FIXME It was in the old code to refresh the frag check
+	*/
 } dmmknobs_t;
 
+/**
+ * \brief A structure to store heap information.
+ */
 typedef struct heap_s {
-	maptable_node_t *maptable_head;
-	void *free_list_head;
-	void *used_blocks_head;
-	void *rov_ptr;
-	uint64_t num_objects;
-	dmmstats_t dmm_stats;
-	dmmknobs_t dmm_knobs;
+	maptable_node_t *maptable_head; /**< \brief The head of the maptable list. */
+	void *free_list_head; /**< \brief The head of the free list. */
+	void *used_blocks_head; /**< \brief The head of the used blocks list. */
+	void *rov_ptr; /**< \brief Roving pointer. */
+	uint64_t num_objects; /**< \brief Number of objects in the heap. */
+	dmmstats_t dmm_stats; /**< \brief Statistics of the heap. */
+	dmmknobs_t dmm_knobs; /**< \brief Tunable parameters of the heap. */
 #ifdef HAVE_LOCKS
-	pthread_mutex_t mutex;
+	pthread_mutex_t mutex;/**< \brief Mutex when POSIX Threads are used. */
 #endif /* HAVE_LOCKS */
 } heap_t;
 
+/**
+ * \brief The allocator structure of dmmlib.
+ */
 typedef struct allocator_s {
-	heap_t heaps[NUM_HEAPS];
+	heap_t heaps[NUM_HEAPS]; /**< \brief The heaps that the allocator manages. */
 } allocator_t;
 
 #endif /* HEAP_H */