ssg.h 3.39 KB
Newer Older
Jonathan Jenkins's avatar
Jonathan Jenkins committed
1
2
3
4
5
6
7
8
/*
 * Copyright (c) 2016 UChicago Argonne, LLC
 *
 * See COPYRIGHT in top-level directory.
 */

#pragma once

Shane Snyder's avatar
Shane Snyder committed
9
10
11
12
13
14
/**
 * Scalable Service Groups (SSG) interface
 * 
 * An interface for creating and managing process groups using
 * Mercury and Argobots.
 */
Jonathan Jenkins's avatar
Jonathan Jenkins committed
15
16
17
18
19
20

#ifdef __cplusplus
extern "C" {
#endif

#include <mercury.h>
Shane Snyder's avatar
Shane Snyder committed
21
22
23
24
25
#include <margo.h>

#ifdef HAVE_MPI
#include <mpi.h>
#endif
Jonathan Jenkins's avatar
Jonathan Jenkins committed
26

Shane Snyder's avatar
Shane Snyder committed
27
28
29
30
/* SSG return codes */
#define SSG_SUCCESS 0
/* TODO: define some errors? */

31
#define SSG_GROUP_ID_NULL 0
Jonathan Jenkins's avatar
Jonathan Jenkins committed
32

Shane Snyder's avatar
Shane Snyder committed
33
34
/* XXX: actually define what these are */
typedef int ssg_group_id_t;
Jonathan Jenkins's avatar
Jonathan Jenkins committed
35

Shane Snyder's avatar
Shane Snyder committed
36
37
38
/***************************************************
 *** SSG runtime intialization/shutdown routines ***
 ***************************************************/
Jonathan Jenkins's avatar
Jonathan Jenkins committed
39

Shane Snyder's avatar
Shane Snyder committed
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
/**
 * 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.
60
61
62
63
 * @params[in] group_name       Name of the SSG group
 * @params[in] group_addr_strs  Array of HG address strings for each group member
 * @params[in] group_size       Number of group members
 * @returns SSG group ID on success, SSG_GROUP_ID_NULL otherwise
Shane Snyder's avatar
Shane Snyder committed
64
65
 *
 * NOTE: The HG address string of the caller of this function must be present in
66
67
 * the list of address strings given in 'group_addr_strs'. That is, the caller
 * of this function is required to be a member of the SSG group that is created.
Shane Snyder's avatar
Shane Snyder committed
68
69
 */
ssg_group_id_t ssg_group_create(
70
71
72
    const char * group_name,
    const char * const group_addr_strs[],
    int group_size);
Shane Snyder's avatar
Shane Snyder committed
73
74
75
76
77
78
79

/**
 * 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
80
 * @returns SSG group ID on success, SSG_GROUP_ID_NULL otherwise
Shane Snyder's avatar
Shane Snyder committed
81
82
83
84
85
86
 * 
 * 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(
87
88
    const char * group_name,
    const char * file_name);
Jonathan Jenkins's avatar
Jonathan Jenkins committed
89

Shane Snyder's avatar
Shane Snyder committed
90
#ifdef HAVE_MPI
Shane Snyder's avatar
Shane Snyder committed
91
92
93
94
/**
 * 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
95
 * @returns SSG group ID on success, SSG_GROUP_ID_NULL otherwise
Shane Snyder's avatar
Shane Snyder committed
96
97
 */
ssg_group_id_t ssg_group_create_mpi(
98
    const char * group_name,
Shane Snyder's avatar
Shane Snyder committed
99
    MPI_Comm comm);
Shane Snyder's avatar
Shane Snyder committed
100
101
#endif

Shane Snyder's avatar
Shane Snyder committed
102
103
104
105
106
107
108
/**
 * 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);
Jonathan Jenkins's avatar
Jonathan Jenkins committed
109

Shane Snyder's avatar
Shane Snyder committed
110
111
#if 0
/*** SSG group membership view access routines */
Jonathan Jenkins's avatar
Jonathan Jenkins committed
112

113
114
// get my rank in the group
int ssg_get_group_rank(const ssg_t s);
Jonathan Jenkins's avatar
Jonathan Jenkins committed
115

116
117
// get the size of the group
int ssg_get_group_size(const ssg_t s);
Jonathan Jenkins's avatar
Jonathan Jenkins committed
118

119
// get the HG address for the group member at the given rank
Jonathan Jenkins's avatar
Jonathan Jenkins committed
120
hg_addr_t ssg_get_addr(const ssg_t s, int rank);
121
#endif
Shane Snyder's avatar
Shane Snyder committed
122

Jonathan Jenkins's avatar
Jonathan Jenkins committed
123
124
125
#ifdef __cplusplus
}
#endif