Comments and doxygen updates to the oob.

This commit was SVN r1993.

src/mca/oob/base/base.h

@@ -21,14 +21,25 @@ extern ompi_process_name_t mca_oob_name_any;
 extern ompi_process_name_t mca_oob_name_seed;
 extern ompi_process_name_t mca_oob_name_self;
 
+/**
+ * The wildcard for recieves from any peer.
+ */
 #define MCA_OOB_NAME_ANY  &mca_oob_name_any
+/**
+ * The process name of the seed deamon
+ */
 #define MCA_OOB_NAME_SEED &mca_oob_name_seed
+/**
+ * Process name of self
+ */
 #define MCA_OOB_NAME_SELF &mca_oob_name_self
 
 /*
  * Other constants
  */
-
+/**
+ * Recieve from any tag.
+ */
 #define MCA_OOB_TAG_ANY 0
 
 /*
@@ -54,9 +65,9 @@ typedef enum {
 *   int size = mca_oob_recv(name, 0, 0, MSG_OOB_PEEK|MSG_OOB_TRUNC);
 */
 
-#define MCA_OOB_PEEK  0x01   /* flag to oob_recv to allow caller to peek a portion of the next available
+#define MCA_OOB_PEEK  0x01   /**< flag to oob_recv to allow caller to peek a portion of the next available
                               * message w/out removing the message from the queue.  */
-#define MCA_OOB_TRUNC 0x02   /* flag to oob_recv to return the actual size of the message even if the receive
+#define MCA_OOB_TRUNC 0x02   /**< flag to oob_recv to return the actual size of the message even if the receive
                                 buffer is smaller than the number of bytes available */
 
 #if defined(c_plusplus) || defined(__cplusplus)

src/mca/oob/base/oob_base_pack.c

@@ -2,8 +2,8 @@
  * $HEADER$
  */
 
-/** @file **/
-/**
+/** @file
+ *
  * The pack and unpack routines for the oob
  */
 #include "mca/oob/base/base.h"

src/mca/oob/cofs/src/oob_cofs.c

@@ -22,7 +22,7 @@
 
 static int do_recv(mca_ns_base_jobid_t jobid, mca_ns_base_vpid_t procid, const struct iovec* iov, int count, int tag, int flags);
 
-/**
+/*
 *  Similiar to unix send(2).
 *
 * @param peer (IN)   Opaque name of peer process.

src/mca/oob/oob.h

@@ -108,27 +108,34 @@ typedef int (*mca_oob_base_module_recv_nb_fn_t)(
     mca_oob_callback_fn_t cbfunc,
     void* cbdata);
 
-/*
+/**
  * OOB Module
  */
-
 struct mca_oob_1_0_0_t {
     mca_oob_base_module_send_fn_t     oob_send;
     mca_oob_base_module_recv_fn_t     oob_recv;
     mca_oob_base_module_send_nb_fn_t  oob_send_nb;
     mca_oob_base_module_recv_nb_fn_t  oob_recv_nb;
 };
+/**
+ * Convenience Typedef
+ */
 typedef struct mca_oob_1_0_0_t mca_oob_1_0_0_t;
+/**
+ * Convenience typedef
+ */
 typedef struct mca_oob_1_0_0_t mca_oob_t;
 
 /**
  * OOB Component
  */
-
 typedef mca_oob_t* (*mca_oob_base_component_init_fn_t)(
     bool *allow_multi_user_threads,
     bool *have_hidden_threads);
 
+/**
+ * OOB finalize function
+ */
 typedef int (*mca_oob_base_component_finalize_fn_t)(void);
 
 /**
@@ -141,11 +148,17 @@ struct mca_oob_base_component_1_0_0_t {
    mca_oob_base_component_init_fn_t oob_init;
    mca_oob_base_component_finalize_fn_t oob_finalize;
 };
+/**
+ * Convenience Typedef
+ */
 typedef struct mca_oob_base_component_1_0_0_t mca_oob_base_component_1_0_0_t;
+/**
+ * Convenience Typedef
+ */
 typedef mca_oob_base_component_1_0_0_t mca_oob_base_component_t;
 
 
-/*
+/**
  * Macro for use in components that are of type oob v1.0.0
  */
 #define MCA_OOB_BASE_VERSION_1_0_0 \
@@ -168,6 +181,9 @@ struct mca_oob_base_info_t {
   mca_oob_base_component_t *oob_component;
   mca_oob_t *oob_module;
 };
+/**
+ * Convenience Typedef
+ */
 typedef struct mca_oob_base_info_t mca_oob_base_info_t;
 
 /**
@@ -185,37 +201,6 @@ extern "C" {
     int mca_oob_base_open(void);
     int mca_oob_base_init(bool *allow_multi_user_threads, bool *have_hidden_threads);
     int mca_oob_base_close(void);
-
-/*
- * functions for pack and unpack routines
- */
-/**
- * This function packs the passed data according to the type enum.
- *
- * @param dest the destination for the packed data
- * @param src the source of the data
- * @param n the number of elements in the src
- * @param type the type of data 
- *
- * @retval OMPI_SUCCESS
- * @retval OMPI_ERROR
- */
-    int mca_oob_base_pack(void * dest, void * src, size_t n, mca_oob_base_type_t type);
-
-/**
- * This function unpacks the passed data according to the type enum.
- *
- * @param dest the destination for the unpacked data
- * @param src the source of the packed data
- * @param n the number of elements in the src
- * @param type the type of the data to unpack
- * 
- * @retval OMPI_SUCCESS
- * @retval OMPI_ERROR
- */
-    int mca_oob_base_unpack(void * dest, void * src, size_t n, mca_oob_base_type_t type);
-
-
 #if defined(c_plusplus) || defined(__cplusplus)
 }
 #endif

src/mca/oob/tcp/oob_tcp.c

@@ -316,8 +316,8 @@ int mca_oob_tcp_finalize(void)
                  errno);
         }
         /*** temporarily disable the removal of the revieve event
-         * to prevent segfaults
-         * ompi_event_del(&mca_oob_tcp_component.tcp_recv_event); */
+         * to prevent segfaults */
+         ompi_event_del(&mca_oob_tcp_component.tcp_recv_event); 
         if(0 != close(mca_oob_tcp_component.tcp_listen_sd)) {
             ompi_output(0, "mca_oob_tcp_finalize: error closing listen socket. errno=%d", errno);
         }
@@ -332,7 +332,7 @@ int mca_oob_tcp_finalize(void)
     return OMPI_SUCCESS;
 }
 
-/**
+/*
 * Compare two process names for equality.
 *
 * @param  n1  Process name 1.

src/mca/oob/tcp/oob_tcp.h

@@ -33,23 +33,21 @@ int mca_oob_tcp_close(void);
 mca_oob_t* mca_oob_tcp_init(bool *allow_multi_user_threads, bool *have_hidden_threads);
 int mca_oob_tcp_finalize(void);
 
-/*
+/**
  * Convert process name from network to host byte order.
  *
  * @param name
  */
-
 #define OMPI_PROCESS_NAME_NTOH(n) \
     n.cellid = ntohl(n.cellid); \
     n.jobid = ntohl(n.jobid); \
     n.vpid = ntohl(n.vpid); 
 
-/*
+/**
  * Convert process name from host to network byte order.
  *
  * @param name
  */
-
 #define OMPI_PROCESS_NAME_HTON(n) \
     n.cellid = htonl(n.cellid); \
     n.jobid = htonl(n.jobid); \
@@ -101,7 +99,7 @@ int mca_oob_tcp_send(
 
 int mca_oob_tcp_recv(
     ompi_process_name_t* peer, 
-    const struct iovec *iov, 
+    const struct iovec * msg, 
     int count, 
     int tag,
     int flags);
@@ -127,7 +125,7 @@ int mca_oob_tcp_recv(
 
 int mca_oob_tcp_send_nb(
     const ompi_process_name_t* peer, 
-    const struct iovec* iov, 
+    const struct iovec* msg, 
     int count,
     int tag,
     int flags, 
@@ -149,7 +147,7 @@ int mca_oob_tcp_send_nb(
 
 int mca_oob_tcp_recv_nb(
     ompi_process_name_t* peer, 
-    const struct iovec* iov, 
+    const struct iovec* msg, 
     int count, 
     int tag,
     int flags,
@@ -177,6 +175,9 @@ struct mca_oob_tcp_component_t {
     ompi_list_t      tcp_msg_recv;         /**< list of recieved messages */
     ompi_mutex_t     tcp_match_lock;       /**< lock held while searching/posting messages */
 };
+/**
+ * Convenience Typedef
+ */
 typedef struct mca_oob_tcp_component_t mca_oob_tcp_component_t;
 
 extern mca_oob_tcp_component_t mca_oob_tcp_component;

src/mca/oob/tcp/oob_tcp_hdr.h

@@ -9,7 +9,7 @@
 #ifndef _MCA_OOB_TCP_HDR_H_
 #define _MCA_OOB_TCP_HDR_H_
 
-/*
+/**
  * Header used by tcp oob protocol.
  */
 struct mca_oob_tcp_hdr_t {
@@ -18,10 +18,16 @@ struct mca_oob_tcp_hdr_t {
 };
 typedef struct mca_oob_tcp_hdr_t mca_oob_tcp_hdr_t;
 
+/**
+ * Convert the message header to host byte order
+ */
 #define MCA_OOB_TCP_HDR_NTOHL(h) \
     ntohl(h->msg_size); \
     ntohl(h->msg_tag);
 
+/**
+ * Convert the message header to network byte order
+ */
 #define MCA_OOB_TCP_HDR_HTONL(h) \
     htonl(h->msg_size); \
     htonl(h->msg_tag);

src/mca/oob/tcp/oob_tcp_msg.c

@@ -27,7 +27,7 @@ static void mca_oob_tcp_msg_destruct(mca_oob_tcp_msg_t* msg)
 }
 
 
-/**
+/*
  *  Wait for a msg to complete.
  *  @param  msg (IN)   Message to wait on.
  *  @param  rc (OUT)   Return code (number of bytes read on success or error code on failure).
@@ -50,7 +50,7 @@ int mca_oob_tcp_msg_wait(mca_oob_tcp_msg_t* msg, int* rc)
     return OMPI_SUCCESS;
 }
 
-/**
+/*
  *  Signal that a message has completed.
  *  @param  msg (IN)   Message to wait on.
  *  @param peer (IN) the peer of the message
@@ -113,7 +113,7 @@ bool mca_oob_tcp_msg_send_handler(mca_oob_tcp_msg_t* msg, struct mca_oob_tcp_pee
     }
 }
 
-/**
+/*
  * Receives message data.
  * @param msg the message to be recieved into
  * @param peer the peer to recieve from
@@ -154,7 +154,7 @@ bool mca_oob_tcp_msg_recv_handler(mca_oob_tcp_msg_t* msg, struct mca_oob_tcp_pee
     }
 }
 
-/**
+/*
  *  Called to copy the results of a message into user supplied iovec array.
  *  @param  msg (IN)   Message send that is in progress.
  *  @param  iov (IN)   Iovec array of user supplied buffers.
@@ -195,7 +195,7 @@ int mca_oob_tcp_msg_copy(mca_oob_tcp_msg_t* msg, const struct iovec* iov, int co
     return rc;
 }
 
-/**
+/*
  *  Match name to a message that has been received asynchronously (unexpected).
  *
  *  @param  name (IN)  Name associated with peer or wildcard to match first posted recv.
@@ -221,7 +221,7 @@ mca_oob_tcp_msg_t* mca_oob_tcp_msg_match_recv(const ompi_process_name_t* name, i
     return NULL;
 }
 
-/**
+/*
  *  Match name to a posted recv request.
  *
  *  @param  name (IN)  Name associated with peer or wildcard to match first posted recv.

src/mca/oob/tcp/oob_tcp_msg.h

@@ -107,7 +107,7 @@ int mca_oob_tcp_msg_copy(mca_oob_tcp_msg_t* msg, const struct iovec* iov, int co
 /**
  *  Called asynchronously to progress sending a message from the event library thread.
  *  @param  msg (IN)   Message send that is in progress. 
- *  @param  sd (IN)    Socket descriptor to use for send.
+ *  @param  peer (IN)  Peer we are sending to.
  *  @retval            Number of bytes copied.
  */
 bool mca_oob_tcp_msg_send_handler(mca_oob_tcp_msg_t* msg, struct mca_oob_tcp_peer_t * peer);
@@ -115,7 +115,7 @@ bool mca_oob_tcp_msg_send_handler(mca_oob_tcp_msg_t* msg, struct mca_oob_tcp_pee
 /**
  *  Called asynchronously to progress sending a message from the event library thread.
  *  @param  msg (IN)   Message send that is in progress. 
- *  @param  sd (IN)    Socket descriptor to use for send.
+ *  @param  peer (IN)  Peer theat we are recieving from.
  *  @retval bool       Bool flag indicating wether operation has completed.
  */
 
@@ -131,7 +131,7 @@ bool mca_oob_tcp_msg_recv_handler(mca_oob_tcp_msg_t* msg, struct mca_oob_tcp_pee
  *  Note - this routine requires the caller to be holding the module lock.
  */
 
-mca_oob_tcp_msg_t* mca_oob_tcp_msg_match_recv(const ompi_process_name_t*, int tag);
+mca_oob_tcp_msg_t* mca_oob_tcp_msg_match_recv(const ompi_process_name_t* name, int tag);
 
 /**
  *  Match name to a posted recv request.
@@ -144,7 +144,7 @@ mca_oob_tcp_msg_t* mca_oob_tcp_msg_match_recv(const ompi_process_name_t*, int ta
  *  Note - this routine requires the caller to be holding the module lock.
  */
 
-mca_oob_tcp_msg_t* mca_oob_tcp_msg_match_post(const ompi_process_name_t*, int tag, bool peek);
+mca_oob_tcp_msg_t* mca_oob_tcp_msg_match_post(const ompi_process_name_t* name, int tag, bool peek);
 
 /**
  *  Allocate space for iovec array - if the request number of elements is less than
@@ -152,11 +152,10 @@ mca_oob_tcp_msg_t* mca_oob_tcp_msg_match_post(const ompi_process_name_t*, int ta
  *  allocate count elements.
  *
  *  @param  msg (IN)  Message to allocate array.
+ *  @param  count (IN) the number of iovecs
  *  @return           Array of iovec elements.
  *
  */
-
-
 static inline struct iovec* mca_oob_tcp_msg_iov_alloc(mca_oob_tcp_msg_t* msg, int count)
 {
     if(count <= MCA_OOB_TCP_IOV_MAX) 

src/mca/oob/tcp/oob_tcp_peer.c

@@ -55,14 +55,14 @@ static void mca_oob_tcp_peer_construct(mca_oob_tcp_peer_t* peer)
  */
 static void mca_oob_tcp_peer_destruct(mca_oob_tcp_peer_t * peer)
 {
-    /* temporarily not delete the events to prevent segfaults
-     * mca_oob_tcp_peer_close(peer); */
-    if(peer->peer_state != MCA_OOB_TCP_CLOSED &&
+    /* temporarily not delete the events to prevent segfaults */
+    mca_oob_tcp_peer_close(peer); 
+    /*if(peer->peer_state != MCA_OOB_TCP_CLOSED &&
        peer->peer_sd >= 0) {
         ompi_event_del(&peer->peer_send_event);
         close(peer->peer_sd);
         peer->peer_sd = -1;
-    }
+    }*/
     OBJ_DESTRUCT(&(peer->peer_send_queue));
     OBJ_DESTRUCT(&(peer->peer_lock));
 }

src/mca/oob/tcp/oob_tcp_peer.h

@@ -46,6 +46,9 @@ struct mca_oob_tcp_peer_t {
     mca_oob_tcp_msg_t *peer_send_msg; /**< current send in progress */
     mca_oob_tcp_msg_t *peer_recv_msg; /**< current recv in progress */
 };
+/**
+ * Convenience Typedef
+ */
 typedef struct mca_oob_tcp_peer_t mca_oob_tcp_peer_t;
 
 /*