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

Shane Snyder's avatar
Shane Snyder committed
31
#define SSG_MEMBER_ID_INVALID UINT64_MAX
32
33
typedef uint64_t ssg_member_id_t;

34
35
36
37
38
39
40
41
42
43
44
45
/* 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
46

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

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

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

/**
 * Creates an SSG group from a given list of HG address strings.
74
75
76
77
78
79
 *
 * @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
80
81
 *
 * NOTE: The HG address string of the caller of this function must be present in
82
83
 * 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
84
 */
85
int ssg_group_create(
86
87
    const char * group_name,
    const char * const group_addr_strs[],
88
89
    int group_size,
    ssg_group_id_t * group_id);
Shane Snyder's avatar
Shane Snyder committed
90
91
92
93

/**
 * Creates an SSG group from a given config file containing the HG address strings
 * of all group members.
94
95
96
 *
 * @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
97
 *                          HG address strings for this group
98
99
 * @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
100
101
102
103
104
 * 
 * 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.
 */
105
int ssg_group_create_config(
106
    const char * group_name,
107
108
    const char * file_name,
    ssg_group_id_t * group_id);
Jonathan Jenkins's avatar
Jonathan Jenkins committed
109

Shane Snyder's avatar
Shane Snyder committed
110
#ifdef HAVE_MPI
Shane Snyder's avatar
Shane Snyder committed
111
112
/**
 * Creates an SSG group from a given MPI communicator.
113
114
115
116
117
 *
 * @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
118
 */
119
int ssg_group_create_mpi(
120
    const char * group_name,
121
122
    MPI_Comm comm,
    ssg_group_id_t * group_id);
Shane Snyder's avatar
Shane Snyder committed
123
124
#endif

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

134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
/**
 * 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);

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

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

169
/**
Shane Snyder's avatar
Shane Snyder committed
170
 * Obtains the size of a given SSG group.
171
172
173
174
175
176
 *
 * @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
177

178
/**
Shane Snyder's avatar
Shane Snyder committed
179
 * Obtains the HG address of a member in a given SSG group.
180
181
 *
 * @param[in] group_id  SSG group ID
Shane Snyder's avatar
Shane Snyder committed
182
183
 * @param[in] member_id SSG group member ID
 * @returns HG address of given group member on success, HG_ADDR_NULL otherwise
184
185
186
187
 */
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
188

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