Adding some documentation.

This commit was SVN r1639.

src/mca/allocator/allocator.h

@@ -2,31 +2,33 @@
   * $HEADER$
   */
 /**
-  * @file
+  * @file 
+  * The public definition of the MCA Allocator framework.
   */
 #ifndef MCA_ALLOCATOR_H
 #define MCA_ALLOCATOR_H
 #include "mca/mca.h"
 
+/* Here so that we can use mca_allocator_t in the function typedefs */
 struct mca_allocator_t;
 
 /**
-  * allocate function typedef
+  * The allocate function typedef for the functrion to be provided by the component.
   */
 typedef void* (*mca_allocator_alloc_fn_t)(struct mca_allocator_t*, size_t size, size_t align);
  
 /**
-  * realloc function typedef
+  * The realloc function typedef
   */
 typedef void* (*mca_allocator_realloc_fn_t)(struct mca_allocator_t*, void*, size_t);
 
 /**
-  * free function typedef
+  * Free function typedef
   */
 typedef void(*mca_allocator_free_fn_t)(struct mca_allocator_t*, void *);
 
 
-/*
+/**
  * compact/return memory to higher level allocator
  */
 
@@ -35,7 +37,7 @@ typedef int (*mca_allocator_return_fn_t)(
 );
  
 
-/*
+/**
  * cleanup (free) any resources held by allocator
  */
 
@@ -43,48 +45,63 @@ typedef int (*mca_allocator_finalize_fn_t)(
     struct mca_allocator_t* allocator 
 );
 
-
+/**
+ * The data structure for each component.
+ */
 struct mca_allocator_t {
-    mca_allocator_alloc_fn_t alc_alloc;
-    mca_allocator_realloc_fn_t alc_realloc;
-    mca_allocator_free_fn_t alc_free;
-    mca_allocator_return_fn_t alc_return;
-    mca_allocator_finalize_fn_t alc_finalize;
+    mca_allocator_alloc_fn_t alc_alloc;     /**< Allocate memory */
+    mca_allocator_realloc_fn_t alc_realloc; /**< Reallocate memory */
+    mca_allocator_free_fn_t alc_free;       /**< Free memory */
+    mca_allocator_return_fn_t alc_return;   /**< Return memory */
+    mca_allocator_finalize_fn_t alc_finalize; /**< Finalize and free everything */
 };
+/**
+ * Convenience typedef.
+ */
 typedef struct mca_allocator_t mca_allocator_t;
 
 
 /**
-  *
+  * A function to get more memory from the system. This function is to be
+  * provided by the module to the allocator framework.
   */
 
 typedef void* (*mca_allocator_segment_alloc_fn_t)(size_t* size);
 
 /**
-  *
+  * A function to free memory from the control of the allocator framework 
+  * back to the system. This function is to be provided by the module to the
+  * allocator frmaework.
   */
 typedef void* (*mca_allocator_segment_free_fn_t)(void* segment);
 
 
 /**
-  * module initialization function
+  * The function used to initialize the module. 
   */
-
 typedef struct mca_allocator_t* (*mca_allocator_base_module_init_fn_t)(
     bool *allow_multi_user_threads,
     mca_allocator_segment_alloc_fn_t segment_alloc,
     mca_allocator_segment_free_fn_t segment_free
 );
 
+/**
+ * The data structure provided by each component to the framework which
+ * describes the component.
+ */
 struct mca_allocator_base_module_1_0_0_t {
-    mca_base_module_t allocator_version;
-    mca_base_module_data_1_0_0_t allocator_data;
-    mca_allocator_base_module_init_fn_t allocator_init;
+    mca_base_module_t allocator_version; /**< The version of the module */
+    mca_base_module_data_1_0_0_t allocator_data; /**< The module metadata */
+    mca_allocator_base_module_init_fn_t allocator_init; 
+    /**< The module initialization function. */
 };
+/**
+ * Convenience typedef.
+ */
 typedef struct mca_allocator_base_module_1_0_0_t mca_allocator_base_module_t;
 
-/*
- * Macro for use in modules that are of type ptl v1.0.0
+/**
+ * Macro for use in modules that are of type allocator v1.0.0
  */
 #define MCA_ALLOCATOR_BASE_VERSION_1_0_0 \
   /* mpool v1.0 is chained to MCA v1.0 */ \
@@ -92,6 +109,9 @@ typedef struct mca_allocator_base_module_1_0_0_t mca_allocator_base_module_t;
   /* ptl v1.0 */ \
   "allocator", 1, 0, 0
 
+/**
+ * The output integer used for the mca base
+ */
 extern int mca_allocator_base_output;
 
 #endif /* MCA_ALLOCATOR_H */

src/mca/allocator/base/allocator_base_close.c

@@ -12,7 +12,11 @@
 #include "mca/allocator/allocator.h"
 #include "mca/allocator/base/base.h"
 
-
+/**
+ * Closes all the remaining modules.
+ *
+ * @retval OMPI_SUCCESS
+ */
 int mca_allocator_base_close(void)
 {
   /* Close all remaining available modules (may be one if this is a

src/mca/allocator/base/allocator_base_open.c

@@ -38,7 +38,15 @@ int mca_allocator_base_open(void)
                             &mca_allocator_base_components);
 }
 
-
+/**
+ * Traverses through the list of available modules, calling their init functions
+ * until it finds the module that has the specified name. It then returns the found
+ * module.
+ *
+ * @param name the name of the module that is being searched for.
+ * @retval mca_allocator_base_module_t* pointer to the requested module
+ * @retval NULL if the requested module is not found
+ */
 mca_allocator_base_module_t* mca_allocator_component_lookup(const char* name)
 {
     /* Traverse the list of available modules; call their init functions. */

src/mca/allocator/base/base.h

@@ -13,19 +13,27 @@
 #include "mca/mca.h"
 #include "mca/allocator/allocator.h"
 
-
+/**
+ * Structure which describes a selected module.
+ */
 struct mca_allocator_base_selected_module_t {
-  ompi_list_item_t super;
-  mca_allocator_base_module_t *allocator_component;
-  mca_allocator_t *allocator_module;
+  ompi_list_item_t super;    /**< Makes this an object of type ompi_list_item */
+  mca_allocator_base_module_t *allocator_component; /**< Info about the module */
+  mca_allocator_t *allocator_module; /**< The function pointers for all the module's functions. */
 };
+/**
+ * Convenience typedef.
+ */
 typedef struct mca_allocator_base_selected_module_t mca_allocator_base_selected_module_t;
-                                                                                                     
+
+/**
+ * Declaces mca_mpool_base_selected_module_t as a class.
+ */
 OBJ_CLASS_DECLARATION(mca_mpool_base_selected_module_t);
                                                                                                      
 
 /*
- * Global functions for MCA: overall PTL open and close
+ * Global functions for MCA: overall allocator open and close
  */
 
 #if defined(c_plusplus) || defined(__cplusplus)
@@ -42,7 +50,9 @@ extern "C" {
 /*
  * Globals
  */
-
+/**
+ * The list of all the selected components.
+ */
 extern ompi_list_t mca_allocator_base_components;
 
 #endif /* MCA_ALLOCATOR_BASE_H */

src/mca/allocator/bucket/allocator_bucket_alloc.h

@@ -3,9 +3,7 @@
  */
 
 /** @file
- *  A generic memory allocator.
- *
- *
+ *  A generic memory bucket allocator.
  **/
 
 #ifndef ALLOCATOR_BUCKET_ALLOC_H 
@@ -18,26 +16,19 @@
 #include "class/ompi_object.h"
 #include "mca/allocator/allocator.h"
 
-/**
-  * Typedef so we can add a pointer to mca_allocator_bucket_chunk_header_t in
-  * mca_allocator_bucket_chunk_header_t
-  */
-typedef struct mca_allocator_bucket_chunk_header_t * mca_allocator_bucket_chunk_header_ptr_t; 
-
 /**
   * Structure for the header of each memory chunk
   */
 struct mca_allocator_bucket_chunk_header_t {
-    mca_allocator_bucket_chunk_header_ptr_t  next_in_segment; /**< The next chunk in the 
-                                                   memory segment */
+    struct mca_allocator_bucket_chunk_header_t * next_in_segment; 
+               /**< The next chunk in the memory segment */
     /**
       * Union which holds either a pointer to the next free chunk
       * or the bucket number
       */
     union u {
-        mca_allocator_bucket_chunk_header_ptr_t next_free; /**< if the chunk is free this
-                                                will point to the next free
-                                                chunk in the bucket */
+        struct mca_allocator_bucket_chunk_header_t * next_free; 
+        /**< if the chunk is free this will point to the next free chunk in the bucket */
         int bucket;                  /**< the bucket number it belongs to */
     } u; /**< the union */
 };
@@ -46,17 +37,12 @@ struct mca_allocator_bucket_chunk_header_t {
    */ 
 typedef struct mca_allocator_bucket_chunk_header_t mca_allocator_bucket_chunk_header_t;
 
-/**
-  * Typedef so we can reference a pointer to mca_allocator_bucket_segment_head_t from itself
-  */
-typedef struct mca_allocator_bucket_segment_head_t * mca_allocator_bucket_segment_head_ptr;
-
 /**
   * Structure that heads each segment 
   */
 struct mca_allocator_bucket_segment_head_t {
-    mca_allocator_bucket_chunk_header_t * first_chunk; /**< the first chunk of the header */
-    mca_allocator_bucket_segment_head_ptr next_segment; /**< the next segment in the 
+    struct mca_allocator_bucket_chunk_header_t * first_chunk; /**< the first chunk of the header */
+    struct mca_allocator_bucket_segment_head_t * next_segment; /**< the next segment in the 
                                                  bucket */
 };
 /**
@@ -81,13 +67,13 @@ typedef struct mca_allocator_bucket_bucket_t mca_allocator_bucket_bucket_t;
   * Structure that holds the necessary information for each area of memory
   */
 struct mca_allocator_bucket_t {
-    mca_allocator_t super;
-    mca_allocator_bucket_bucket_t * buckets;     /**< the array of buckets */
-    int num_buckets;                     /**< the number of buckets */
-    mca_allocator_segment_alloc_fn_t get_mem_fn;          /**< pointer to the function to get
-                                              more memory */
-    mca_allocator_segment_free_fn_t free_mem_fn;       /**< pointer to the function to free
-                                              memory */
+    mca_allocator_t super;          /**< makes this a child of class mca_allocator_t */
+    mca_allocator_bucket_bucket_t * buckets; /**< the array of buckets */
+    int num_buckets;                         /**< the number of buckets */
+    mca_allocator_segment_alloc_fn_t get_mem_fn; 
+    /**< pointer to the function to get more memory */
+    mca_allocator_segment_free_fn_t free_mem_fn;
+    /**< pointer to the function to free memory */
 };
 /**
   * Typedef so we don't have to use struct
@@ -100,7 +86,8 @@ extern "C" {
   /**
    * Initializes the mca_allocator_bucket_options_t data structure for the passed
    * parameters.
-   * @param numBuckets The number of buckets the allocator will use
+   * @param mem a pointer to the mca_allocator_t struct to be filled in
+   * @param num_buckets The number of buckets the allocator will use
    * @param get_mem_funct A pointer to the function that the allocator
    * will use to get more memory
    * @param free_mem_funct A pointer to the function that the allocator
@@ -118,27 +105,24 @@ extern "C" {
    * mca_allocator_bucket_options_t struct and returns a pointer to memory in that
    * region or NULL if there was an error
    *
-   * @param mem_options A pointer to the appropriate struct for the area of
-   * memory.
+   * @param mem A pointer to the appropriate struct for the area of memory.
    * @param size The size of the requested area of memory
    *
    * @retval Pointer to the area of memory if the allocation was successful
    * @retval NULL if the allocation was unsuccessful
-   *
    */
     void * mca_allocator_bucket_alloc(mca_allocator_t * mem, size_t size);
 
 /**
    * Accepts a request for memory in a specific region defined by the
-   * mca_allocator_bucket_options_t struct and aligned by the specified amount and returns a
-   * pointer to memory in that region or NULL if there was an error
+   * mca_allocator_bucket_options_t struct and aligned by the specified amount and
+   * returns a pointer to memory in that region or NULL if there was an error
    *
-   * @param mem_options A pointer to the appropriate struct for the area of
+   * @param mem A pointer to the appropriate struct for the area of
    * memory.
    * @param size The size of the requested area of memory
    * @param alignment The requested alignment of the new area of memory. This
-   * MUST be a power of 2. If it is 0 then the memory is aligned on a page
-   * boundry
+   * MUST be a power of 2. 
    *
    * @retval Pointer to the area of memory if the allocation was successful
    * @retval NULL if the allocation was unsuccessful
@@ -152,7 +136,7 @@ extern "C" {
    * region. If it is unsuccessful, it will return NULL and the passed area of
    * memory will be untouched.
    *
-   * @param mem_options A pointer to the appropriate struct for the area of
+   * @param mem A pointer to the appropriate struct for the area of
    * memory.
    * @param size The size of the requested area of memory
    * @param ptr A pointer to the region of memory to be resized
@@ -167,7 +151,7 @@ extern "C" {
 /**
    * Frees the passed region of memory
    *
-   * @param mem_options A pointer to the appropriate struct for the area of
+   * @param mem A pointer to the appropriate struct for the area of
    * memory.
    * @param ptr A pointer to the region of memory to be freed
    *
@@ -181,7 +165,7 @@ extern "C" {
    * this function only frees memory that was previously freed with
    * mca_allocator_bucket_free().
    *
-   * @param mem_options A pointer to the appropriate struct for the area of
+   * @param mem A pointer to the appropriate struct for the area of
    * memory.
    *
    * @retval None
@@ -192,7 +176,7 @@ extern "C" {
 /**
    * Cleanup all resources held by this allocator.
    *
-   * @param mem_options A pointer to the appropriate struct for the area of
+   * @param mem A pointer to the appropriate struct for the area of
    * memory.
    *
    * @retval None

src/mca/mpool/base/base.h

@@ -24,7 +24,7 @@ typedef struct mca_mpool_base_selected_module_t mca_mpool_base_selected_module_t
 OBJ_CLASS_DECLARATION(mca_mpool_base_selected_module_t);
 
 /*
- * Global functions for MCA: overall PTL open and close
+ * Global functions for MCA: overall mpool open and close
  */
 
 #if defined(c_plusplus) || defined(__cplusplus)

src/mca/mpool/mpool.h

@@ -3,6 +3,7 @@
   */
 /**
   * @file
+  * Description of the Memory Pool framework
   */
 #ifndef MCA_MPOOL_H
 #define MCA_MPOOL_H
@@ -53,40 +54,49 @@ typedef void (*mca_mpool_base_finalize_fn_t)(struct mca_mpool_t*);
 
 
 /**
- *  mpool component descriptor. Contains component version information
- *  and open/close/init functions.
+ * initialize
  */
-                                                                                                                         
 typedef struct mca_mpool_t* (*mca_mpool_base_init_fn_t)(bool *allow_multi_user_threads);
 
-
+/**
+ * mpool component descriptor. Contains component version information
+ * and open/close/init functions.
+ */
 struct mca_mpool_base_component_1_0_0_t {
-  mca_base_module_t mpool_version;
-  mca_base_module_data_1_0_0_t mpool_data;
-  mca_mpool_base_init_fn_t mpool_init;
+  mca_base_module_t mpool_version;        /**< version */
+  mca_base_module_data_1_0_0_t mpool_data;/**< metadata */
+  mca_mpool_base_init_fn_t mpool_init;    /**< init function */
 };
+/**
+ * Convenience typedef.
+ */
 typedef struct mca_mpool_base_component_1_0_0_t mca_mpool_base_component_1_0_0_t;
+/**
+  * Convenience typedef
+  */
 typedef struct mca_mpool_base_component_1_0_0_t mca_mpool_base_component_t;
-                                                                                                                         
 
 /**
  *  mpool module descriptor. Contains functions exported
  *  by the component.
  */
 struct mca_mpool_t {
-    mca_mpool_base_component_t *mpool_component;
-    mca_mpool_base_address_fn_t mpool_base;
-    mca_mpool_base_alloc_fn_t mpool_alloc;
-    mca_mpool_base_realloc_fn_t mpool_realloc;
-    mca_mpool_base_free_fn_t mpool_free;
-    mca_mpool_base_register_fn_t mpool_register;
-    mca_mpool_base_deregister_fn_t mpool_deregister;
-    mca_mpool_base_finalize_fn_t mpool_finalize;
+    mca_mpool_base_component_t *mpool_component;  /**< component stuct */
+    mca_mpool_base_address_fn_t mpool_base;       /**< returns the base address */
+    mca_mpool_base_alloc_fn_t mpool_alloc;        /**< allocate function */
+    mca_mpool_base_realloc_fn_t mpool_realloc;    /**< reallocate function */
+    mca_mpool_base_free_fn_t mpool_free;          /**< free function */
+    mca_mpool_base_register_fn_t mpool_register;  /**< register memory */
+    mca_mpool_base_deregister_fn_t mpool_deregister; /**< deregister memory */
+    mca_mpool_base_finalize_fn_t mpool_finalize;  /**< finalize */
 };
+/**
+ * Convenience typedef
+ */
 typedef struct mca_mpool_t mca_mpool_t;
 
-/*
- * Macro for use in modules that are of type ptl v1.0.0
+/**
+ * Macro for use in modules that are of type mpool v1.0.0
  */
 #define MCA_MPOOL_BASE_VERSION_1_0_0 \
   /* mpool v1.0 is chained to MCA v1.0 */ \