Adding a few comments and description to the info* functions

This commit was SVN r637.

src/mpi/interface/c/info_c2f.c

@@ -6,11 +6,22 @@
 
 #include "mpi.h"
 #include "mpi/interface/c/bindings.h"
+#include "lam/lfc/list.h"
+#include "mpi/info/info.h"
 
 #if LAM_HAVE_WEAK_SYMBOLS && LAM_PROFILING_DEFINES
 #pragma weak MPI_Info_c2f = PMPI_Info_c2f
 #endif
 
+/**
+ * Converts info into a fortan handle
+ *
+ * @param info The C handle which has to be converted 
+ * @retval Fortran handle corresponding to info.
+ *
+ * If info is a valid C handle, the MPI_Info_c2f returns a valid 
+ * fortran handle to the same MPI_INFO object.
+ */
 MPI_Fint MPI_Info_c2f(MPI_Info info) {
     return (MPI_Fint)0;
 }

src/mpi/interface/c/info_create.c

@@ -6,11 +6,51 @@
 
 #include "mpi.h"
 #include "mpi/interface/c/bindings.h"
+#include "lam/lfc/list.h"
+#include "mpi/info/info.h"
 
 #if LAM_HAVE_WEAK_SYMBOLS && LAM_PROFILING_DEFINES
 #pragma weak MPI_Info_create = PMPI_Info_create
 #endif
 
+/**
+ * Create a new info object 
+ *
+ * @param info Pointer to the MPI_Info handle
+ *
+ * @retval MPI_SUCCESS
+ * @retval MPI_ERR_ARG
+ * @retval MPI_ERR_EXHAUSTED
+ *
+ * When an MPI_Info object is not being used, it should be freed using
+ * MPI_Info_free
+ */
 int MPI_Info_create(MPI_Info *info) {
+    /**
+     * Anju:
+     * These are miscelleneous notes. They will be removed later.
+     *
+     * MPI_Info is a pointer to the struct lam_info_t. This structure 
+     * contains a pointer to the lam_list_t structure. lam_list_t 
+     * structure is a generic list management structure which is a
+     * container that can hold lam_list_item_t objects. Hence any 
+     * object that needs to be stored as a list has to have lam_list_item_t
+     * as its first element.
+     * 
+     * Steps to initialize the list item:
+     * info -> pointer to MPI_Info
+     * MPI_Info -> pointer to lam_info_t
+     * lam_info_t -> has pointer to lam_list_t item.
+     *
+     * First, we initialize by allocating memory for lam_info_t
+     * structure. Then, we have to initialize the list itself. Way to 
+     * initialize the list is 
+     * 
+     * (*info) = (lam_info_t) LAM_MALLOC (sizeof(struct laminfo_t))
+     * (*info)->list_pointer = (lam_list_t) LAM_MALLOC (sizeof(struct
+     *                                                  lam_list_t))
+     * lam_list_init((*info)->list_pointer)
+     *
+     */
     return MPI_SUCCESS;
 }

src/mpi/interface/c/info_delete.c

@@ -6,11 +6,30 @@
 
 #include "mpi.h"
 #include "mpi/interface/c/bindings.h"
+#include "lam/lfc/list.h"
+#include "mpi/info/info.h"
 
 #if LAM_HAVE_WEAK_SYMBOLS && LAM_PROFILING_DEFINES
 #pragma weak MPI_Info_delete = PMPI_Info_delete
 #endif
 
+/**
+ * Delete a (key,value) pair from "info"
+ *
+ * @param info MPI_Info handle on which we need to operate
+ * @param key The key portion of the (key,value) pair that 
+ *            needs to be deleted
+ *
+ * @retval MPI_SUCCESS If the (key,val) pair was deleted
+ * @retval MPI_ERR_ARG
+ * @retval MPI_ERR_KEY
+ * @retval MPI_ERR_NOKEY
+ * @retval MPI_ERR_INTERN
+ */
 int MPI_Info_delete(MPI_Info info, char *key) {
+
+    /**
+     * This function merely deletes the (key,val) pair in info
+     */
     return MPI_SUCCESS;
 }

src/mpi/interface/c/info_dup.c

@@ -6,11 +6,33 @@
 
 #include "mpi.h"
 #include "mpi/interface/c/bindings.h"
+#include "lam/lfc/list.h"
+#include "mpi/info/info.h"
 
 #if LAM_HAVE_WEAK_SYMBOLS && LAM_PROFILING_DEFINES
 #pragma weak MPI_Info_dup = PMPI_Info_dup
 #endif
 
+/**
+ *   MPI_Info_dup - Duplicate an 'MPI_Info' object
+ *
+ *   @param info source info object (handle)
+ *   @param newinfo pointer to the new info object (handle)
+ *
+ *   @retval MPI_SUCCESS
+ *   @retval MPI_ERR_ARG
+ *
+ *   Not only will the (key, value) pairs be duplicated, the order of keys
+ *   will be the same in 'newinfo' as it is in 'info'.
+ *   When an info object is no longer being used, it should be freed with
+ *   'MPI_Info_free'.
+ */
 int MPI_Info_dup(MPI_Info info, MPI_Info *newinfo) {
+    /**
+     * Here we need to do 2 things
+     * 1. Create a newinfo object using MPI_Info_create
+     * 2. Fetch all the values from info and copy them to 
+     *    newinfo using MPI_Info_set
+     */
     return MPI_SUCCESS;
 }

src/mpi/interface/c/info_f2c.c

@@ -6,11 +6,19 @@
 
 #include "mpi.h"
 #include "mpi/interface/c/bindings.h"
+#include "lam/lfc/list.h"
+#include "mpi/info/info.h"
 
 #if LAM_HAVE_WEAK_SYMBOLS && LAM_PROFILING_DEFINES
 #pragma weak MPI_Info_f2c = PMPI_Info_f2c
 #endif
 
+/**
+ * Converts the MPI_Fint info into a valid C MPI_Info handle
+ *
+ * @param info Integer handle to an MPI_INFO object
+ * @retval C handle corresponding to MPI_INFOO object
+ */
 MPI_Info MPI_Info_f2c(MPI_Fint info) {
     return (MPI_Info)0;
 }

src/mpi/interface/c/info_free.c

@@ -6,11 +6,30 @@
 
 #include "mpi.h"
 #include "mpi/interface/c/bindings.h"
+#include "lam/lfc/list.h"
+#include "mpi/info/info.h"
 
 #if LAM_HAVE_WEAK_SYMBOLS && LAM_PROFILING_DEFINES
 #pragma weak MPI_Info_free = PMPI_Info_free
 #endif
 
+/**
+ *   MPI_Info_free - Free an 'MPI_Info' object.
+ *
+ *   @param info pointer to info object to be freed (handle)
+ *
+ *   @retval MPI_SUCCESS
+ *   @retval MPI_ERR_ARG
+ *
+ *   Upon successful completion, 'info' will be set to 'MPI_INFO_NULL'.
+ */
 int MPI_Info_free(MPI_Info *info) {
+    /*
+     * Free all the alloced items from MPI_Info info.
+     * Make sure the items are freed in an orderly
+     * fashion so that there are no dangling pointers.
+     * Also, something needs to be done about the 
+     * fortran handle.
+     */
     return MPI_SUCCESS;
 }

src/mpi/interface/c/info_get.c

@@ -6,12 +6,38 @@
 
 #include "mpi.h"
 #include "mpi/interface/c/bindings.h"
+#include "lam/lfc/list.h"
+#include "mpi/info/info.h"
 
 #if LAM_HAVE_WEAK_SYMBOLS && LAM_PROFILING_DEFINES
 #pragma weak MPI_Info_get = PMPI_Info_get
 #endif
 
+/**
+ *   MPI_Info_get - Get a (key, value) pair from an 'MPI_Info' object
+ *
+ *   @param info info object (handle)
+ *   @param key null-terminated character string of the index key
+ *   @param valuelen maximum length of 'value' (integer)
+ *   @param value null-terminated character string of the value
+ *   @param flag true (1) if 'key' defined on 'info', false (0) if not
+ *               (logical)
+ *
+ *   @retval MPI_SUCCESS
+ *   @retval MPI_ERR_ARG
+ *   @retval MPI_ERR_INFO_KEY
+ *
+ *   In C and C++, 'valuelen' should be one less than the allocated space
+ *   to allow for for the null terminator.
+ */
 int MPI_Info_get(MPI_Info info, char *key, int valuelen,
                  char *value, int *flag) {
+
+    /*
+     * Simple function. All we need to do is search for the value
+     * having the "key" associated with it and then populate the
+     * necessary structures.
+     */
+
     return MPI_SUCCESS;
 }

src/mpi/interface/c/info_get_nkeys.c

@@ -6,11 +6,26 @@
 
 #include "mpi.h"
 #include "mpi/interface/c/bindings.h"
+#include "lam/lfc/list.h"
+#include "mpi/info/info.h"
 
 #if LAM_HAVE_WEAK_SYMBOLS && LAM_PROFILING_DEFINES
 #pragma weak MPI_Info_get_nkeys = PMPI_Info_get_nkeys
 #endif
 
+/**
+ * MPI_Info_get_nkeys - Returns the number of keys defined on an
+ * 'MPI_Info' object
+ *
+ * @param info info object (handle)
+ * @param nkeys number of keys defined on 'info' (integer)
+ *
+ * @retval MPI_SUCCESS
+ * @retval MPI_ERR_ARG
+ *
+ * This function returns the number of elements in the list 
+ * containing the key-value pairs
+ */
 int MPI_Info_get_nkeys(MPI_Info info, int *nkeys) {
     return MPI_SUCCESS;
 }

src/mpi/interface/c/info_get_nthkey.c

@@ -6,11 +6,23 @@
 
 #include "mpi.h"
 #include "mpi/interface/c/bindings.h"
+#include "lam/lfc/list.h"
+#include "mpi/info/info.h"
 
 #if LAM_HAVE_WEAK_SYMBOLS && LAM_PROFILING_DEFINES
 #pragma weak MPI_Info_get_nthkey = PMPI_Info_get_nthkey
 #endif
 
+/**
+ *   MPI_Info_get_nthkey - Get a key indexed by integer from an 'MPI_Info' obje
+ *
+ *   @param info info object (handle)
+ *   @param n index of key to retrieve (integer)
+ *   @param key character string of at least 'MPI_MAX_INFO_KEY' characters
+ *   
+ *   @retval MPI_SUCCESS
+ *   @retval MPI_ERR_ARG
+ */
 int MPI_Info_get_nthkey(MPI_Info info, int n, char *key) {
     return MPI_SUCCESS;
 }

src/mpi/interface/c/info_get_valuelen.c

@@ -6,11 +6,29 @@
 
 #include "mpi.h"
 #include "mpi/interface/c/bindings.h"
+#include "lam/lfc/list.h"
+#include "mpi/info/info.h"
 
 #if LAM_HAVE_WEAK_SYMBOLS && LAM_PROFILING_DEFINES
 #pragma weak MPI_Info_get_valuelen = PMPI_Info_get_valuelen
 #endif
 
+/**
+ *   MPI_Info_get_valuelen - Get the length of a value for a given key in an 'M
+ *
+ *   @param info - info object (handle)
+ *   @param key - null-terminated character string of the index key
+ *   @param valuelen - length of the value associated with 'key' (integer)
+ *   @param flag - true (1) if 'key' defined on 'info', false (0) if not
+ *   (logical)
+ *
+ *   @retval MPI_SUCCESS
+ *   @retval MPI_ERR_ARG
+ *   @retval MPI_ERR_INFO_KEY
+ *
+ *   The length returned in C and C++ does not include the end-of-string
+ *   character.  If the 'key' is not found on 'info', 'valuelen' is left alone.
+ */
 int MPI_Info_get_valuelen(MPI_Info info, char *key, int *valuelen,
                           int *flag) {
     return MPI_SUCCESS;

src/mpi/interface/c/info_set.c

@@ -6,11 +6,34 @@
 
 #include "mpi.h"
 #include "mpi/interface/c/bindings.h"
+#include "lam/lfc/list.h"
+#include "mpi/info/info.h"
 
 #if LAM_HAVE_WEAK_SYMBOLS && LAM_PROFILING_DEFINES
 #pragma weak MPI_Info_set = PMPI_Info_set
 #endif
 
+/**
+ *   MPI_Info_set - Set a (key, value) pair in an 'MPI_Info' object
+ *
+ *   @param key null-terminated character string of the index key
+ *   @param value null-terminated character string of the value
+ *   @param info info object (handle)
+ *
+ *   @retval MPI_SUCCESS
+ *   @retval MPI_ERR_ARG
+ *   @retval MPI_ERR_INFO_KEY
+ *   @retval MPI_ERR_INFO_VAL
+ *   @retval MPI_ERR_INFO_NOKEY
+ *   @retval MPI_ERR_INTERN
+ *
+ *   MPI_Info_set adds the (key,value) pair to info, and overrides
+ *   teh value if for the same key a previsou value was set. key and
+ *   value must nen NULL terminated strings in C. In fortan, leading 
+ *   and trailing spaces in key and value are stripped. If either 
+ *   key or value is greater than the allowed maxima, MPI_ERR_INFO_KEY
+ *   and MPI_ERR_INFO_VALUE are raised
+ */
 int MPI_Info_set(MPI_Info info, char *key, char *value) {
     return MPI_SUCCESS;
 }