swim-fd.h 4.33 KB
Newer Older
1
/*
Shane Snyder's avatar
Shane Snyder committed
2 3
 * Copyright (c) 2016 UChicago Argonne, LLC
 *
4 5 6
 * See COPYRIGHT in top-level directory.
 */

Shane Snyder's avatar
Shane Snyder committed
7
#pragma once
8

Shane Snyder's avatar
Shane Snyder committed
9 10
#include <stdint.h>
#include <inttypes.h>
11

12 13 14 15 16 17 18
#ifdef __cplusplus
extern "C" {
#endif

/* opaque swim context type */
typedef struct swim_context swim_context_t;

Shane Snyder's avatar
Shane Snyder committed
19
/* swim member specific types */
20
typedef uint64_t swim_member_id_t;
Shane Snyder's avatar
Shane Snyder committed
21 22 23 24 25 26 27 28
typedef uint32_t swim_member_inc_nr_t;
typedef enum swim_member_status
{
    SWIM_MEMBER_ALIVE = 0,
    SWIM_MEMBER_SUSPECT,
    SWIM_MEMBER_DEAD
} swim_member_status_t;

29
/* SWIM state associated with each group member */
Shane Snyder's avatar
Shane Snyder committed
30 31 32 33 34 35
typedef struct swim_member_state
{
    swim_member_inc_nr_t inc_nr;
    swim_member_status_t status;
} swim_member_state_t;

36
/* SWIM protocol update */
37 38 39 40 41 42
typedef struct swim_member_update
{
    swim_member_id_t id;
    swim_member_state_t state;
} swim_member_update_t;

43 44 45 46 47
#define SWIM_MEMBER_STATE_INIT(__ms) do { \
    __ms.inc_nr = 0; \
    __ms.status = SWIM_MEMBER_ALIVE; \
} while(0)

48
/* SWIM callbacks for integrating with an overlying group management layer */
49 50
typedef struct swim_group_mgmt_callbacks
{
51 52 53 54 55 56 57 58 59 60 61 62
    /**
     * Retrieve a (non-dead) random group member from the group
     * management layer to send a direct ping request to.
     * NOTE: to ensure time-bounded detection of faulty members,
     * round-robin selection of members is required.
     *
     * @param[in]  group_data   void pointer to group managment data
     * @param[out] target_id    ID of selected direct ping target
     * @param[out] inc_nr       SWIM incarnation number of target
     * @param[out] target_addr  HG address of target
     * @returns 1 on successful selection of a target, 0 if no targets available
     */
63 64
    int (*get_dping_target)(
            void *group_data,
Shane Snyder's avatar
Shane Snyder committed
65 66 67 68
            swim_member_id_t *target_id,
            swim_member_inc_nr_t *inc_nr,
            hg_addr_t *target_addr
            );
69 70 71 72 73 74 75 76 77
    /**
     * Retrieve a set of (non-dead) random group members from the group
     * management layer to send indirect ping requests to.
     *
     * @param[in]  group_data       void pointer to group managment data
     * @param[out] target_ids       IDs of selected indirect ping targets
     * @param[out] target_addrs     HG addresses of targets
     * @returns number of selected indirect ping targets, 0 if no targets available
     */
Shane Snyder's avatar
Shane Snyder committed
78 79 80 81 82
    int (*get_iping_targets)(
            void *group_data,
            swim_member_id_t *target_ids,
            hg_addr_t *target_addrs
            );
83 84 85 86 87 88 89
    /**
     * Get the HG address corresponding to a given member ID.
     *
     * @param[in]  group_data   void pointer to group managment data
     * @param[in]  id           member ID to query
     * @param[out] addr         HG address of given member
     */
Shane Snyder's avatar
Shane Snyder committed
90 91 92 93 94
    void (*get_member_addr)(
            void *group_data,
            swim_member_id_t id,
            hg_addr_t *addr
            );
95 96 97 98 99 100 101
    /**
     * Get the SWIM protocol state corresponding to a given member ID.
     *
     * @param[in]  group_data   void pointer to group managment data
     * @param[in]  id           member ID to query
     * @param[out] state        pointer to given member's SWIM state
     */
Shane Snyder's avatar
Shane Snyder committed
102 103 104 105
    void (*get_member_state)(
            void *group_data,
            swim_member_id_t id,
            swim_member_state_t **state
106
            );
107 108 109 110 111 112
    /**
     * Apply a SWIM protocol update in the group management layer.
     *
     * @param[in] group_data    void pointer to group managment data
     * @param[in] update        SWIM member update to apply to group
     */
113 114 115 116
    void (*apply_member_update)(
            void *group_data,
            swim_member_update_t update
            );
117 118
} swim_group_mgmt_callbacks_t;

119 120 121 122 123 124 125 126 127 128
/**
 * Initialize the SWIM protocol.
 *
 * @param[in] mid               Margo instance ID
 * @param[in] group_data        void pointer to group management data
 * @param[in] self_id           ID
 * @param[in] swim_callbacks    SWIM callbacks to group management layer
 * @param[in] active            boolean value indicating whether member should actively ping
 * @returns SWIM context pointer on success, NULL otherwise
 */
129
swim_context_t * swim_init(
130
    margo_instance_id mid,
Shane Snyder's avatar
Shane Snyder committed
131
    void * group_data,
132
    swim_member_id_t self_id,
133
    swim_group_mgmt_callbacks_t swim_callbacks,
134 135
    int active);

136 137 138 139 140
/**
 * Finalize the SWIM protocol.
 *
 * @param[in] swim_ctx  SWIM context pointer
 */
141
void swim_finalize(
142
    swim_context_t * swim_ctx);
143 144 145 146

#ifdef __cplusplus
}
#endif