CAF configures applications at startup using an actor_system_config
or a user-defined subclass of that type. The config objects allow users to add custom types, to load modules, and to fine-tune the behavior of loaded modules with command line options or configuration files system-config-options.
The following code example is a minimal CAF application with a middleman
but without any custom configuration options.
The compiler expands this example code to the following.
The function exec_main
performs several steps:
- Initialize all meta objects for the type ID blocks listed in
CAF_MAIN
. - Create a config object. If
caf_main
has two arguments, then CAF assumes that the second argument is the configuration and the type gets derived from that argument. Otherwise, CAF usesactor_system_config
. - Parse command line arguments and configuration file.
- Load all modules requested in
CAF_MAIN
. - Create an actor system.
- Call
caf_main
with the actor system and optionally withconfig
.
When implementing the steps performed by CAF_MAIN
by hand, the main
function would resemble the following (pseudo) code:
int main(int argc, char** argv) {
// Initialze the global type information before anything else.
init_global_meta_objects<...>();
core::init_global_meta_objects();
// Create the config.
actor_system_config cfg;
// Read CLI options.
cfg.parse(argc, argv);
// Return immediately if a help text was printed.
if (cfg.cli_helptext_printed)
return 0;
// Load modules.
cfg.load<...>();
// Create the actor system.
actor_system sys{cfg};
// Run user-defined code.
caf_main(sys, cfg);
}
Using CAF_MAIN
simply automates that boilerplate code. A minimal example with a custom type ID block as well as a custom configuration class with the I/O module loaded looks as follows:
The simplest way to load modules is to use the macro CAF_MAIN
and to pass a list of all requested modules, as shown below.
Alternatively, users can load modules in user-defined config classes.
The third option is to simply call x.load<mod1>()
on a config object before initializing an actor system with it.
CAF organizes program options in categories and parses CLI arguments as well as configuration files. CLI arguments override values in the configuration file which override hard-coded defaults. Users can add any number of custom program options by implementing a subtype of actor_system_config
. The example below adds three options to the global
category.
/examples/remoting/distributed_calculator.cpp
We create a new global
category in custom_options_
. Each following call to add
then appends individual options to the category. The first argument to add
is the associated variable. The second argument is the name for the parameter, optionally suffixed with a comma-separated single-character short name. The short name is only considered for CLI parsing and allows users to abbreviate commonly used option names. The third and final argument to add
is a help text.
The custom config
class allows end users to set the port for the application to 42 with either -p 42
(short name) or --port=42
(long name). The long option name is prefixed by the category when using a different category than global
. For example, adding the port option to the category foo
means end users have to type --foo.port=42
when using the long name. Short names are unaffected by the category, but have to be unique.
Boolean options do not require arguments. The member variable server_mode
is set to true
if the command line contains either --server-mode
or -s
.
The example uses member variables for capturing user-provided settings for simplicity. However, this is not required. For example, add<bool>(...)
allows omitting the first argument entirely. All values of the configuration are accessible with get_or
. Note that all global options can omit the "global."
prefix.
CAF adds the program options help
(with short names -h
and -?
) as well as long-help
to the global
category.
The default name for the configuration file is caf-application.conf
. Users can change the file path by passing --config-file=<path>
on the command line.
The syntax for the configuration files provides a clean JSON-like grammar that is similar to other commonly used configuration formats. In a nutshell, instead of writing:
{
"my-category" : {
"first" : 1,
"second" : 2
}
}
you can reduce the noise by writing:
my-category {
first = 1
second = 2
}
Note
CAF will accept both of the examples above and will produce the same result. We recommend using the second style, mostly because it reduces syntax noise.
Unlike regular JSON, CAF's configuration format supports a couple of additional syntax elements such as comments (comments start with #
and end at the end of the line) and, most notably, does not accept null
.
The parses uses the following syntax for writing key-value pairs:
key=true |
is a boolean |
key=1 |
is an integer |
key=1.0 |
is an floating point number |
key=1ms |
is an timespan |
key='foo' |
is a string |
key="foo" |
is a string |
key=[0, 1, ...] |
is as a list |
key={a=1, b=2, ...} |
is a dictionary (map) |
The following example configuration file lists all standard options in CAF and their default value. Note that some options such as scheduler.max-threads
are usually detected at runtime and thus have no hard-coded default.
/examples/caf-application.conf
CAF requires serialization support for all of its message types (see type-inspection
). However, CAF also needs a mapping of unique type IDs to user-defined types at runtime. This is required to deserialize arbitrary messages from the network.
The type IDs are assigned by listing all custom types in a type ID block. CAF assigns ascending IDs to each type by in the block as well as storing the type name. In the following example, we forward-declare the types foo
and foo2
and register them to CAF in a type ID block. The name of the type ID block is arbitrary, but it must be a valid C++ identifier.
/examples/custom_type/custom_types_1.cpp
Aside from a type ID, CAF also requires an inspect
overload in order to be able to serialize objects. As an introductory example, we (again) use the following POD type foo
.
/examples/custom_type/custom_types_1.cpp
By assigning type IDs and providing inspect
overloads, we provide static and compile-time information for all our types. However, CAF also needs some information at run-time for deserializing received data. The function init_global_meta_objects
takes care fo registering all the state we need at run-time. This function usually gets called by CAF_MAIN
automatically. When not using this macro, users must call init_global_meta_objects
before any other CAF function.
Adding a custom error type to the system is a convenience feature to allow improve the string representation. Error types can be added by implementing a render function and passing it to add_error_category
, as shown in custom-error
.
Adding actor types to the configuration allows users to spawn actors by their name. In particular, this enables spawning of actors on a different node (see remote-spawn
). For our example configuration, we consider the following simple calculator
actor.
/examples/remoting/remote_spawn.cpp
Adding the calculator actor type to our config is achieved by calling add_actor_type
. After calling this in our config, we can spawn the calculator
anywhere in the distributed actor system (assuming all nodes use the same config). Note that the handle type still requires a type ID (see custom-message-types).
Our final example illustrates how to spawn a calculator
locally by using its type name. Because the dynamic type name lookup can fail and the construction arguments passed as message can mismatch, this version of spawn
returns expected<T>
.
Adding dynamically typed actors to the config is achieved in the same way. When spawning a dynamically typed actor in this way, the template parameter is simply actor
. For example, spawning an actor "foo" which requires one string is created with:
Because constructor (or function) arguments for spawning the actor are stored in a message
, only actors with appropriate input types are allowed. For example, pointer types are illegal. Hence users need to replace C-strings with std::string
.
Logging is disabled in CAF per default. It can be enabled by setting the --with-log-level=
option of the configure
script to one of error
, warning
, info
, debug
, or trace
(from least output to most). Alternatively, setting the CMake variable CAF_LOG_LEVEL
to one of these values has the same effect.
All logger-related configuration options listed here and in system-config-options are silently ignored if logging is disabled.
File output is disabled per default. Setting caf.logger.file.verbosity
to a valid severity level causes CAF to print log events to the file specified in caf.logger.file.path
.
The caf.logger.file.path
may contain one or more of the following placeholders:
Variable | Output |
[PID] |
The OS-specific process ID. |
[TIMESTAMP] |
The UNIX timestamp on startup. |
[NODE] |
The node ID of the CAF system. |
Console output is disabled per default. Setting caf.logger.console.verbosity
to a valid severity level causes CAF to print log events to std::clog
.
CAF uses log4j-like format strings for configuring printing of individual events via caf.logger.file.format
and caf.logger.console.format
. Note that format modifiers are not supported at the moment. The recognized field identifiers are:
Character | Output |
c |
The category/component. |
C |
The full qualifier of the current function. For example, the qualifier of void ns::foo::bar() is printed as ns.foo . |
d |
The date in ISO 8601 format, i.e., "YYYY-MM-DDThh:mm:ss" . |
F |
The file name. |
L |
The line number. |
m |
The user-defined log message. |
M |
The name of the current function. For example, the name of void ns::foo::bar() is printed as bar . |
n |
A newline. |
p |
The priority (severity level). |
r |
Elapsed time since starting the application in milliseconds. |
t |
ID of the current thread. |
a |
ID of the current actor (or actor0 when not logging inside an actor). |
% |
A single percent sign. |
The two configuration options caf.logger.file.excluded-components
and caf.logger.console.excluded-components
reduce the amount of generated log events in addition to the minimum severity level. These parameters are lists of component names that shall be excluded from any output.