Bedrock’s JSON format

This section details how to configure a Bedrock daemon using a JSON file. The code bellow is an example of such a JSON configuration.

{
    "margo" : {
        "mercury" : {
        },
        "argobots" : {
        "abt_mem_max_num_stacks" : 8,
        "abt_thread_stacksize" : 2097152,
        "version" : "1.0.0",
        "pools" : [
            {
                "name" : "my_progress_pool",
                "kind" : "fifo_wait",
                "access" : "mpmc"
            },
            {
                "name" : "my_rpc_pool",
                "kind" : "fifo_wait",
                "access" : "mpmc"
            }
        ],
        "xstreams" : [
            {
                "name" : "my_progress_xstream",
                "cpubind" : 0,
                "affinity" : [ 0, 1 ],
                "scheduler" : {
                    "type" : "basic_wait",
                    "pools" : [ "my_progress_pool" ]
                }
            },
            {
                "name" : "my_rpc_xstream",
                "cpubind" : 2,
                "affinity" : [ 2, 3, 4, 5 ],
                "scheduler" : {
                    "type" : "basic_wait",
                    "pools" : [ "my_rpc_pool" ]
                }
            }
            ]
        },
        "progress_pool" : "my_progress_pool",
        "rpc_pool" : "my_rpc_pool"
    },
    "bedrock": {
        "pool": "my_rpc_pool",
        "provider_id": 0
    },
    "libraries" : [
        "libyokan-bedrock-module.so",
        "bedrock/05_cpp_module/libmy-bedrock-module.so"
    ],
    "providers" : [
        {
            "name" : "my_yokan_provider",
            "type" : "yokan",
            "provider_id" : 42,
            "config" : {},
            "dependencies" : {
                "pool": "my_rpc_pool"
            }
        },
        {
            "name" : "my_example_provider",
            "type" : "my_module",
            "provider_id" : 33,
            "config" : {},
            "dependencies" : {
                "kv_store" : "my_yokan_provider@local",
                "pool": "__primary__"
            }
        }
    ]
}

Margo section (optional)

The first section that such a JSON file may contain is a margo section. The format for this section is explained in the Margo tutorials and will not be covered here. Note that if not provided, default values will be used, hence the Margo instance created by Bedrock will still rely on an Argobots pool called __primary__.

Note

In the following sections, keep in mind that an Argobots configuration always has an implicite __primary__ pool, even if it does not appear in the configuration. This pool can always be refered to by name.

Bedrock section (optional)

The bedrock section can provide Bedrock-specific configuration parameters, including the Argobots pool in which Bedrock RPCs should execute, and the provider id used by Bedrock. All the Bedrock daemons in a given service should use the same provider id. There is usually no reason to change this id, unless Bedrock is embedded inside an application and multiple Bedrock instances are running alongside each other.

Libraries and components

The libraries section lists shared libraries to load. These libraries tell Bedrock how to instantiate providers for various component types. The next tutorial details how to write these component libraries, called “modules”.

The providers section is an array of provider objects of the following form.

{
     "name" : "<string>",
     "type" : "<string>",
     "provider_id" : "<int>",
     "config" : "<object>",
     "dependencies" : {
            "<key1>" : "<name1>",
            "<key2>" : "<name2>"
     }
}

The name will be the name by which the provider can be referred to in other places of the configuration. The type must be one of the module names provided in one of the loaded libraries. The provider_id must be an integer between 0 and 65534 (max uint16, minus one as 65535 is reserved). All the providers must have distinct provider ids. config should be a JSON object formatted to comply with the component’s expected JSON format. It will be passed as-is to the component’s registration function. You should refer to the component’s documentation to know what is expected from this configuration field.

Finally the dependencies entry is an object associating dependency names to references. Bedrock will resolve these references and pass them to the provider creation function when calling it.

Dependency resolution

The dependencies section in a provider lists dependency names associated with values. These values can be one of the following:

Pool: The name of an Argobots pool listed in the "margo" section;
Xstream: The name of an Argobots execution stream listed in the "margo" section;
Local provider: The name of another provider defined in the same JSON file (such provider must have been defined before) will resolve to a pointer to this provider;
Remote provider: A string of the form "<name>@<location>" or "<type>:<id>@<location>" will resolve into a provider handle pointing to a specific provider identified either by its <name> or by its <type> and provider <id> at the specified <location>. The location may be either local, to refer to the calling process, or a Mercury address (e.g. na+sm://2317/0) pointing to a remote Bedrock daemon.

The documentation for a given component should provide you with the list of dependencies that must be provided, as well as their types. Some of these dependencies may be listed as optional, some may be mandatory, in which case Bedrock will fail if the dependency isn’t provided in the dependencies section of the provider. Some dependencies may be an array, some may be a single string.