margo.h 5.88 KB
Newer Older
1 2 3 4 5 6 7 8 9
/*
 * (C) 2015 The University of Chicago
 * 
 * See COPYRIGHT in top-level directory.
 */

#ifndef __MARGO
#define __MARGO

10 11 12 13
#ifdef __cplusplus
extern "C" {
#endif

14 15 16 17 18 19
#include <mercury_bulk.h>
#include <mercury.h>
#include <mercury_macros.h>
#include <abt.h>
#include <ev.h>

20 21 22
struct margo_instance;
typedef struct margo_instance* margo_instance_id;

23 24
#define MARGO_INSTANCE_NULL ((margo_instance_id)NULL)

25
/**
Jonathan Jenkins's avatar
doc fix  
Jonathan Jenkins committed
26
 * Initializes margo library from given argobots and Mercury instances.
Philip Carns's avatar
Philip Carns committed
27 28 29
 * @param [in] progress_pool Argobots pool to drive communication
 * @param [in] handler_pool Argobots pool to service RPC handlers
 * @param [in] hg_context Mercury context
Jonathan Jenkins's avatar
fixupme  
Jonathan Jenkins committed
30
 * @returns margo instance id on success, MARGO_INSTANCE_NULL upon error
31
 */
32
margo_instance_id margo_init(ABT_pool progress_pool, ABT_pool handler_pool,
Jonathan Jenkins's avatar
Jonathan Jenkins committed
33
    hg_context_t *hg_context);
34 35 36

/**
 * Shuts down margo library and its underlying evfibers and mercury resources
Philip Carns's avatar
Philip Carns committed
37
 * @param [in] mid Margo instance
38
 */
39
void margo_finalize(margo_instance_id mid);
40 41 42 43 44 45 46 47 48 49 50 51

/**
 * Suspends the caller until some other entity (e.g. an RPC, thread, or
 * signal handler) invokes margo_finalize().
 *
 * NOTE: This informs Margo that the calling thread no longer needs to be 
 * scheduled for execution if it is sharing an Argobots pool with the
 * progress engine.
 *
 * @param [in] mid Margo instance
 */
void margo_wait_for_finalize(margo_instance_id mid);
52 53

/**
Philip Carns's avatar
Philip Carns committed
54 55 56
 * Retrieve the abt_handler pool that was associated with the instance at 
 *    initialization time
 * @param [in] mid Margo instance
57
 */
58
ABT_pool* margo_get_handler_pool(margo_instance_id mid);
59

60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
/**
 * Retrieve the Mercury context that was associated with this instance at
 *    initialization time
 * @param [in] mid Margo instance
 * @return the Mercury context used in margo_init
 */
hg_context_t* margo_get_context(margo_instance_id mid);

/**
 * Retrieve the Mercury class that was associated with this instance at
 *    initialization time
 * @param [in] mid Margo instance
 * @return the Mercury class used in margo_init
 */
hg_class_t* margo_get_class(margo_instance_id mid);

76 77
/**
 * Forward an RPC request to a remote host
Philip Carns's avatar
Philip Carns committed
78
 * @param [in] mid Margo instance
79 80 81 82 83
 * @param [in] handle identifier for the RPC to be sent
 * @param [in] in_struct input argument struct for RPC
 * @returns 0 on success, hg_return_t values on error
 */
hg_return_t margo_forward(
84
    margo_instance_id mid,
85 86 87
    hg_handle_t handle,
    void *in_struct);

88 89 90 91 92 93 94 95 96 97 98 99 100 101
/**
 * Forward an RPC request to a remote host with a user-defined timeout
 * @param [in] mid Margo instance
 * @param [in] handle identifier for the RPC to be sent
 * @param [in] in_struct input argument struct for RPC
 * @param [in] timeout_ms timeout in milliseconds
 * @returns 0 on success, hg_return_t values on error
 */
hg_return_t margo_forward_timed(
    margo_instance_id mid,
    hg_handle_t handle,
    void *in_struct,
    double timeout_ms);

Jonathan Jenkins's avatar
Jonathan Jenkins committed
102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
/**
 * Send an RPC response, waiting for completion before returning
 * control to the calling ULT.
 * Note: this call is typically not needed as RPC listeners need not concern
 * themselves with what happens after an RPC finishes. However, there are cases
 * when this is useful (deferring resource cleanup, calling margo_finalize()
 * for e.g. a shutdown RPC).
 * @param [in] mid Margo instance
 * @param [in] handle identifier for the RPC for which a response is being
 * sent
 * @param [in] out_struct output argument struct for response
 * @return HG_SUCCESS on success, hg_return_t values on error. See HG_Respond.
 */
hg_return_t margo_respond(
    margo_instance_id mid,
    hg_handle_t handle,
    void *out_struct);

120 121
/** 
 * Perform a bulk transfer
Philip Carns's avatar
Philip Carns committed
122
 * @param [in] mid Margo instance
123 124 125 126 127 128 129 130 131 132
 * @param [in] op type of operation to perform
 * @param [in] origin_addr remote Mercury address
 * @param [in] origin_handle remote Mercury bulk memory handle
 * @param [in] origin_offset offset into remote bulk memory to access
 * @param [in] local_handle local bulk memory handle
 * @param [in] local_offset offset into local bulk memory to access
 * @param [in] size size (in bytes) of transfer
 * @returns 0 on success, hg_return_t values on error
 */
hg_return_t margo_bulk_transfer(
133
    margo_instance_id mid,
134
    hg_bulk_op_t op,
135
    hg_addr_t origin_addr,
136 137 138 139 140 141
    hg_bulk_t origin_handle,
    size_t origin_offset,
    hg_bulk_t local_handle,
    size_t local_offset,
    size_t size);

142 143 144
/**
 * address lookup
 * @param [in] name             lookup name
Jonathan Jenkins's avatar
fixupme  
Jonathan Jenkins committed
145 146
 * @param [out] addr            return address
 * @returns HG_SUCCESS on success
147
 */
148
hg_return_t margo_addr_lookup(
149
    margo_instance_id mid,
Philip Carns's avatar
Philip Carns committed
150
    const char   *name,
151
    hg_addr_t    *addr);
152

153 154
/**
 * Suspends the calling ULT for a specified time duration
155
 * @param [in] mid Margo instance
156 157 158
 * @param [in] timeout_ms timeout duration in milliseconds
 */
void margo_thread_sleep(
159
    margo_instance_id mid,
160 161
    double timeout_ms);

Philip Carns's avatar
Philip Carns committed
162 163
/**
 * Retrive the Margo instance that has been associated with a Mercury class
164
 * @param [in] cl Mercury class
Philip Carns's avatar
Philip Carns committed
165
 * @returns Margo instance on success, NULL on error
166
 */
167
margo_instance_id margo_hg_class_to_instance(hg_class_t *cl);
168

169 170 171 172
/**
 * macro that defines a function to glue an RPC handler to a fiber
 * @param [in] __name name of handler function
 */
173
#define DEFINE_MARGO_RPC_HANDLER(__name) \
174
hg_return_t __name##_handler(hg_handle_t handle) { \
175 176
    int __ret; \
    ABT_pool* __pool; \
177 178 179 180
    margo_instance_id __mid; \
    struct hg_info *__hgi; \
    __hgi = HG_Get_info(handle); \
    __mid = margo_hg_class_to_instance(__hgi->hg_class); \
181
    __pool = margo_get_handler_pool(__mid); \
182
    __ret = ABT_thread_create(*__pool, __name, handle, ABT_THREAD_ATTR_NULL, NULL); \
183 184 185 186 187 188
    if(__ret != 0) { \
        return(HG_NOMEM_ERROR); \
    } \
    return(HG_SUCCESS); \
}

Philip Carns's avatar
Philip Carns committed
189 190 191 192 193
/**
 * macro that declares the prototype for a function to glue an RPC 
 * handler to a fiber
 * @param [in] __name name of handler function
 */
194
#define DECLARE_MARGO_RPC_HANDLER(__name) hg_return_t __name##_handler(hg_handle_t handle);
195

196 197 198 199
#ifdef __cplusplus
}
#endif

200
#endif /* __MARGO */