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
