heap.h fully commented.

include/dmmlib/heap.h

@@ -2,7 +2,7 @@
  * \file 	heap.h
  * \author 	Ioannis Koutras (joko@microlab.ntua.gr)
  * \date 	September, 2011
- * \brief 	Basic structures needed for the dmmlib allocator.
+ * 	Basic structures needed for the dmmlib allocator.
  */
 
 #ifndef HEAP_H
@@ -17,85 +17,73 @@
 #include <pthread.h>
 #endif /* HAVE_LOCKS */
 
-
-
+/**
+ * A structure for knobs states (currently 5)
+ * 
+ * FIXME Have to check them
+ *
+ * */
 typedef uint8_t knob_state_t;
 
-/**
- * \brief A structure to represent a maptable node.
- */
+/** A structure to represent a maptable node. */
 typedef struct maptable_node_s {
-	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. */
+	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. */
 } maptable_node_t;
 
-/**
- * \brief Statistics data structure.
- */
+/** Statistics data structure. */
 typedef struct dmmstats_s {
-	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. */
+	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. */
 } dmmstats_t;
 
-/**
- * \brief A structure to represent tunable parameters of a heap
- */
+/** A structure to represent tunable parameters of a heap */
 typedef struct dmmknobs_s {
-	float frag_threshold; /**< \brief Fragmentation threshold to enable
-				coalescing or not. */ 
-	uint32_t mem_threshold; /**< \brief Memory size threshold. */
-	/** \brief Maximum coalesce size; -1 If coalescing is not supported */
-	int32_t max_coalesce_size;
-	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 what it is
-	knob_state_t frag_state; /**< \brief The current state of fragmentation. */
-	knob_state_t foot_state;	
+	float frag_threshold; /**< Fragmentation threshold to enable coalescing
+				or not. */ 
+	uint32_t mem_threshold; /**< Memory size threshold. */
+	int32_t max_coalesce_size; /**< Maximum coalesce size; -1 if coalescing
+				     is not supported */
+	uint32_t min_split_size; /**< Minimum split size. */
+	/* FIXME Need to find explanation */
+	float empty_threshold; /**< Empty Threshold */
+	uint32_t percentage; /**< Percentage value */
+	knob_state_t frag_state; /**< The current state of fragmentation. */
+	knob_state_t foot_state; /**< The current state of footprint. */
 } dmmknobs_t;
 
-/**
- * A structure to store heap information.
- */
+/** A structure to store heap information. */
 typedef struct heap_s {
-	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. */
+	maptable_node_t *maptable_head; /**< The head of the maptable list. */
+	void *free_list_head; /**< The head of the free list. */
+	void *used_blocks_head; /**< The head of the used blocks list. */
+	void *rov_ptr; /**< Roving pointer. */
+	uint64_t num_objects; /**< Number of objects in the heap. */
+	dmmstats_t dmm_stats; /**< Statistics of the heap. */
+	dmmknobs_t dmm_knobs; /**< Tunable parameters of the heap. */
 #ifdef HAVE_LOCKS
-	pthread_mutex_t mutex;/**< \brief Mutex when POSIX Threads are used. */
+	pthread_mutex_t mutex;/**< Mutex when POSIX Threads are used. */
 #endif /* HAVE_LOCKS */
 } heap_t;
 
-/**
- * \brief The allocator structure of dmmlib.
- */
+/** The allocator structure of dmmlib. */
 typedef struct allocator_s {
-	heap_t heaps[NUM_HEAPS]; /**< \brief The heaps that the allocator manages. */
-	bool initialized; /**< \brief Initialization flag of the allocator. */
+	heap_t heaps[NUM_HEAPS]; /**< The heaps that the allocator manages. */
+	bool initialized; /**< Initialization flag of the allocator. */
+	void *border_ptr; /**< Border pointer of the allocator. */
 #ifdef WITH_MEMORY_SPACE_AWARENESS
-	void *border_ptr;
-	size_t remaining_size;
+	size_t remaining_size; /**< The size of the remaining free space which
+				 is handled by the allocator. */
 #endif /* WITH_MEMORY_SPACE_AWARENESS */
 } allocator_t;