Quickstart

This tutorial provides a basic programmer’s introduction to working with rpcc to define RPCs for the Mercury framework. By following this tutorial, we will be able to:

  1. Define rpcs in a .rpcc file.

  2. Use the rpcc compiler to generate C/C++ source files.

Defining our RPCs

In order to create Mercury RPCs for our service, we need to start with a .rpcc file. The definitions in a .rpcc file are simple: we simply add a rpc statement for each remote procedure we need, and then define both its arguments and return_values by specifying the types and names of the fields that compose each message.

Here’s an example of a simple remote procedure definition:

# contents of rpc_sample.rpcc
package tutorial;

rpc hello_world {

    id: 42;
    arguments {
        string message;
    };

    return_values {
        int8 error_code;
    };
};

In this example, our service provides a simple hello_world remote procedure that requires a string with the containing the message that should be printed, and returns an error_code to let the developer know whether the remote procedure executed successfully or not. As we can see, the syntax of a .rpcc file is pretty similar to C++ or Java. Let’s go through each part of the file and see what it does:

  • The file starts with a package declaration, which helps prevent naming conflicts when integrating the generated code into an existing project. In C++, all the generated classes and functions will be placed in a namespace matching the package name.

  • Next, we have the remote procedure definitions. A remote procedure definition is just a named structure that contains the defined arguments and return_values of the rpc, alongside some options that control how the rpc itself is generated.

Note

Note that, in Mercury, each rpc requires a unique identifier so that the corresponding functions can be executed on the target. By default, the rpcc compiler will automically generate unique identifiers for each defined rpc. The id option shown in the example can be used to override this behavior, allowing developers to explictly provide a user-defined unique identifier for the rpc.

Compiling our remote procedures

Now that we have a .rpcc file, the next thing we need is to generate the code that we will use to be able to call the hello_world remote procedure. To do this, we need to run the rpcc compiler on our sample_rpc.rpcc file.

  1. If you haven’t installed the compiler, follow these instructions to install the latest version.

  2. Now we run the compiler, specifying the desired output mode (i.e. which of the Supported Libraries is going to be used by client code to interact with remote procedures), as well as the code standard to use when generating code.

$ rpcc --output-mode=hermes --std=c++17 rpc_sample.rpcc

Warning

Note that some of the supported output modes may not work with all the code standards.

This generates the following Hermes-compatible source files in the current directory, which should be integrated into your project’s build system:

  • rpc_sample-rpcc.hpp, the header which declares our generated classes.

  • rpc_sample-rpcc.cpp, which contains the implementation of our classes.