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

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

#ifdef __cplusplus
extern "C" {
#endif

Shane Snyder's avatar
Shane Snyder committed
23 24
/* SSG return codes */
#define SSG_SUCCESS 0
25
#define SSG_FAILURE (-1)
Shane Snyder's avatar
Shane Snyder committed
26

27
typedef uint64_t ssg_member_id_t;
28
#define SSG_MEMBER_ID_INVALID UINT64_MAX
29

Shane Snyder's avatar
Shane Snyder committed
30 31 32
/* opaque SSG group identifier type */
typedef struct ssg_group_descriptor *ssg_group_id_t;
#define SSG_GROUP_ID_NULL ((ssg_group_id_t)NULL)
Jonathan Jenkins's avatar
Jonathan Jenkins committed
33

34 35 36
/* HG proc routine prototype for ssg_group_id_t */
hg_return_t hg_proc_ssg_group_id_t(hg_proc_t proc, void *data);

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

Shane Snyder's avatar
Shane Snyder committed
41 42
/**
 * Initializes the SSG runtime environment.
43
 *
Shane Snyder's avatar
Shane Snyder committed
44 45 46 47 48 49 50 51
 * @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.
52 53
 *
 * @returns SSG_SUCCESS on success, SSG error code otherwise
Shane Snyder's avatar
Shane Snyder committed
54
 */
55
int ssg_finalize(
Shane Snyder's avatar
Shane Snyder committed
56 57 58 59 60 61 62 63
    void);

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

/**
 * Creates an SSG group from a given list of HG address strings.
64
 *
65 66 67
 * @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
Shane Snyder's avatar
Shane Snyder committed
68
 * @returns SSG group identifier on success, SSG_GROUP_ID_NULL otherwise
Shane Snyder's avatar
Shane Snyder committed
69 70
 *
 * NOTE: The HG address string of the caller of this function must be present in
71 72
 * 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
73
 */
Shane Snyder's avatar
Shane Snyder committed
74
ssg_group_id_t ssg_group_create(
75 76
    const char * group_name,
    const char * const group_addr_strs[],
Shane Snyder's avatar
Shane Snyder committed
77
    int group_size);
Shane Snyder's avatar
Shane Snyder committed
78 79 80 81

/**
 * Creates an SSG group from a given config file containing the HG address strings
 * of all group members.
82
 *
83 84
 * @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
85
 *                          HG address strings for this group
Shane Snyder's avatar
Shane Snyder committed
86
 * @returns SSG group identifier on success, SSG_GROUP_ID_NULL otherwise
87
 *
Shane Snyder's avatar
Shane Snyder committed
88 89 90 91 92
 * 
 * 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
93
ssg_group_id_t ssg_group_create_config(
94
    const char * group_name,
Shane Snyder's avatar
Shane Snyder committed
95
    const char * file_name);
Jonathan Jenkins's avatar
Jonathan Jenkins committed
96

Shane Snyder's avatar
Shane Snyder committed
97 98
/**
 * Destroys data structures associated with a given SSG group ID.
99 100
 *
 * @param[in] group_id SSG group ID
Shane Snyder's avatar
Shane Snyder committed
101 102 103 104
 * @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
105

106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
/**
 * 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);

128 129 130
/*********************************
 *** SSG group access routines ***
 *********************************/
Jonathan Jenkins's avatar
Jonathan Jenkins committed
131

132
/**
Shane Snyder's avatar
Shane Snyder committed
133
 * Obtains the caller's member ID in the given SSG group.
134 135
 *
 * @param[in] group_id SSG group ID
136
 * @returns caller's group ID on success, SSG_MEMBER_ID_INVALID otherwise
137 138 139
 */
ssg_member_id_t ssg_get_group_self_id(
    ssg_group_id_t group_id);
Jonathan Jenkins's avatar
Jonathan Jenkins committed
140

141
/**
Shane Snyder's avatar
Shane Snyder committed
142
 * Obtains the size of a given SSG group.
143 144 145 146 147 148
 *
 * @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
149

150
/**
Shane Snyder's avatar
Shane Snyder committed
151
 * Obtains the HG address of a member in a given SSG group.
152 153
 *
 * @param[in] group_id  SSG group ID
Shane Snyder's avatar
Shane Snyder committed
154 155
 * @param[in] member_id SSG group member ID
 * @returns HG address of given group member on success, HG_ADDR_NULL otherwise
156 157 158 159
 */
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
160

161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183
/**
 * 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);

/** 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
184 185 186
#ifdef __cplusplus
}
#endif