ssg.h 4.5 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
/* SSG return codes */
#define SSG_SUCCESS 0
29
#define SSG_ERROR (-1)
Shane Snyder's avatar
Shane Snyder committed
30

31
32
33
34
35
36
37
38
39
40
41
42
/* 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
43

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

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

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

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

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

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

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

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

Shane Snyder's avatar
Shane Snyder committed
153
154
#if 0
/*** SSG group membership view access routines */
Jonathan Jenkins's avatar
Jonathan Jenkins committed
155

156
157
// get my rank in the group
int ssg_get_group_rank(const ssg_t s);
Jonathan Jenkins's avatar
Jonathan Jenkins committed
158

159
160
// get the size of the group
int ssg_get_group_size(const ssg_t s);
Jonathan Jenkins's avatar
Jonathan Jenkins committed
161

162
// get the HG address for the group member at the given rank
Jonathan Jenkins's avatar
Jonathan Jenkins committed
163
hg_addr_t ssg_get_addr(const ssg_t s, int rank);
164
#endif
Shane Snyder's avatar
Shane Snyder committed
165

Jonathan Jenkins's avatar
Jonathan Jenkins committed
166
167
168
#ifdef __cplusplus
}
#endif