JSON configuration

A JSON file describes the channels of one or more devices. Give it to a device with --mq-config <file>. The device reads only the entry with its ID or its --config-key, and stores the channels of this entry as properties.

A complete file

The file of the 1-n-1 example has three entries: one for the sampler, one for the two processors, and one for the sink.

examples/1-n-1/ex-1-n-1.json

{
    "fairMQOptions": {
        "devices": [
            {
                "id": "sampler1",
                "channels": [
                    {
                        "name": "data1",
                        "sockets": [
                            {
                                "type": "push",
                                "method": "bind",
                                "address": "tcp://*:5555",
                                "sndBufSize": 1000,
                                "rcvBufSize": 1000,
                                "rateLogging": 0
                            }
                        ]
                    }
                ]
            },
            {
                "key": "processor",
                "channels": [
                    {
                        "name": "data1",
                        "sockets": [
                            {
                                "type": "pull",
                                "method": "connect",
                                "address": "tcp://localhost:5555",
                                "sndBufSize": 1000,
                                "rcvBufSize": 1000,
                                "rateLogging": 0
                            }
                        ]
                    },
                    {
                        "name": "data2",
                        "sockets": [
                            {
                                "type": "push",
                                "method": "connect",
                                "address": "tcp://localhost:5556",
                                "sndBufSize": 1000,
                                "rcvBufSize": 1000,
                                "rateLogging": 0
                            }
                        ]
                    }
                ]
            },
            {
                "id": "sink1",
                "channels": [
                    {
                        "name": "data2",
                        "sockets": [
                            {
                                "type": "pull",
                                "method": "bind",
                                "address": "tcp://*:5556",
                                "sndBufSize": 1000,
                                "rcvBufSize": 1000,
                                "rateLogging": 0
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

examples/1-n-1/ex-1-n-1.json:1–73

Structure

The parser reads this tree (JSONParser.cxx):

fairMQOptions             object, required
└── devices               array of device entries
    └── { }               device entry: id or key, channels
        └── channels      array of channels
            └── { }       channel: name, properties, numSockets, sockets
                └── sockets   array of sockets
                    └── { }   socket: properties

Each socket object makes one sub-channel. Its index is its position in the sockets array, from 0. The properties of the sub-channel get the keys chans.<name>.<index>.<property>, for example chans.data1.0.address. The parser ignores all keys that it does not know, on each level.

Keys

Device entry

Key	Type	Meaning
id	string	The device ID that selects this entry. The parser uses it only if the entry has no key.
key	string	The value that selects this entry. Several devices can use one entry with --config-key.
channels	array	The channels of the device.

An entry needs id or key, otherwise no device can select it.

Channel

Key	Type	Meaning
name	string	Required. The name of the channel.
sockets	array	One object for each sub-channel. Without sockets and without numSockets, the channel has one sub-channel.
numSockets	int	For a value above 0: the number of sub-channels. The parser then ignores sockets. See numSockets.
type, method, address, transport, sndBufSize, rcvBufSize, sndKernelSize, rcvKernelSize, sndTimeoutMs, rcvTimeoutMs, linger, rateLogging, portRangeMin, portRangeMax, autoBind	see Channel properties	The values for all sub-channels of the channel.

Socket

Key	Type	Meaning
type, method, address, transport, sndBufSize, rcvBufSize, sndKernelSize, rcvKernelSize, sndTimeoutMs, rcvTimeoutMs, linger, rateLogging, portRangeMin, portRangeMax, autoBind	see Channel properties	The values for this sub-channel. They override the values of the channel.

name and numSockets have no effect in a socket object.

How the device finds its entry

The config plugin reads the file when the device goes into the state INITIALIZING DEVICE (Config.cxx):

1. The plugin takes the value of --config-key. Without --config-key, it takes the value of --id.
2. The parser compares this value with the key of each device entry. For an entry without key, it compares the value with id (JSONParser.cxx).
3. The parser reads the channels of each entry that matches.

An entry with a key does not match its id. Several devices can use the same entry. In the start script of the 1-n-1 example, both processors have their own ID and the same key processor:

examples/1-n-1/fairmq-start-ex-1-n-1.sh.in

PROCESSOR1="fairmq-ex-1-n-1-processor"
PROCESSOR1+=" --id processor1"
PROCESSOR1+=" --mq-config $ex2config"
PROCESSOR1+=" --config-key processor"
xterm -geometry 80x23+500+0 -hold -e @EX_BIN_DIR@/$PROCESSOR1 &

PROCESSOR2="fairmq-ex-1-n-1-processor"
PROCESSOR2+=" --id processor2"
PROCESSOR2+=" --mq-config $ex2config"
PROCESSOR2+=" --config-key processor"
xterm -geometry 80x23+500+330 -hold -e @EX_BIN_DIR@/$PROCESSOR2 &

examples/1-n-1/fairmq-start-ex-1-n-1.sh.in:12–22

• No entry matches. The device gets no channels from the file, and the parser shows no error. A device without channels logs the warning No channels created after finishing initialization in CONNECTING.
• Several entries match. The parser reads all of them. For a property that is in two entries, the value of the first entry stays.
• --mq-config and --channel-config. If you give both, the plugin reads only the JSON file.

Channel values and socket values

The values of a channel are the defaults of its sockets. A socket object can override each of them. This configuration of the parser tests shows the rules:

test/properties/_jsonparser.cxx

auto const kConfig = R"({
    "fairMQOptions": {
        "devices": [
            {
                "id": "sampler",
                "channels": [
                    {
                        "name": "data",
                        "type": "push",
                        "method": "bind",
                        "transport": "zeromq",
                        "sndBufSize": 500,
                        "sockets": [
                            { "address": "tcp://127.0.0.1:5555" },
                            { "address": "ipc://data", "transport": "shmem", "method": "connect", "rateLogging": 0 }
                        ]
                    },
                    {
                        "name": "fanout",
                        "type": "push",
                        "address": "tcp://127.0.0.1:5556",
                        "numSockets": 3
                    },
                    {
                        "name": "plain",
                        "type": "pair",
                        "autoBind": false
                    }
                ]
            },
            {
                "id": "other",
                "key": "sink",
                "channels": [ { "name": "data", "type": "pull" } ]
            }
        ]
    }
})";

test/properties/_jsonparser.cxx:45–82

For the device ID sampler, the parser makes these sub-channels. The tests in the same file check the values.

Sub-channel	Values from the socket	Values from the channel	Other properties
data[0]	address	type, method, transport, sndBufSize	Defaults
data[1]	address, method, transport, rateLogging	type, sndBufSize	Defaults
fanout[0] to fanout[2]	none, because of numSockets	type, address	Defaults
plain[0]	none, because there is no sockets array	type, autoBind	Defaults

The entry with the ID other has the key sink. --config-key sink selects it, but --id other does not.

numSockets

With numSockets above 0, the parser makes this number of sub-channels. All of them get the values of the channel, also the address. The parser then ignores the sockets array (JSONParser.cxx). Channel properties describes the effect on binding sub-channels.

Value types

Write strings as JSON strings, numbers as JSON numbers, and booleans as true or false. Channel properties gives the type of each property.

Wrong types

The parser reads each value with a default (JSONParser.cxx). If it cannot convert a value, it uses the default and shows no error. For example, "sndBufSize": "big" gives sndBufSize 1000. To see the values, start the device with --severity trace: the parser then logs each property of each sub-channel.

Errors

Problem	Result
The file does not exist, or it is not valid JSON.	boost::property_tree::json_parser_error
The file has no fairMQOptions object.	boost::property_tree::ptree_bad_path
A channel has no name.	boost::property_tree::ptree_bad_path
The ID is empty. This occurs only when you call the parser from code.	fair::mq::ParserError: no device ID provided. Provide with `--id` cmd option
No entry matches the ID or the key.	No error. The device has no channels from the file.
A value has the wrong type.	No error. The parser uses the default.

The config plugin catches the exceptions and logs their message with the severity error (Config.cxx). The device then continues without the channels of the file. If the device has no --id and no --config-key, the plugin logs the warning No device ID or config-key provided for the configuration parser. and does not read the file.

Caution

A device with a broken file can start without channels. If your device does not find a channel, look for an error message from the parser at the start of the log.

Parse a file from code

fair::mq::JSONParser() reads a file and returns the properties of one device entry. PtreeParser() does the same for a Boost property tree. Give the result to ProgOptions::SetProperties():

#include <fairmq/JSONParser.h>
#include <fairmq/ProgOptions.h>

fair::mq::ProgOptions config;
config.SetProperties(fair::mq::JSONParser("ex-1-n-1.json", "sampler1"));

The second argument is the ID or the key of the entry.

Related pages

• Channel properties: all keys of a channel and a socket, with the defaults.
• Configure channels: the JSON file, --channel-config and properties from code.
• Configuration and properties: how the device reads its configuration.
• Command-line options: --mq-config, --config-key and --id.