[Mochi-devel] margo v0.2 update

[Shane Snyder]

Hi all,

Following is the high-level list of changes to Margo and its API 
starting with version 0.2 (thanks to Matthieu & Phil for helping with 
all of this):

* margo_init is much more simplified and initializes Mercury and 
Argobots on behalf of the user (with margo_finalize finalizing them in 
that case)
     * the prototype is margo_init(addr_string, MARGO_CLIENT_MODE | 
MARGO_SERVER_MODE, use_progress_thread, num_rpc_handler_threads)
     * margo_init_pool is still available as an advanced init routine, 
where the user must init Mercury/Argobots and pass in an HG_Context and 
ABT_pools for RPC handlers and the progress loop

* Margo now has its own RPC registration functions that should be used 
for registering RPCs (as Margo is now attaching internal state to RPCs)
     * MARGO_REGISTER is basically equivalent to MERCURY_REGISTER, 
except it takes a Margo instance ID rather than a Mercury class
     * MARGO_REGISTER_MPLEX is mostly the same as above, but allows a 
user to specify an ABT_pool to use for a given RPC type

* related to the above, but Margo users should now use 
margo_register_data (rather than HG_Register_data) for associating user 
data with an RPC type
     * like Mercury, there is a corresponding margo_registered_data call 
to retrieve the user pointer

* the following Mercury-like functions are now defined within Margo, 
although it is still safe to just use the Mercury calls directly (most 
are just #defined to the corresponding Mercury call, anyway):
     * margo_registered_disable_response
     * margo_addr_free
     * margo_addr_self
     * margo_addr_dup
     * margo_addr_to_string
     * margo_create
     * margo_destroy
         * Note that margo_create/margo_destroy are enhancing 
HG_Create/HG_Destroy with a cache of reusable handles, so they may be 
preferable to the Mercury calls
     * margo_bulk_create
     * margo_bulk_free
     * margo_bulk_deserialize

* margo_hg_handle_get_instance and margo_hg_info_get_instance calls have 
been added to the API to retrieve a Margo instance ID given a received 
handle or the HG info struct associated with the handle

* there are also new APIs for obtaining diagnostics info from the Margo 
progress loop and for setting Margo parameters at runtime -- Phil can 
probably give more info on these

This list of changes also been added to the Margo README.

Note that these changes currently exist only in the 
'margo-registered-data' branch of margo. The examples and tests have all 
been updated and should be used to better understand the new changes. We 
will push the new version to master and tag the old version after we've 
given other repos an opportunity to catch up to the new changes. SSG at 
least has an equivalently named branch (margo-registered-data) that is 
up-to-date with these changes. I believe Matthieu has already updated 
his kNN work and the sds-examples repo, too.

Still left to be done, likely before finishing the move back to master:

* update Margo documentation to give info on handle caching, diagnostics 
interface, param setting interface, etc.
* update bake-bulk repo with the Margo changes
* test and merge in a new (optional) Margo API for managing pools of 
bulk handles/buffers

Let us know if you have questions/comments/concerns.

Thanks,
--Shane