Mercury Serialization Macros
For convenience, Mercury provides macros that can reduce the amount of code required to send an RPC call. Instead of using tedious RPC stubs and code generators, Mercury makes use of the Boost preprocessor library so that users can generate all the boilerplate code that is necessary to serialize and deserialize function arguments.
RPC Registration
When registering a new RPC through the RPC layer (see
previous section), users are expected to tell Mercury
how to serialize and deserialize input and output arguments. To facilitate that
and in conjunction with the following macros, the MERCURY_REGISTER() macro
makes the registration
of RPC calls more convenient by mapping the types to the generated proc functions.
MERCURY_REGISTER(hg_class, func_name, in_struct_type_name, out_struct_type_name, rpc_cb);
Example
int rpc_open(const char *path, rpc_handle_t handle, int *event_id);
One can use the MERCURY_REGISTER macro and pass the types of the input/output
structures directly. In cases where no input or no output argument is present,
the void type can be passed to the macro.
rpc_id = MERCURY_REGISTER(hg_class, "rpc_open", rpc_open_in_t, rpc_open_out_t, rpc_open_cb);
Predefined Types
Mercury already defines some types and uses standard types so that the size of the type is fixed between platforms when serializing and deserializing it. For convenience, HG types can also be used to serialize bulk handles for example, but also strings, etc.
| Predefined Types | Type name |
|---|---|
| Standard types | int8_t, uint8_t int16_t, uint16_t int32_t, uint32_t int64_t, uint64_t |
| Strings | hg_string_t, hg_const_string_t |
| Bulk descriptor | hg_bulk_t |
| Mercury types | hg_bool_t, hg_id_t, hg_size_t, hg_ptr_t |
New Type Description
The macro MERCURY_GEN_PROC() can be used to describe new types that are
generally composed of primitive types. The macro generates both a
new struct and a proc function that can be used
to serialize arguments. The structure fields contain either input arguments or
output arguments. The generated proc routine uses the proc routines from
pre-existing types to serialize and deserialize each of the fields.
MERCURY_GEN_PROC(struct_type_name, fields)
Example
The following function has two input arguments, one output argument and one return value.
int rpc_open(const char *path, rpc_handle_t handle, int *event_id);
The following macro can be used to generate boilerplate code for the input argument (again, refer to the predefined types section for a list of the pre-existing types that can be passed to this macro):
MERCURY_GEN_PROC( rpc_open_in_t, ((hg_const_string_t)(path))
((rpc_handle_t)(handle)) )
/* Will generate an rpc_open_in_t struct */
typedef struct {
hg_const_string_t path;
rpc_handle_t handle;
} rpc_open_in_t;
/* and an hg_proc_rpc_open_in_t proc function */
hg_return_t
hg_proc_rpc_open_in_t(hg_proc_t proc, void *data)
{
hg_return_t ret;
rpc_open_in_t *struct_data = (rpc_open_in_t *) data;
ret = hg_proc_hg_const_string_t(proc, &struct_data->path);
if (ret != HG_SUCCESS) {
/* error */
}
ret = hg_proc_rpc_handle_t(proc, &struct_data->handle);
if (ret != HG_SUCCESS) {
/* error */
}
return ret;
}
Note the parentheses that separate the name of the field and its type. Each field is then separated by another pair of parentheses. This follows the sequence data type of the Boost preprocessor library.
Existing struct Description
In some cases, however, the argument types are not known by Mercury, which is
the case of the previous example with the rpc_handle_t type. For these cases,
another macro, called MERCURY_GEN_STRUCT_PROC, can be used. It defines a
serialization function for an existing struct or type—this assumes that the
type can be mapped to already existing types; if not, users can create their
own proc function and use the hg_proc_raw routine that takes a stream of bytes.
MERCURY_GEN_STRUCT_PROC(struct_type_name, fields)
Example
The following function has one non-standard type, rpc_handle_t.
int rpc_open(const char *path, rpc_handle_t handle, int *event_id);
/* pre-defined struct */
typedef struct {
hg_uint64_t cookie;
} rpc_handle_t;
The following macro can then be used to generate boilerplate code for the type by defining its fields.
MERCURY_GEN_STRUCT_PROC( rpc_handle_t, ((hg_uint64_t)(cookie)) )
/* Will generate an hg_proc_rpc_handle_t function */
static hg_return_t
hg_proc_rpc_handle_t(hg_proc_t proc, void *data)
{
hg_return_t ret;
rpc_handle_t *struct_data = (rpc_handle_t *) data;
ret = hg_proc_hg_uint64_t(proc, &struct_data->cookie);
if (ret != HG_SUCCESS) {
/* error */
}
return ret;
}