From 60be99b4cd89b025aebf8f5f19d087a9236254e6 Mon Sep 17 00:00:00 2001 From: Prabhanjan Kambadur Date: Sun, 1 Feb 2004 22:28:20 +0000 Subject: [PATCH] Adding a few comments and description to the info* functions This commit was SVN r637. --- src/mpi/interface/c/info_c2f.c | 11 +++++++ src/mpi/interface/c/info_create.c | 40 +++++++++++++++++++++++++ src/mpi/interface/c/info_delete.c | 19 ++++++++++++ src/mpi/interface/c/info_dup.c | 22 ++++++++++++++ src/mpi/interface/c/info_f2c.c | 8 +++++ src/mpi/interface/c/info_free.c | 19 ++++++++++++ src/mpi/interface/c/info_get.c | 26 ++++++++++++++++ src/mpi/interface/c/info_get_nkeys.c | 15 ++++++++++ src/mpi/interface/c/info_get_nthkey.c | 12 ++++++++ src/mpi/interface/c/info_get_valuelen.c | 18 +++++++++++ src/mpi/interface/c/info_set.c | 23 ++++++++++++++ 11 files changed, 213 insertions(+) diff --git a/src/mpi/interface/c/info_c2f.c b/src/mpi/interface/c/info_c2f.c index ed9f72f03d..4959783778 100644 --- a/src/mpi/interface/c/info_c2f.c +++ b/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; } diff --git a/src/mpi/interface/c/info_create.c b/src/mpi/interface/c/info_create.c index 6e62077b43..2b8a9b5ea5 100644 --- a/src/mpi/interface/c/info_create.c +++ b/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; } diff --git a/src/mpi/interface/c/info_delete.c b/src/mpi/interface/c/info_delete.c index 7cee56b226..c7398e5934 100644 --- a/src/mpi/interface/c/info_delete.c +++ b/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; } diff --git a/src/mpi/interface/c/info_dup.c b/src/mpi/interface/c/info_dup.c index 0282ea2611..d06aa9adcf 100644 --- a/src/mpi/interface/c/info_dup.c +++ b/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; } diff --git a/src/mpi/interface/c/info_f2c.c b/src/mpi/interface/c/info_f2c.c index 545e96629a..e006b63fb7 100644 --- a/src/mpi/interface/c/info_f2c.c +++ b/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; } diff --git a/src/mpi/interface/c/info_free.c b/src/mpi/interface/c/info_free.c index c1f3c7965c..a9ef2cbb09 100644 --- a/src/mpi/interface/c/info_free.c +++ b/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; } diff --git a/src/mpi/interface/c/info_get.c b/src/mpi/interface/c/info_get.c index c5eca6d7d9..915ec679f1 100644 --- a/src/mpi/interface/c/info_get.c +++ b/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; } diff --git a/src/mpi/interface/c/info_get_nkeys.c b/src/mpi/interface/c/info_get_nkeys.c index afbdedcb04..2d48eba13d 100644 --- a/src/mpi/interface/c/info_get_nkeys.c +++ b/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; } diff --git a/src/mpi/interface/c/info_get_nthkey.c b/src/mpi/interface/c/info_get_nthkey.c index 21c3b5b8fd..c083f62e9a 100644 --- a/src/mpi/interface/c/info_get_nthkey.c +++ b/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; } diff --git a/src/mpi/interface/c/info_get_valuelen.c b/src/mpi/interface/c/info_get_valuelen.c index 104745c28b..9a002096fe 100644 --- a/src/mpi/interface/c/info_get_valuelen.c +++ b/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; diff --git a/src/mpi/interface/c/info_set.c b/src/mpi/interface/c/info_set.c index 86f72293a1..c58c09c1d6 100644 --- a/src/mpi/interface/c/info_set.c +++ b/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; }