Exercise 3: Using Bedrock and composing with other services

In this exercise we will use Bedrock to deploy a daemon containing an instance of our phonebook provider. We will then implement a phonebook backend that uses Yokan, and organize the composition of the two within the same daemon. Everything in this exercise relies on the codebase from Exercise 2, however you don’t need to have completed Exercise 2 to do this exercise.

First, make sure that the Spack environment from Exercise 2 is activated (spack env status should show you in which environment you are).

From the build directory, re-run cmake as follows.

cmake .. -DENABLE_TESTS=ON -DENABLE_BEDROCK=ON
make

This time a libYP-bedrock-module.so is being built. This is the Bedrock module for our phonebook service, i.e. the library that tells Bedrock how to instanciate and use our phonebook provider.

To make sure Bedrock finds this library, execute the following command from the build directory.

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:`pwd`/src

examples/bedrock-config.json is an example of Bedrock configuration that spins up a phonebook provider with provider ID 42. This provider manages one phonebook of type “dummy”. You can try our this configuration using the bedrock program as follows.

bedrock na+sm -c ../examples/bedrock-config.json

You can copy the address printed by bedrock on the last line of its log, and in another terminal (don’t forget to activate your spack environment), run the following command.

bedrock-query na+sm -a <copied-address> -p

You will see the current configuration of the service, including a phonebook provider that manages a phonebook. Bedrock has completed the input configuration with a lot of information about Mercury, Argobots, etc. These information can be very useful to communicate to Mochi developers when you try to find out what’s wrong with your service.

We will now add Yokan in our service. To add Yokan as dependency to our spack environment, run the following command.

spack add mochi-yokan+bedrock
spack install

This will install Yokan.

Important

spack add will add the dependency to your active environment, but you should also make sure to list this new dependency in the list of specs in spack.yaml at the root of your project so that it is taken into account next time you want to build a new environment from it.

Edit CMakeLists.txt at the root of your project to add find_package(yokan REQUIRED) (e.g. after the call to find_package(thallium REQUIRED)).

Note

When developing your own service, don’t forget to also edit the src/*.cmake.in and src/*.pc.in files to add relevant dependencies there. Those are the files used by cmake and pkg-config respectively to search for dependencies when people are using your code.

Edit src/CMakeLists.txt to add yokan-client as a dependency for the YP-server library (i.e. find the call to target_link_libraries for YP-server and add yokan-client in the list of public dependencies).

From the build directory, re-run cmake .. to make it find Yokan.

Open examples/bedrock-config.json and add the Yokan library in the libraries section.

"yokan": "libyokan-bedrock-module.so"

In this file as well, we will instanciate a Yokan provider with a Yokan database. In the providers section, before the phonebook provider, add the following provider definition.

{
  "type": "yokan",
  "name": "my-yokan-provider",
  "provider_id": 123,
  "config": {
    "databases": [
      {
        "type": "map",
        "name": "my-db"
      }
    ]
  }
},

Important

It is important that the Yokan provider be defined before the YP provider because the former will be a dependency of the latter.

If you re-run bedrock with this new configuration then call bedrock-query, you should be able to confirm that your Bedrock daemon is now running two providers: one YP provider and one Yokan provider. Of course, these two don’t know about each other, they simply share the resources of the same process. We will now introduce a dependency between YP and Yokan.

Edit src/BedrockModule.cpp and find the getProviderDependencies member function at the end. Change static const std::vector<bedrock::Dependency> no_dependency; into a variable that lists en actual dependency, i.e.:

static const std::vector<bedrock::Dependency> dependencies =
    {{"yokan_ph", "yokan", BEDROCK_REQUIRED}};

The first field, "yokan_ph", is the name by which YP will reference this dependency. "yokan" is the type of dependency. BEDROCK_REQUIRED indicates that this dependency is required.

If you rebuild your code now and re-run the Bedrock configuration, it will display an error message:

[critical] Missing dependency yokan_ph in configuration

So let’s fix that by going again into examples/bedrock-config.json, and add the following in the field in the definition of our YP provider.

"dependencies": {
  "yokan_ph": "yokan:123@local"
}

You can also use "my-yokan-provider" instead of "yokan:123". Now Bedrock should restart accepting your configuration.

Edit src/BedrockModule.cpp once again. This time we will look at the registerProvider function at the beginning of the file. Use the args variable to find the dependency to Yokan as follows.

auto it = args.dependencies.find("yokan_ph");
yk_provider_handle_t yokan_ph =
  it->second.dependencies[0]->getHandle<yk_provider_handle_t>();

You will need to include yokan/provider-handle.h to get the definition of yk_provider_handle_t.

You have now retrieved a Yokan provider handle pointing to your Yokan provider, in the context of registering a YP provider.

Exercise 3: Using Bedrock and composing with other services

Bonus: continuing to wire YP with Yokan