Configuration » History » Version 4
Version 3 (S. Wrede, 05/19/2011 03:01 PM) → Version 4/15 (S. Wrede, 05/19/2011 03:04 PM)
h1. Configuration
The configuration mechanism is based on the following principles:
* We cannot (and do not want) to handle configuration of individual participants. The configuration mechanism is intended to provide process-wide defaults. Participants that require individual configurations have to be configured programmatically.
* The configuration mechanism works identically across implementation languages
* Configuration options are obtained from multiple configuration sources:
** Configuration files
** Environment variables
** _Commandline options (planned)_
* Configuration options are organized in a tree of name-value pairs
h2. Syntax and Semantics
Option names consist of multiple components which are specified in configuration-source-dependent syntax. For example, in configuration files section names like @[transport.spread]@ are concatenated with names of contained options like @port@ to obtain @transport.spread.port@. For environment variables, the name @RSB_TRANSPORT_SPREAD_PORT@ maps to @transport.spread.port@.
Currently the following option tree is defined (uppercase option name components are placeholders):
<pre>
+ qualityofservice
+-- reliability { UNRELIABLE, RELIABLE }
+-- ordering { UNORDERED, ORDERED }
+ errorhandling
+-- onhandlererror { LOG, PRINT, EXIT }
+ transport
+-- NAME
+---- enabled bool
+---- TRANSPORT_SPECIFIC_OPTION ?
+---- converter
+------ WIRE-SCHEMA string
+-- spread
+---- host string
+---- port uint
+-- inprocess
</pre>
h2. Processing Order
Configuration sources are processed in the following order such that options from sources which are processed later take precedence over options from sources which are processed earlier:
# Config file @${HOME}/.config/rsb.conf@
# Config file @$(pwd)/rsb.conf@
# Environment variables
h3. Example and test case
Consider the following situation:
* Contents of @${HOME}/.config/rsb.conf@:
<pre>
[transport.spread]
host = azurit
port = <uint>5301
</pre>
* Contents of @(pwd)/rsb.conf@
<pre>
[transport.spread]
host = localhost
</pre>
* Environment Variables
@RSB_TRANSPORT_SPREAD_PORT='<unit>4444'@
This would result in the following effective option values:
* @transport.spread.host = localhost@
* @transport.spread.port = 4444@
h2. Sources
The following sections briefly explains the currently defined configuration sources.
h3. Configuration Files
Configuration files use the following syntax, which is similar to INI-files or desktop-files:
* Comments are initiated by the @#@ character and extend to the end of the current line
* After removing comments, all lines have to be of one of the following forms:
** empty
** @[NAME]@ where @NAME@ consists of alphanumeric characters and colons
** @NAME = VALUE@ where @NAME@ consists of alphanumeric characters
Here is an example:
<pre>
[qualityofservice]
reliability = UNRELIABLE
ordering = UNORDERED
[errorhandling]
onhandlererror = LOG
[transport.spread]
host = localhost
port = 4803 <uint>4803
enabled = 1 <bool>1 # this is the default
[spread.converter.c++]
image = IplImage # wireSchema = dataType
[transport.inprocess]
foo = barbar
factor = 1.5 <double>1.5
enabled = 1 <bool>1
[plugins.c++]
path = /vol/vampire/lib:/vol/cor/lib
libraries = rsbspread:rsbvampire # no filetype suffix
</pre>
h3. Environment Variables
Environment variables are processed according to the following rules
# Variables whose names start with @RSB_@ are processed
# The @RSB_@ prefix is stripped form the name
# To obtain the name of the corresponding option, the remainder of the name is converted to lower case and split at @_@ characters
Example:
@RSB_TRANSPORT_SPREAD_PORT -> transport.spread.port@
The configuration mechanism is based on the following principles:
* We cannot (and do not want) to handle configuration of individual participants. The configuration mechanism is intended to provide process-wide defaults. Participants that require individual configurations have to be configured programmatically.
* The configuration mechanism works identically across implementation languages
* Configuration options are obtained from multiple configuration sources:
** Configuration files
** Environment variables
** _Commandline options (planned)_
* Configuration options are organized in a tree of name-value pairs
h2. Syntax and Semantics
Option names consist of multiple components which are specified in configuration-source-dependent syntax. For example, in configuration files section names like @[transport.spread]@ are concatenated with names of contained options like @port@ to obtain @transport.spread.port@. For environment variables, the name @RSB_TRANSPORT_SPREAD_PORT@ maps to @transport.spread.port@.
Currently the following option tree is defined (uppercase option name components are placeholders):
<pre>
+ qualityofservice
+-- reliability { UNRELIABLE, RELIABLE }
+-- ordering { UNORDERED, ORDERED }
+ errorhandling
+-- onhandlererror { LOG, PRINT, EXIT }
+ transport
+-- NAME
+---- enabled bool
+---- TRANSPORT_SPECIFIC_OPTION ?
+---- converter
+------ WIRE-SCHEMA string
+-- spread
+---- host string
+---- port uint
+-- inprocess
</pre>
h2. Processing Order
Configuration sources are processed in the following order such that options from sources which are processed later take precedence over options from sources which are processed earlier:
# Config file @${HOME}/.config/rsb.conf@
# Config file @$(pwd)/rsb.conf@
# Environment variables
h3. Example and test case
Consider the following situation:
* Contents of @${HOME}/.config/rsb.conf@:
<pre>
[transport.spread]
host = azurit
port = <uint>5301
</pre>
* Contents of @(pwd)/rsb.conf@
<pre>
[transport.spread]
host = localhost
</pre>
* Environment Variables
@RSB_TRANSPORT_SPREAD_PORT='<unit>4444'@
This would result in the following effective option values:
* @transport.spread.host = localhost@
* @transport.spread.port = 4444@
h2. Sources
The following sections briefly explains the currently defined configuration sources.
h3. Configuration Files
Configuration files use the following syntax, which is similar to INI-files or desktop-files:
* Comments are initiated by the @#@ character and extend to the end of the current line
* After removing comments, all lines have to be of one of the following forms:
** empty
** @[NAME]@ where @NAME@ consists of alphanumeric characters and colons
** @NAME = VALUE@ where @NAME@ consists of alphanumeric characters
Here is an example:
<pre>
[qualityofservice]
reliability = UNRELIABLE
ordering = UNORDERED
[errorhandling]
onhandlererror = LOG
[transport.spread]
host = localhost
port = 4803 <uint>4803
enabled = 1 <bool>1 # this is the default
[spread.converter.c++]
image = IplImage # wireSchema = dataType
[transport.inprocess]
foo = barbar
factor = 1.5 <double>1.5
enabled = 1 <bool>1
[plugins.c++]
path = /vol/vampire/lib:/vol/cor/lib
libraries = rsbspread:rsbvampire # no filetype suffix
</pre>
h3. Environment Variables
Environment variables are processed according to the following rules
# Variables whose names start with @RSB_@ are processed
# The @RSB_@ prefix is stripped form the name
# To obtain the name of the corresponding option, the remainder of the name is converted to lower case and split at @_@ characters
Example:
@RSB_TRANSPORT_SPREAD_PORT -> transport.spread.port@