ssg.h 5.06 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

#ifdef __cplusplus
extern "C" {
#endif

Shane Snyder's avatar
Shane Snyder committed
20
21
22
#ifdef HAVE_MPI
#include <mpi.h>
#endif
Jonathan Jenkins's avatar
Jonathan Jenkins committed
23

24
25
26
#include <mercury.h>
#include <margo.h>

Shane Snyder's avatar
Shane Snyder committed
27
28
/* SSG return codes */
#define SSG_SUCCESS 0
29
#define SSG_FAILURE (-1)
Shane Snyder's avatar
Shane Snyder committed
30

31
32
typedef uint64_t ssg_member_id_t;

33
34
35
36
37
38
39
40
41
42
43
44
/* SSG group identifier datatype */
/* TODO: this shouldn't be visible ... we can't use a typical
 * opaque pointer since we want to be able to xmit these to
 * other processes.
 */
#define SSG_GROUP_ID_MAX_ADDR_LEN 64
typedef struct ssg_group_id
{
    uint64_t magic_nr;
    uint64_t name_hash;
    char addr_str[SSG_GROUP_ID_MAX_ADDR_LEN];
} ssg_group_id_t;
Jonathan Jenkins's avatar
Jonathan Jenkins committed
45

Shane Snyder's avatar
Shane Snyder committed
46
47
48
/***************************************************
 *** SSG runtime intialization/shutdown routines ***
 ***************************************************/
Jonathan Jenkins's avatar
Jonathan Jenkins committed
49

Shane Snyder's avatar
Shane Snyder committed
50
51
/**
 * Initializes the SSG runtime environment.
52
 *
Shane Snyder's avatar
Shane Snyder committed
53
54
55
56
57
58
59
60
 * @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.
61
62
 *
 * @returns SSG_SUCCESS on success, SSG error code otherwise
Shane Snyder's avatar
Shane Snyder committed
63
 */
64
int ssg_finalize(
Shane Snyder's avatar
Shane Snyder committed
65
66
67
68
69
70
71
72
    void);

/*************************************
 *** SSG group management routines ***
 *************************************/

/**
 * Creates an SSG group from a given list of HG address strings.
73
74
75
76
77
78
 *
 * @param[in]  group_name       Name of the SSG group
 * @param[in]  group_addr_strs  Array of HG address strings for each group member
 * @param[in]  group_size       Number of group members
 * @param[out] group_id         Pointer to output SSG group ID
 * @returns SSG_SUCCESS on success, SSG error code otherwise
Shane Snyder's avatar
Shane Snyder committed
79
80
 *
 * NOTE: The HG address string of the caller of this function must be present in
81
82
 * 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
83
 */
84
int ssg_group_create(
85
86
    const char * group_name,
    const char * const group_addr_strs[],
87
88
    int group_size,
    ssg_group_id_t * group_id);
Shane Snyder's avatar
Shane Snyder committed
89
90
91
92

/**
 * Creates an SSG group from a given config file containing the HG address strings
 * of all group members.
93
94
95
 *
 * @param[in]  group_name   Name of the SSG group
 * @param[in]  file_name    Name of the config file containing the corresponding
Shane Snyder's avatar
Shane Snyder committed
96
 *                          HG address strings for this group
97
98
 * @param[out] group_id     Pointer to output SSG group ID
 * @returns SSG_SUCCESS on success, SSG error code otherwise
Shane Snyder's avatar
Shane Snyder committed
99
100
101
102
103
 * 
 * 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.
 */
104
int ssg_group_create_config(
105
    const char * group_name,
106
107
    const char * file_name,
    ssg_group_id_t * group_id);
Jonathan Jenkins's avatar
Jonathan Jenkins committed
108

Shane Snyder's avatar
Shane Snyder committed
109
#ifdef HAVE_MPI
Shane Snyder's avatar
Shane Snyder committed
110
111
/**
 * Creates an SSG group from a given MPI communicator.
112
113
114
115
116
 *
 * @param[in]  group_name   Name of the SSG group
 * @param[in]  comm         MPI communicator containing group members
 * @param[out] group_id     Pointer to output SSG group ID
 * @returns SSG_SUCCESS on success, SSG error code otherwise
Shane Snyder's avatar
Shane Snyder committed
117
 */
118
int ssg_group_create_mpi(
119
    const char * group_name,
120
121
    MPI_Comm comm,
    ssg_group_id_t * group_id);
Shane Snyder's avatar
Shane Snyder committed
122
123
#endif

Shane Snyder's avatar
Shane Snyder committed
124
125
/**
 * Destroys data structures associated with a given SSG group ID.
126
127
 *
 * @param[in] group_id SSG group ID
Shane Snyder's avatar
Shane Snyder committed
128
129
130
131
 * @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
132

133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
/**
 * Attaches a client to an SSG group.
 *
 * @param[in] group_id SSG group ID
 * @returns SSG_SUCCESS on success, SSG error code otherwise
 *
 * NOTE: The "client" cannot be a member of the group -- attachment is merely
 * a way of making the membership view of an existing SSG group available to
 * non-group members.
 */
int ssg_group_attach(
    ssg_group_id_t group_id);

/**
 * Detaches a client from an SSG group.
 *
 * @param[in] group_id SSG group ID
 * @returns SSG_SUCCESS on success, SSG error code otherwise
 */
int ssg_group_detach(
    ssg_group_id_t group_id);

155
156
157
/*********************************
 *** SSG group access routines ***
 *********************************/
Jonathan Jenkins's avatar
Jonathan Jenkins committed
158

159
160
161
162
163
164
165
166
/**
 * Obtains the caller's group rank in an SSG group.
 *
 * @param[in] group_id SSG group ID
 * @returns caller's group rank on success, SSG_RANK_UNKNOWN otherwise
 */
ssg_member_id_t ssg_get_group_self_id(
    ssg_group_id_t group_id);
Jonathan Jenkins's avatar
Jonathan Jenkins committed
167

168
169
170
171
172
173
174
175
/**
 * Obtains the size of an SSG group.
 *
 * @param[in] group_id SSG group ID
 * @returns size of the group on success, 0 otherwise
 */
int ssg_get_group_size(
    ssg_group_id_t group_id);
Jonathan Jenkins's avatar
Jonathan Jenkins committed
176

177
178
179
180
181
182
183
184
185
186
/**
 * Obtains the HG address of a given rank in an SSG group.
 *
 * @param[in] group_id  SSG group ID
 * @param[in] rank      SSG group rank 
 * @returns HG address of given group rank on success, HG_ADDR_NULL otherwise
 */
hg_addr_t ssg_get_addr(
    ssg_group_id_t group_id,
    ssg_member_id_t member_id);
Shane Snyder's avatar
Shane Snyder committed
187

Jonathan Jenkins's avatar
Jonathan Jenkins committed
188
189
190
#ifdef __cplusplus
}
#endif