Command-line options

A device made with runDevice.h accepts the options on this page. The table at the end lists the options that each such device has, with the defaults from the code. Each option becomes a property with the same name, so your code reads it with GetProperty().

Where the options come from

The device runner (DeviceRunner) collects the options from several places before it parses the command line (DeviceRunner.cxx):

Source	Group in --help	Group in the table	Options
ProgOptions	FairMQ Command Line Options	General, Logging	--help, --version, --print-options, the log options
The config plugin	FairMQ device options	Device, Shared memory	Device ID, transport, channel configuration, shared memory
The control plugin	Control (builtin) Plugin	Control	--control, --catch-signals
The plugin manager	Plugin Manager	Plugins	-P, -S
Your device	Custom options	Not in the table	The options of addCustomOptions()
Other plugins	The name that the plugin gives	Not in the table	The options of each plugin that you load with -P

The device runner always loads the config plugin and the control plugin. The config plugin reads the channel configuration. The control plugin moves the device through its states. Refer to Plugins and control.

Show the options of a device

--help (or -h) prints all options of the device, with their groups, defaults and descriptions. Then the program stops before it makes the device (DeviceRunner.cxx).

--print-options prints one line for each option, in the format name:value:type:description (ProgOptions.cxx). The value is the value after the parse of the command line. For an option without a value, the value is empty and the type is <unknown>. Then the program stops before it makes the device.

fairmq-ex-1-1-sampler --id sampler1 --print-options

Some lines of the output:

help::<unknown>:Print help
id:sampler1:string:Device ID.
transport:zeromq:string:Transport ('zeromq'/'shmem').
control:dynamic:string:Control mode, 'static' or 'dynamic' (aliases for dynamic are external and interactive), 'none', 'gui'

When the device starts, it logs all properties with the severity debug, after the line Configuration: (ProgOptions.cxx). Each line has the form name = value <type> origin. The origin is [default], [provided] or [empty]. The channel properties from --channel-config and --mq-config are not in this log, because the config plugin reads them later, in INITIALIZING DEVICE.

--version and --print-channels

--version and --print-channels print nothing in this version. The device runner sets the console log to nolog for these two options, and then writes the output to the log (DeviceRunner.cxx). The device runner then ends the device with the transition END (DeviceRunner.cxx). --print-channels is for the channels that a device registers with RegisterChannelEndpoint(), not for the configured channels.

Value formats

• A long option takes its value as --name value or --name=value (ProgOptions.cxx).
• A short option takes its value as -P value or -Pvalue.
• A boolean option takes true or false, for example --color false.
• --print-options and --print-channels need no value.
• --help and --version take no value.
• Sizes are in bytes, for example --shm-segment-size 1000000000.
• --channel-config and -S take several values after the option. Give one value for each channel after one --channel-config, as the examples do:

examples/multiple-channels/fairmq-start-ex-multiple-channels.sh.in

SAMPLER="fairmq-ex-multiple-channels-sampler"
SAMPLER+=" --id sampler1"
SAMPLER+=" --channel-config name=data,type=push,method=bind,rateLogging=0,address=tcp://*:5555"
SAMPLER+="                  name=broadcast,type=sub,method=connect,rateLogging=0,address=tcp://localhost:5005"

examples/multiple-channels/fairmq-start-ex-multiple-channels.sh.in:5–8

Unknown options

The device ignores options that it does not know (ProgOptions.cxx). For example, the device starts also with the misspelled option --chanel-config, but without channels. It logs each unknown option only with the severity debug: detected unregistered option.

Custom options

With runDevice.h, your program defines the function addCustomOptions(). The device runner adds these options in the group Custom options (runDevice.h). Use the types and the defaults of Boost.Program_options:

examples/1-1/sampler.cxx

void addCustomOptions(bpo::options_description& options)
{
    options.add_options()
        ("text", bpo::value<std::string>()->default_value("Hello"), "Text to send out")
        ("max-iterations", bpo::value<uint64_t>()->default_value(0), "Maximum number of iterations of Run/ConditionalRun/OnData (0 - infinite)");
}

examples/1-1/sampler.cxx:59–64

Read the values in your device as properties, with the same type as in the option:

examples/1-1/sampler.cxx

void InitTask() override
{
    // Get the fText and fMaxIterations values from the command line options (via fConfig)
    fText = fConfig->GetProperty<std::string>("text");
    fMaxIterations = fConfig->GetProperty<uint64_t>("max-iterations");
}

examples/1-1/sampler.cxx:18–23

For a property with another type, GetProperty() throws an exception. Configuration and properties describes the properties.

Plugin options

A plugin can declare its own options. The device runner adds the options of each plugin that you load with -P, so --help -P <plugin> shows them. A plugin option is a property like the others. Refer to Write a plugin.

All options

The table shows the options of a device made with runDevice.h, without custom options and the options of other plugins. Use the filter to find an option, or select a group. The link at the end of each description goes to the line of the code that defines the option.

AllDeviceShared memoryControlLoggingPluginsGeneral

37 options

Option	Default	Description
--idstring	""	Device ID. A JSON configuration uses it as the key of the device, unless you set --config-key.config plugin
--io-threadsint	1	Number of I/O threads of the ZeroMQ context. The zeromq and the shmem transports use it.config plugin
--transportstring	zeromq	Default transport of the device: zeromq or shmem. A channel can set its own transport.config plugin
--network-interfacestring	default	Network interface for a bind sub-channel without an address, for example eth0. The device binds to the IP of this interface on an automatic port. default: the interface of the default route.config plugin
--init-timeoutint	120	Time in seconds to connect all channels in the state CONNECTING. If an address is not valid yet, the device tries again every 50 ms and reads the address property again. After this time, the device goes to the state ERROR.config plugin
--print-channelsbool	no value: true	Print the channels that the device registers with RegisterChannelEndpoint(), as name:min:max (the minimum and maximum number of sub-channels), and stop. Known defect: the output is empty, because the device sets the console severity to nolog first.config plugin
--ratefloat	0	Maximum rate of the ConditionalRun() loop in Hz. 0: no limit.config plugin
--sessionstring	default	Session name. Devices of the same user with the same session use the same shared memory.config plugin
--config-keystring	—	Key of the device in the JSON file. Use it instead of the device ID.config plugin
--mq-configstring	—	JSON file with the configuration of the devices and their channels. If you also give --channel-config, the device uses only --mq-config.config plugin
--channel-configvector<string>, several values	—	Channel configuration as a list of key=value pairs, separated by commas. Give one list for each channel. Each address in a list adds a sub-channel. Several lists can follow one --channel-config. A list can start with <name>: instead of name=<name>.config plugin
--shm-segment-sizesize_t	2147483648	Size of the managed shared memory segment in bytes. The default is 2 GiB. Only the device that creates the segment sets its size.config plugin
--shm-allocationstring	rbtree_best_fit	Allocation algorithm of the segment: rbtree_best_fit or simple_seq_fit. A device that opens an existing segment uses the algorithm of that segment and logs a warning if it differs.config plugin
--shm-segment-iduint16_t	0	Experimental. ID of the segment for new messages. Devices of one session can use several segments.config plugin
--shmiduint64_t	—	Experimental. Use this shmId instead of the one that FairMQ makes from the session name and the user ID. The value is a decimal number. The object names contain it as a hexadecimal number with at least 8 digits: --shmid 1 gives 00000001.config plugin
--shm-mlock-segmentbool	false	Lock the segment in RAM after the device opens or creates it.config plugin
--shm-mlock-segment-on-creationbool	false	Lock the segment in RAM only when this device creates it.config plugin
--shm-zero-segmentbool	false	Write zeros to the free memory of the segment after the device opens or creates it.config plugin
--shm-zero-segment-on-creationbool	false	Write zeros to the free memory of the segment only when this device creates it.config plugin
--shm-throw-bad-allocbool	true	Throw fair::mq::MessageBadAlloc when an allocation in the segment fails. false: try again every --bad-alloc-attempt-interval ms, until the allocation succeeds or a transition interrupts the transport. false overrides --bad-alloc-max-attempts. A message that is larger than the segment always throws.config plugin
--shm-metadata-msg-sizesize_t	0	Size in bytes of the ZeroMQ message that carries the metadata. The transport pads the metadata to this size. A value below the size of the metadata (40 bytes for one message) has no effect.config plugin
--bad-alloc-max-attemptsint	—	Number of allocation attempts before MessageBadAlloc. -1: no limit. The device always makes one attempt, so 0 and 1 have the same effect.config plugin
--bad-alloc-attempt-intervalint	50	Time between two allocation attempts in ms.config plugin
--shm-monitorbool	false	Start fairmq-shmmonitor for the session, if no monitor runs for it. The device looks for the executable in FAIRMQ_PATH and PATH.config plugin
--shm-no-cleanupbool	false	Keep the shared memory when the last device of the session stops.config plugin
--controlstring	dynamic	Controller of the state machine: static, dynamic (also interactive and external), gui or none. An unknown value gives static, with an error in the log.control plugin
--catch-signalsint	1	Handle SIGINT and SIGTERM: 1 (yes) or 0 (no). The first signal starts the shutdown sequence. A second SIGINT aborts the process.control plugin
--severitystring	""	Console log severity: trace, debug, info, state, warn, error, fatal or nolog. Empty: keep the default of FairLogger. The environment variable FAIRMQ_SEVERITY overrides this option.ProgOptions
--file-severitystring	debug	Log severity for the log file of --log-to-file.ProgOptions
--verbositystring	medium	Log verbosity: veryhigh, high, medium or low. It sets the fields in each log line.ProgOptions
--colorbool	true	Use colors in the console log.ProgOptions
--log-to-filestring	""	Write the log to this file. The console log is then off.ProgOptions
-S, --plugin-search-pathvector<string>, several values	—	Directories to search for plugins, in this order. Put < before a path to put it at the start of the list, or > to put it at the end. If a plugin is not in these directories, the device tries the system lookup of libraries (system directories, RUNPATH, LD_LIBRARY_PATH).PluginManager
-P, --pluginvector<string>	—	Load these plugins, in this sequence. For the file libfairmq-plugin-example.so, the name is example. Put p: before the name of a prelinked plugin.PluginManager
-h, --helpflag	—	Print the help and stop.ProgOptions
-v, --versionflag	—	Print the versions of FairMQ and of the device, and stop. Known defect: the output is empty, because the device sets the console severity to nolog first.ProgOptions
--print-optionsbool	no value: true	Print all options in a machine-readable format (option:value:type:description) and stop.ProgOptions

Related pages

• Configuration and properties: how options, JSON files and plugins give properties.
• Channel properties: the keys for --channel-config.
• JSON configuration: the file for --mq-config.
• Plugins and control: --control, -P and the plugin search path.
• Logging: --severity, --verbosity and the log file.