Commit bbe73599 authored by Shane Snyder's avatar Shane Snyder
Browse files

first cut at wrapping important parts of HG iface

parent 9bd02ac2
......@@ -76,7 +76,8 @@ margo_instance_id margo_init_pool(
* Shuts down margo library and its underlying abt and mercury resources
* @param [in] mid Margo instance
*/
void margo_finalize(margo_instance_id mid);
void margo_finalize(
margo_instance_id mid);
/**
* Suspends the caller until some other entity (e.g. an RPC, thread, or
......@@ -88,44 +89,65 @@ void margo_finalize(margo_instance_id mid);
*
* @param [in] mid Margo instance
*/
void margo_wait_for_finalize(margo_instance_id mid);
void margo_wait_for_finalize(
margo_instance_id mid);
/**
* Registers an RPC with margo
* @param [in] mid Margo instance
* @param [in] id Mercury RPC identifier
*
* \param [in] mid Margo instance
* \param [in] func_name unique function name for RPC
* \param [in] in_proc_cb pointer to input proc callback
* \param [in] out_proc_cb pointer to output proc callback
* \param [in] rpc_cb RPC callback
*
* \return unique ID associated to the registered function
*/
int margo_register(margo_instance_id mid, hg_id_t id);
hg_id_t margo_register_name(
margo_instance_id mid,
const char *func_name,
hg_proc_cb_t in_proc_cb,
hg_proc_cb_t out_proc_cb,
hg_rpc_cb_t rpc_cb);
/**
* Registers an RPC with margo that is associated with a multiplexed service
* @param [in] mid Margo instance
* @param [in] id Mercury RPC identifier
* @param [in] mplex_id multiplexing identifier
* @param [in] pool Argobots pool the handler will execute in
*
* \param [in] mid Margo instance
* \param [in] func_name unique function name for RPC
* \param [in] in_proc_cb pointer to input proc callback
* \param [in] out_proc_cb pointer to output proc callback
* \param [in] rpc_cb RPC callback
* \param [in] mplex_id multiplexing identifier
* \param [in] pool Argobots pool the handler will execute in
*
* \return unique ID associated to the registered function
*/
int margo_register_mplex(margo_instance_id mid, hg_id_t id, uint32_t mplex_id, ABT_pool pool);
hg_id_t margo_register_name_mplex(
margo_instance_id mid,
const char *func_name,
hg_proc_cb_t in_proc_cb,
hg_proc_cb_t out_proc_cb,
hg_rpc_cb_t rpc_cb,
uint32_t mplex_id,
ABT_pool pool);
/*
* Indicate whether HG_Register_name() has been called for the RPC specified by
* Indicate whether margo_register_name() has been called for the RPC specified by
* func_name.
*
* \param hg_class [IN] pointer to HG class
* \param func_name [IN] function name
* \param id [OUT] registered RPC ID
* \param flag [OUT] pointer to boolean
* \param [in] mid Margo instance
* \param [in] func_name function name
* \param [out] id registered RPC ID
* \param [out] flag pointer to boolean
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Registered_name(
hg_class_t *hg_class,
const char *func_name,
hg_id_t *id,
hg_bool_t *flag
);
*/
hg_return_t margo_registered_name(
margo_instance_id mid,
const char *func_name,
hg_id_t *id,
hg_bool_t *flag);
/**
* Register and associate user data to registered function.
......@@ -154,264 +176,192 @@ hg_return_t margo_register_data(
*
* \return Pointer to data or NULL
*/
void* margo_registered_data(margo_instance_id mid, hg_id_t id);
void* margo_registered_data(
margo_instance_id mid,
hg_id_t id);
/**
* Disable response for a given RPC ID. This allows an origin process to send an
* RPC to a target without waiting for a response. The RPC completes locally and
* the callback on the origin is therefore pushed to the completion queue once
* the RPC send is completed. By default, all RPCs expect a response to
* be sent back.
* Disable response for a given RPC ID.
*
* \param hg_class [IN] pointer to HG class
* \param id [IN] registered function ID
* \param disable [IN] boolean (HG_TRUE to disable
* HG_FALSE to re-enable)
* \param [in] mid Margo instance
* \param [in] id registered function ID
* \param [in] disable_flag flag to disable (1) or re-enable (0) responses
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Registered_disable_response(
hg_class_t *hg_class,
hg_id_t id,
hg_bool_t disable
);
*/
hg_return_t margo_registered_disable_response(
margo_instance_id mid,
hg_id_t id,
int disable_flag);
/**
* Lookup an addr from a peer address/name.
* @param [in] name lookup name
* @param [out] addr return address
* @returns HG_SUCCESS on success
* \param [in] name lookup name
* \param [out] addr return address
*
* \return HG_SUCCESS or corresponding HG error code
*/
hg_return_t margo_addr_lookup(
margo_instance_id mid,
const char *name,
hg_addr_t *addr);
const char *name,
hg_addr_t *addr);
/**
* Free the addr from the list of peers.
* Free the given Mercury addr.
*
* \param hg_class [IN] pointer to HG class
* \param addr [IN] abstract address
* \param [in] mid Margo instance
* \param [in] addr Mercury address
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Addr_free(
hg_class_t *hg_class,
hg_addr_t addr
);
*/
hg_return_t margo_addr_free(
margo_instance_id mid,
hg_addr_t addr);
/**
* Access self address. Address must be freed with HG_Addr_free().
* Access self address. Address must be freed with margo_addr_free().
*
* \param hg_class [IN] pointer to HG class
* \param addr [OUT] pointer to abstract address
* \param [in] mid Margo instance
* \param [in] addr pointer to abstract Mercury address
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Addr_self(
hg_class_t *hg_class,
hg_addr_t *addr
);
*/
hg_return_t margo_addr_self(
margo_instance_id mid,
hg_addr_t *addr);
/**
* Duplicate an existing HG abstract address. The duplicated address can be
* stored for later use and the origin address be freed safely. The duplicated
* address must be freed with HG_Addr_free().
* Duplicate an existing Mercury address.
*
* \param hg_class [IN] pointer to HG class
* \param addr [IN] abstract address
* \param new_addr [OUT] pointer to abstract address
* \param [in] mid Margo instance
* \param [in] addr abstract Mercury address to duplicate
* \param [in] new_addr pointer to newly allocated abstract Mercury address
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Addr_dup(
hg_class_t *hg_class,
hg_addr_t addr,
hg_addr_t *new_addr
);
*/
hg_return_t margo_addr_dup(
margo_instance_id mid,
hg_addr_t addr,
hg_addr_t *new_addr);
/**
* Convert an addr to a string (returned string includes the terminating
* null byte '\0'). If buf is NULL, the address is not converted and only
* the required size of the buffer is returned. If the input value passed
* through buf_size is too small, HG_SIZE_ERROR is returned and the buf_size
* output is set to the minimum size required.
* Convert a Mercury addr to a string (returned string includes the
* terminating null byte '\0'). If buf is NULL, the address is not
* converted and only the required size of the buffer is returned.
* If the input value passed through buf_size is too small, HG_SIZE_ERROR
* is returned and the buf_size output is set to the minimum size required.
*
* \param hg_class [IN] pointer to HG class
* \param buf [IN/OUT] pointer to destination buffer
* \param buf_size [IN/OUT] pointer to buffer size
* \param addr [IN] abstract address
* \param [in] mid Margo instance
* \param [in/out] buf pointer to destination buffer
* \param [in/out] buf_size pointer to buffer size
* \param [in] addr abstract Mercury address
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Addr_to_string(
hg_class_t *hg_class,
char *buf,
hg_size_t *buf_size,
hg_addr_t addr
);
*/
hg_return_t margo_addr_to_string(
margo_instance_id mid,
char *buf,
hg_size_t *buf_size,
hg_addr_t addr);
/**
* Initiate a new HG RPC using the specified function ID and the local/remote
* target defined by addr. The HG handle created can be used to query input
* and output, as well as issuing the RPC by calling HG_Forward().
* After completion the handle must be freed using HG_Destroy().
* Initiate a new Mercury RPC using the specified function ID and the
* local/remote target defined by addr. The handle created can be used to
* query input and output, as well as issuing the RPC by calling
* HG_Forward(). After completion the handle must be freed using HG_Destroy().
*
* \param context [IN] pointer to HG context
* \param addr [IN] abstract network address of destination
* \param id [IN] registered function ID
* \param handle [OUT] pointer to HG handle
* \param [in] mid Margo instance
* \param [in] addr abstract Mercury address of destination
* \param [in] id registered function ID
* \param [out] handle pointer to HG handle
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Create(
hg_context_t *context,
hg_addr_t addr,
hg_id_t id,
hg_handle_t *handle
);
*/
hg_return_t margo_create(
margo_instance_id mid,
hg_addr_t addr,
hg_id_t id,
hg_handle_t *handle);
/**
* Destroy HG handle. Decrement reference count, resources associated to the
* handle are freed when the reference count is null.
* Destroy Mercury handle.
*
* \param handle [IN] HG handle
* \param [in] handle Mercury handle
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Destroy(
hg_handle_t handle
);
*/
hg_return_t margo_destroy(
hg_handle_t handle);
/**
* Increment ref count on handle.
* Increment ref count on a Mercury handle.
*
* \param handle [IN] HG handle
* \param [in] handle Mercury handle
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Ref_incr(
hg_handle_t hg_handle
);
*/
hg_return_t margo_ref_incr(
hg_handle_t handle);
/**
* Get info from handle.
*
* \remark Users must call HG_Addr_dup() to safely re-use the addr field.
*
* \param handle [IN] HG handle
* \param [in] handle Mercury handle
*
* \return Pointer to info or NULL in case of failure
*/
/* XXX
HG_EXPORT const struct hg_info *
HG_Get_info(
hg_handle_t handle
);
*/
const struct hg_info *margo_get_info(
hg_handle_t handle);
/**
* Get input from handle (requires registration of input proc to deserialize
* parameters). Input must be freed using HG_Free_input().
* parameters). Input must be freed using margo_free_input().
*
* \remark This is equivalent to:
* - HG_Core_get_input()
* - Call hg_proc to deserialize parameters
*
* \param handle [IN] HG handle
* \param in_struct [IN/OUT] pointer to input structure
* \param [in] handle Mercury handle
* \param [in/out] in_struct pointer to input structure
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Get_input(
hg_handle_t handle,
void *in_struct
);
*/
hg_return_t margo_get_input(
hg_handle_t handle,
void *in_struct);
/**
* Free resources allocated when deserializing the input.
* User may copy parameters contained in the input structure before calling
* HG_Free_input().
*
* \param handle [IN] HG handle
* \param in_struct [IN/OUT] pointer to input structure
* \param [in] handle Mercury handle
* \param [in/out] in_struct pointer to input structure
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Free_input(
hg_return_t margo_free_input(
hg_handle_t handle,
void *in_struct
);
*/
void *in_struct);
/**
* Get output from handle (requires registration of output proc to deserialize
* parameters). Output must be freed using HG_Free_output().
*
* \remark This is equivalent to:
* - HG_Core_get_output()
* - Call hg_proc to deserialize parameters
* parameters). Output must be freed using margo_free_output().
*
*
* \param handle [IN] HG handle
* \param out_struct [IN/OUT] pointer to output structure
* \param [in] handle Mercury handle
* \param [in/out] out_struct pointer to output structure
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Get_output(
hg_handle_t handle,
void *out_struct
);
*/
hg_return_t margo_get_output(
hg_handle_t handle,
void *out_struct);
/**
* Free resources allocated when deserializing the output.
* User may copy parameters contained in the output structure before calling
* HG_Free_output().
*
* \param handle [IN] HG handle
* \param out_struct [IN/OUT] pointer to input structure
* \param [in] handle Mercury handle
* \param [in/out] out_struct pointer to output structure
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Free_output(
hg_handle_t handle,
void *out_struct
);
*/
hg_return_t margo_free_output(
hg_handle_t handle,
void *out_struct);
/**
* Forward an RPC request to a remote host
......@@ -460,16 +410,154 @@ hg_return_t margo_respond(
/**
* Cancel an ongoing operation.
*
* \param handle [IN] HG handle
* \param [in] handle Mercury handle
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Cancel(
hg_handle_t handle
);
*/
hg_return_t margo_cancel(
hg_handle_t handle);
/**
* Create an abstract bulk handle from specified memory segments.
* Memory allocated is then freed when margo_bulk_free() is called.
* \remark If NULL is passed to buf_ptrs, i.e.,
* \verbatim margo_bulk_create(mid, count, NULL, buf_sizes, flags, &handle) \endverbatim
* memory for the missing buf_ptrs array will be internally allocated.
*
* \param [in] mid Margo instance
* \param [in] count number of segments
* \param [in] buf_ptrs array of pointers
* \param [in] buf_sizes array of sizes
* \param [in] flags permission flag:
* - HG_BULK_READWRITE
* - HG_BULK_READ_ONLY
* - HG_BULK_WRITE_ONLY
* \param [out] handle pointer to returned abstract bulk handle
*
* \return HG_SUCCESS or corresponding HG error code
*/
hg_return_t margo_bulk_create(
margo_instance_id mid,
hg_uint32_t count,
void **buf_ptrs,
const hg_size_t *buf_sizes,
hg_uint8_t flags,
hg_bulk_t *handle);
/**
* Free bulk handle.
*
* \param [in/out] handle abstract bulk handle
*
* \return HG_SUCCESS or corresponding HG error code
*/
hg_return_t margo_bulk_free(
hg_bulk_t handle);
/**
* Increment ref count on bulk handle.
*
* \param handle [IN] abstract bulk handle
*
* \return HG_SUCCESS or corresponding HG error code
*/
hg_return_t margo_bulk_ref_incr(
hg_bulk_t handle);
/**
* Access bulk handle to retrieve memory segments abstracted by handle.
*
* \param [in] handle abstract bulk handle
* \param [in] offset bulk offset
* \param [in] size bulk size
* \param [in] flags permission flag:
* - HG_BULK_READWRITE
* - HG_BULK_READ_ONLY
* \param [in] max_count maximum number of segments to be returned
* \param [in/out] buf_ptrs array of buffer pointers
* \param [in/out] buf_sizes array of buffer sizes
* \param [out] actual_count actual number of segments returned
*
* \return HG_SUCCESS or corresponding HG error code
*/
hg_return_t margo_bulk_access(
hg_bulk_t handle,
hg_size_t offset,
hg_size_t size,
hg_uint8_t flags,
hg_uint32_t max_count,
void **buf_ptrs,
hg_size_t *buf_sizes,
hg_uint32_t *actual_count);
/**
* Get total size of data abstracted by bulk handle.
*
* \param [in] handle abstract bulk handle
*
* \return Non-negative value
*/
hg_size_t margo_bulk_get_size(
hg_bulk_t handle);
/**
* Get total number of segments abstracted by bulk handle.
*
* \param [in] handle abstract bulk handle
*
* \return Non-negative value
*/
hg_uint32_t margo_bulk_get_segment_count(
hg_bulk_t handle);
/**
* Get size required to serialize bulk handle.
*
* \param [in] handle abstract bulk handle
* \param [in] request_eager boolean (passing HG_TRUE adds size of encoding
* actual data along the handle if handle meets
* HG_BULK_READ_ONLY flag condition)
*
* \return Non-negative value
*/
hg_size_t margo_bulk_get_serialize_size(
hg_bulk_t handle,
hg_bool_t request_eager);
/**
* Serialize bulk handle into a buffer.
*
* \param [in/out] buf pointer to buffer
* \param [in] buf_size buffer size
* \param [in] request_eager boolean (passing HG_TRUE encodes actual data
* along the handle, which is more efficient for
* small data, this is only valid if bulk handle
* has HG_BULK_READ_ONLY permission)
* \param [in] handle abstract bulk handle
*
* \return HG_SUCCESS or corresponding HG error code
*/
hg_return_t margo_bulk_serialize(
void *buf,
hg_size_t buf_size,
hg_bool_t request_eager,
hg_bulk_t handle);
/**
* Deserialize bulk handle from an existing buffer.
*
* \param [in] mid Margo instance
* \param [out] handle abstract bulk handle
* \param [in] buf pointer to buffer
* \param [in] buf_size buffer size
*
* \return HG_SUCCESS or corresponding HG error code
*/
hg_return_t margo_bulk_deserialize(
margo_instance_id mid,
hg_bulk_t *handle,
const void *buf,
hg_size_t buf_size);
/**
* Perform a bulk transfer
......@@ -481,6 +569,7 @@ HG_Cancel(
* @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
* @param [out] op_id pointer to returned operation ID
* @returns 0 on success, hg_return_t values on error
*/
hg_return_t margo_bulk_transfer(
......@@ -491,9 +580,27 @@ hg_return_t margo_bulk_transfer(
size_t origin_offset,
hg_bulk_t local_handle,
size_t local_offset,
size_t size);
size_t size,
hg_op_id_t *op_id);
/**
* Cancel an ongoing operation.
*
* \param [in] op_id operation ID
*
* \return HG_SUCCESS or corresponding HG error code
*/
hg_return_t margo_bulk_cancel(
hg_op_id_t op_id);
/* XXX BULK */
/**
* Suspends the calling ULT for a specified time duration
* @param [in] mid Margo instance
* @param [in] timeout_ms timeout duration in milliseconds
*/
void margo_thread_sleep(
margo_instance_id mid,
double timeout_ms);