[Mochi-devel] margo v0.2 update

[Shane Snyder]

Hi all,

Quick update:

The 'margo-registered-data' branch that all of these modifications were 
made in has been merged over to margo master. That is, if you have a 
project that depends on margo master, you'll need to update your code 
after your next pull. If living in the past is your kind of thing, then 
I've tagged the previous master as 'v0.1' in git so you can check that 
out. (The previous master branch is also preserved in 'old-master-v0.1' 
should we ever have to fall back to it entirely).

There was one additional update to the margo API that is not accounted 
for in the list of changes in my previous email:

* margo_forward, margo_respond, and margo_destroy functions all no 
longer take a Margo instance ID as an input argument. They are now 
basically identical to the mercury calls in that they mostly just need 
the Mercury handle as input.

I have also converted bake-bulk and SSG to use this new API, and have 
updated master in each of those repos to account for the new changes. 
Again, if you still need to keep using the old interface, you can 
checkout the 'v0.1' tag for bake-bulk or the 'v0.2' tag for SSG.

Note: After force moving the branches in these projects around, I seemed 
to confuse git about which remote branch each of my local branches pulls 
from... I don't *think* anyone else should run into this problem, but it 
might be worth checking the git config in your existing repos after 
pulling these updates. Open up the '.git/config' file at the top-level 
of the repos and just ensure that your master branch is set to merge 
from 'refs/heads/master' and not any other branch.

Let me know if there are any issues/questions.

Thanks,
--Shane

On 09/07/2017 02:30 PM, Shane Snyder wrote:
> 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