Commit 07775bdc authored by Shane Snyder's avatar Shane Snyder
Browse files

revamped SSG public interface

as bonus, added doxygen style comments
parent 96799c9a
......@@ -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
......
......@@ -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
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment