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

9 10 11
#include <mercury.h>
#include <margo.h>

12 13 14
#include <stdint.h>
#include <inttypes.h>

Shane Snyder's avatar
Shane Snyder committed
15
/** @file ssg.h
Shane Snyder's avatar
Shane Snyder committed
16 17 18 19 20
 * Scalable Service Groups (SSG) interface
 * 
 * An interface for creating and managing process groups using
 * Mercury and Argobots.
 */
Jonathan Jenkins's avatar
Jonathan Jenkins committed
21 22 23 24 25

#ifdef __cplusplus
extern "C" {
#endif

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

30 31 32 33 34
/* opaque SSG group ID type */
typedef struct ssg_group_descriptor *ssg_group_id_t;
#define SSG_GROUP_ID_NULL ((ssg_group_id_t)NULL)

/* SSG group member ID type */
35
typedef uint64_t ssg_member_id_t;
36
#define SSG_MEMBER_ID_INVALID 0
37

38 39 40 41 42 43 44
/* SSG group member update types */
enum ssg_membership_update_type
{
    SSG_MEMBER_ADD = 0,
    SSG_MEMBER_REMOVE
};

45
typedef struct ssg_member_update
46
{
47
    ssg_member_id_t id;
48
    int type;
49
} ssg_member_update_t;
50 51

typedef void (*ssg_membership_update_cb)(
52
    ssg_member_update_t, void *);
Jonathan Jenkins's avatar
Jonathan Jenkins committed
53

54 55
/* HG proc routine prototypes for SSG types */
#define hg_proc_ssg_member_id_t hg_proc_int64_t
56 57
hg_return_t hg_proc_ssg_group_id_t(hg_proc_t proc, void *data);

Shane Snyder's avatar
Shane Snyder committed
58 59 60
/***************************************************
 *** SSG runtime intialization/shutdown routines ***
 ***************************************************/
Jonathan Jenkins's avatar
Jonathan Jenkins committed
61

Shane Snyder's avatar
Shane Snyder committed
62 63
/**
 * Initializes the SSG runtime environment.
64
 *
Shane Snyder's avatar
Shane Snyder committed
65 66 67 68 69 70 71 72
 * @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.
73 74
 *
 * @returns SSG_SUCCESS on success, SSG error code otherwise
Shane Snyder's avatar
Shane Snyder committed
75
 */
76
int ssg_finalize(
Shane Snyder's avatar
Shane Snyder committed
77 78 79 80 81 82 83 84
    void);

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

/**
 * Creates an SSG group from a given list of HG address strings.
85
 *
86 87 88
 * @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
89 90
 * @param[in] update_cb         Callback function executed on group membership changes
 * @param[in] update_cb_dat     User data pointer passed to membership update callback
Shane Snyder's avatar
Shane Snyder committed
91
 * @returns SSG group identifier on success, SSG_GROUP_ID_NULL otherwise
Shane Snyder's avatar
Shane Snyder committed
92 93
 *
 * NOTE: The HG address string of the caller of this function must be present in
94 95
 * 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
96
 */
Shane Snyder's avatar
Shane Snyder committed
97
ssg_group_id_t ssg_group_create(
98 99
    const char * group_name,
    const char * const group_addr_strs[],
100 101 102
    int group_size,
    ssg_membership_update_cb update_cb,
    void * update_cb_dat);
Shane Snyder's avatar
Shane Snyder committed
103 104 105 106

/**
 * Creates an SSG group from a given config file containing the HG address strings
 * of all group members.
107
 *
108 109
 * @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
110
 *                          HG address strings for this group
111 112
 * @param[in] update_cb         Callback function executed on group membership changes
 * @param[in] update_cb_dat     User data pointer passed to membership update callback
Shane Snyder's avatar
Shane Snyder committed
113
 * @returns SSG group identifier on success, SSG_GROUP_ID_NULL otherwise
114
 *
Shane Snyder's avatar
Shane Snyder committed
115 116 117 118 119
 * 
 * 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.
 */
Shane Snyder's avatar
Shane Snyder committed
120
ssg_group_id_t ssg_group_create_config(
121
    const char * group_name,
122 123 124
    const char * file_name,
    ssg_membership_update_cb update_cb,
    void * update_cb_dat);
Jonathan Jenkins's avatar
Jonathan Jenkins committed
125

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

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

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

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

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

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

190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205
/**
 * Duplicates the given SSG group identifier.
 *
 * @param[in] group_id SSG group ID
 * @returns SSG group identifier on success, SSG_GROUP_ID_NULL otherwise
 */
ssg_group_id_t ssg_group_id_dup(
    ssg_group_id_t group_id);

/** Frees the given SSG group identifier.
 *
 * @param[in] group_id SSG group ID
 */
void ssg_group_id_free(
    ssg_group_id_t group_id);

206 207 208 209 210 211 212 213 214 215 216
/**
 * Retrieves the HG address string associated with an SSG group identifier.
 *
 * @param[in] group_id SSG group ID
 * @returns address string on success, NULL otherwise
 * 
 * NOTE: returned string must be freed by caller.
 */
char *ssg_group_id_get_addr_str(
    ssg_group_id_t group_id);

217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260
/**
 * Serializes an SSG group identifier into a buffer.
 *
 * @param[in]   group_id    SSG group ID
 * @param[out]  buf_p       Pointer to store allocated buffer in
 * @param[out]  buf_size_p  Pointer to store buffer size in
 */
void ssg_group_id_serialize(
    ssg_group_id_t group_id,
    char ** buf_p,
    size_t * buf_size_p);

/**
 * Deserializes an SSG group identifier from a buffer.
 *
 * @param[in]   buf         Buffer containing the SSG group identifier
 * @param[in]   buf_size    Size of given buffer
 * @param[out]  group_id_p  Pointer to store group identifier in
 */
void ssg_group_id_deserialize(
    const char * buf,
    size_t buf_size,
    ssg_group_id_t * group_id_p);

/**
 * Stores an SSG group identifier in the given file name.
 *
 * @param[in]   file_name   File to store the group ID in
 * @param[in]   group_id    SSG group ID
 */
int ssg_group_id_store(
    const char * file_name,
    ssg_group_id_t group_id);

/**
 * Loads an SSG group identifier from the given file name.
 *
 * @param[in]   file_name   File to store the group ID in
 * @param[out]  group_id_p  Pointer to store group identifier in
 */
int ssg_group_id_load(
    const char * file_name,
    ssg_group_id_t * group_id_p);

261 262 263 264 265 266 267
/** Dumps details of caller's membership in a given group to stdout.
 *
 * @param[in] group_id SSG group ID
 */
void ssg_group_dump(
    ssg_group_id_t group_id);

Jonathan Jenkins's avatar
Jonathan Jenkins committed
268 269 270
#ifdef __cplusplus
}
#endif