revamped SSG public interface

as bonus, added doxygen style comments

include/ssg.h

@@ -6,10 +6,12 @@
 
 #pragma once
 
-// "simple static group" interface
-//
-// Contains trivial wireup and connection management functionality, with a
-// model of a static (at startup) member list.
+/**
+ * Scalable Service Groups (SSG) interface
+ * 
+ * An interface for creating and managing process groups using
+ * Mercury and Argobots.
+ */
 
 #ifdef __cplusplus
 extern "C" {
@@ -22,31 +24,89 @@ extern "C" {
 #include <mpi.h>
 #endif
 
-// using pointer so that we can use proc (proc has to allocate in this case)
-typedef struct ssg *ssg_t;
+/* SSG return codes */
+#define SSG_SUCCESS 0
+/* TODO: define some errors? */
+
+#define SSG_GROUP_NULL 0
 
-// some defines
-// null pointer shim
-#define SSG_NULL ((ssg_t)NULL)
+/* XXX: actually define what these are */
+typedef int ssg_group_id_t;
 
-/// group member initialization
+/***************************************************
+ *** SSG runtime intialization/shutdown routines ***
+ ***************************************************/
 
-// config file based - load up the given config file containing a set of hostnames
-ssg_t ssg_init_config(margo_instance_id mid, const char * fname);
+/**
+ * Initializes the SSG runtime environment.
+ * @param[in] mid Corresponding Margo instance identifier
+ * @returns SSG_SUCCESS on success, SSG error code otherwise
+ */
+int ssg_init(
+    margo_instance_id mid);
+
+/**
+ * Finalizes the SSG runtime environment.
+ */
+void ssg_finalize(
+    void);
+
+/*************************************
+ *** SSG group management routines ***
+ *************************************/
+
+/**
+ * Creates an SSG group from a given list of HG address strings.
+ * @params[in] group_name   Name of the SSG group
+ * @params[in] hg_addr_strs Array of HG address strings for each group member
+ * @returns SSG group ID on success, SSG_GROUP_NULL otherwise
+ *
+ * NOTE: The HG address string of the caller of this function must be present in
+ * the list of address strings given in 'hg_addr_strs'. That is, the caller of
+ * this function is required to be a member of the SSG group that is created.
+ */
+ssg_group_id_t ssg_group_create(
+    const char *group_name,
+    const char * const hg_addr_strs[]);
+
+/**
+ * Creates an SSG group from a given config file containing the HG address strings
+ * of all group members.
+ * @params[in] group_name   Name of the SSG group
+ * @params[in] file_name    Name of the config file containing the corresponding
+ *                          HG address strings for this group
+ * @returns SSG group ID on success, SSG_GROUP_NULL otherwise
+ * 
+ * NOTE: The HG address string of the caller of this function must be present in
+ * the list of address strings given in the config file. That is, the caller of
+ * this function is required to be a member of the SSG group that is created.
+ */
+ssg_group_id_t ssg_group_create_config(
+    const char *group_name,
+    const char *file_name);
 
 #ifdef HAVE_MPI
-// mpi based (no config file) - all participants (defined by the input
-// communicator) do a global address exchange
-// in this case, the caller has already initialized HG with its address
-ssg_t ssg_init_mpi(margo_instance_id mid, MPI_Comm comm);
+/**
+ * Creates an SSG group from a given MPI communicator.
+ * @params[in] group_name   Name of the SSG group
+ * @params[in] comm         MPI communicator containing group members
+ * @returns SSG group ID on success, SSG_GROUP_NULL otherwise
+ */
+ssg_group_id_t ssg_group_create_mpi(
+    const char *group_name,
+    MPI_Comm comm);
 #endif
 
-/// finalization
-
-// teardown all state associated with the given ssg group
-void ssg_finalize(ssg_t s);
+/**
+ * Destroys data structures associated with a given SSG group ID.
+ * @params[in] group_id SSG group ID
+ * @returns SSG_SUCCESS on success, SSG error code otherwise
+ */
+int ssg_group_destroy(
+    ssg_group_id_t group_id);
 
-/// accessors
+#if 0
+/*** SSG group membership view access routines */
 
 // get my rank in the group
 int ssg_get_group_rank(const ssg_t s);
@@ -56,29 +116,6 @@ int ssg_get_group_size(const ssg_t s);
 
 // get the HG address for the group member at the given rank
 hg_addr_t ssg_get_addr(const ssg_t s, int rank);
-
-/// mercury support
-
-#if 0
-// group serialization mechanism
-hg_return_t hg_proc_ssg_t(hg_proc_t proc, ssg_t *s);
-
-/// utility functions
-
-// dump address list to the given file
-// returns -1 on error, corresponding to the return code of open/write/close,
-// and sets errno
-int ssg_dump(const ssg_t s, const char *fname);
-
-// set up barrier data structures. Separate call to resolve the margo -> barrier
-// race condition - call this before kicking off the progress loop with margo
-void ssg_register_barrier(ssg_t s, hg_class_t *hgcl);
-
-// perform a naive N-1 barrier using margo.
-// requires ssg_set_margo_id to have been called.
-// NOTE: rank must be set on all ranks prior to calling this. I.e. should init
-// the rank prior to starting up margo
-hg_return_t ssg_barrier_margo(ssg_t s);
 #endif
 
 #ifdef __cplusplus

src/ssg.c

@@ -19,12 +19,13 @@
 #include <margo.h>
 
 #include <ssg.h>
-#include "ssg-internal.h"
+//#include "ssg-internal.h"
 
 #if USE_SWIM_FD
 #include "swim-fd/swim-fd.h"
 #endif
 
+#if 0
 // internal initialization of ssg data structures
 static ssg_t ssg_init_internal(margo_instance_id mid, int self_rank,
     int group_size, hg_addr_t self_addr, char *addr_str_buf);
@@ -452,3 +453,4 @@ static char** setup_addr_str_list(int num_addrs, char * buf)
     }
     return ret;
 }
+#endif