Commit 9bd02ac2 authored by Shane Snyder's avatar Shane Snyder

document which hg functions to wrap in first pass

parent f83d3985
......@@ -90,28 +90,42 @@ void margo_finalize(margo_instance_id mid);
*/
void margo_wait_for_finalize(margo_instance_id mid);
/**
* Retrieve the abt_handler pool that was associated with the instance at
* initialization time
/**
* Registers an RPC with margo
* @param [in] mid Margo instance
* @param [in] id Mercury RPC identifier
*/
ABT_pool* margo_get_handler_pool(margo_instance_id mid);
int margo_register(margo_instance_id mid, hg_id_t id);
/**
* Retrieve the Mercury context that was associated with this instance at
* initialization time
/**
* Registers an RPC with margo that is associated with a multiplexed service
* @param [in] mid Margo instance
* @return the Mercury context used in margo_init
* @param [in] id Mercury RPC identifier
* @param [in] mplex_id multiplexing identifier
* @param [in] pool Argobots pool the handler will execute in
*/
hg_context_t* margo_get_context(margo_instance_id mid);
int margo_register_mplex(margo_instance_id mid, hg_id_t id, uint32_t mplex_id, ABT_pool pool);
/**
* 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
/*
* Indicate whether HG_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
*
* \return HG_SUCCESS or corresponding HG error code
*/
hg_class_t* margo_get_class(margo_instance_id mid);
/* 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
);
*/
/**
* Register and associate user data to registered function.
......@@ -143,13 +157,261 @@ hg_return_t margo_register_data(
void* margo_registered_data(margo_instance_id mid, hg_id_t id);
/**
* Get the margo_instance_id from a received RPC handle.
* 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.
*
* \param [in] h RPC handle
*
* \return Margo instance
* \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)
*
* \return HG_SUCCESS or corresponding HG error code
*/
margo_instance_id margo_hg_handle_get_instance(hg_handle_t h);
/* XXX
HG_EXPORT hg_return_t
HG_Registered_disable_response(
hg_class_t *hg_class,
hg_id_t id,
hg_bool_t disable
);
*/
/**
* Lookup an addr from a peer address/name.
* @param [in] name lookup name
* @param [out] addr return address
* @returns HG_SUCCESS on success
*/
hg_return_t margo_addr_lookup(
margo_instance_id mid,
const char *name,
hg_addr_t *addr);
/**
* Free the addr from the list of peers.
*
* \param hg_class [IN] pointer to HG class
* \param addr [IN] abstract 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
);
*/
/**
* Access self address. Address must be freed with HG_Addr_free().
*
* \param hg_class [IN] pointer to HG class
* \param addr [OUT] pointer to abstract 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
);
*/
/**
* 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().
*
* \param hg_class [IN] pointer to HG class
* \param addr [IN] abstract address
* \param new_addr [OUT] pointer to abstract 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
);
*/
/**
* 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.
*
* \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
*
* \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
);
*/
/**
* 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().
*
* \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
*
* \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
);
*/
/**
* Destroy HG handle. Decrement reference count, resources associated to the
* handle are freed when the reference count is null.
*
* \param handle [IN] HG handle
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Destroy(
hg_handle_t handle
);
*/
/**
* Increment ref count on handle.
*
* \param handle [IN] HG handle
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Ref_incr(
hg_handle_t hg_handle
);
*/
/**
* Get info from handle.
*
* \remark Users must call HG_Addr_dup() to safely re-use the addr field.
*
* \param handle [IN] HG 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
);
*/
/**
* Get input from handle (requires registration of input proc to deserialize
* parameters). Input must be freed using HG_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
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_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
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Free_input(
hg_handle_t handle,
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
*
*
* \param handle [IN] HG handle
* \param out_struct [IN/OUT] 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
);
*/
/**
* 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
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Free_output(
hg_handle_t handle,
void *out_struct
);
*/
/**
* Forward an RPC request to a remote host
......@@ -195,6 +457,20 @@ hg_return_t margo_respond(
hg_handle_t handle,
void *out_struct);
/**
* Cancel an ongoing operation.
*
* \param handle [IN] HG handle
*
* \return HG_SUCCESS or corresponding HG error code
*/
/* XXX
HG_EXPORT hg_return_t
HG_Cancel(
hg_handle_t handle
);
*/
/**
* Perform a bulk transfer
* @param [in] mid Margo instance
......@@ -217,41 +493,48 @@ hg_return_t margo_bulk_transfer(
size_t local_offset,
size_t size);
/* XXX BULK */
/**
* address lookup
* @param [in] name lookup name
* @param [out] addr return address
* @returns HG_SUCCESS on success
* Retrieve the abt_handler pool that was associated with the instance at
* initialization time
* @param [in] mid Margo instance
*/
hg_return_t margo_addr_lookup(
margo_instance_id mid,
const char *name,
hg_addr_t *addr);
ABT_pool* margo_get_handler_pool(margo_instance_id mid);
/**
* Suspends the calling ULT for a specified time duration
* Retrieve the Mercury context that was associated with this instance at
* initialization time
* @param [in] mid Margo instance
* @param [in] timeout_ms timeout duration in milliseconds
* @return the Mercury context used in margo_init
*/
void margo_thread_sleep(
margo_instance_id mid,
double timeout_ms);
hg_context_t* margo_get_context(margo_instance_id mid);
/**
* Registers an RPC with margo
/**
* Retrieve the Mercury class that was associated with this instance at
* initialization time
* @param [in] mid Margo instance
* @param [in] id Mercury RPC identifier
* @return the Mercury class used in margo_init
*/
int margo_register(margo_instance_id mid, hg_id_t id);
hg_class_t* margo_get_class(margo_instance_id mid);
/**
* Registers an RPC with margo that is associated with a multiplexed service
/**
* Get the margo_instance_id from a received RPC handle.
*
* \param [in] h RPC handle
*
* \return Margo instance
*/
margo_instance_id margo_hg_handle_get_instance(hg_handle_t h);
/**
* Suspends the calling ULT for a specified time duration
* @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] timeout_ms timeout duration in milliseconds
*/
int margo_register_mplex(margo_instance_id mid, hg_id_t id, uint32_t mplex_id, ABT_pool pool);
void margo_thread_sleep(
margo_instance_id mid,
double timeout_ms);
/**
* Maps an RPC id and mplex id to the pool that it should execute on
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment