Configuring Actor Applications

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.

void caf_main(actor_system& system) {
  // ...
}
CAF_MAIN(io::middleman)

The compiler expands this example code to the following.

void caf_main(actor_system& system) {
  // ...
}
int main(int argc, char** argv) {
  return exec_main<io::middleman>(caf_main, argc, argv);
}

The function exec_main performs several steps:

1. Initialize all meta objects for the type ID blocks listed in CAF_MAIN.

2. 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 uses actor_system_config.

3. Parse command line arguments and configuration file.

4. Load all modules requested in CAF_MAIN.

5. Create an actor system.

6. Call caf_main with the actor system and optionally with config.

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) {
  // Initialize 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:

CAF_BEGIN_TYPE_ID_BLOCK(my, first_custom_type_id)

  // ...

CAF_END_TYPE_ID_BLOCK(my)


class my_config : public actor_system_config {
public:
  my_config() {
    // ...
  }
};

void caf_main(actor_system& system, const my_config& cfg) {
  // ...
}

CAF_MAIN(id_block::my, io::middleman)

Loading Modules

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.

void caf_main(actor_system& system) {
  // ...
}
CAF_MAIN(mod1, mod2, ...)

Alternatively, users can load modules in user-defined config classes.

class my_config : public actor_system_config {
public:
  my_config() {
    load<mod1>();
    load<mod2>();
    // ...
  }
};

The third option is to simply call x.load<mod1>() on a config object before initializing an actor system with it.

Program Options

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.

class config : public actor_system_config {
public:
  uint16_t port = 0;
  std::string host = "localhost";
  bool server_mode = false;

  config() {
    opt_group{custom_options_, "global"}
      .add(port, "port,p", "set port")
      .add(host, "host,H", "set host (ignored in server mode)")
      .add(server_mode, "server-mode,s", "enable server mode");
  }
};

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.

Configuration Files

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.

# This file shows all possible parameters with defaults. For some values, CAF
# computes a value at runtime if the configuration does not provide a value. For
# example, "caf.scheduler.max-threads" has no hard-coded default and instead
# adjusts to the number of cores available.
caf {
  # Parameters selecting a default scheduler.
  scheduler {
    # Use the work stealing implementation. Accepted alternative: "sharing".
    policy = "stealing"
    # Maximum number of messages actors can consume in single run (int64 max).
    max-throughput = 9223372036854775807
    # # Maximum number of threads for the scheduler. No hardcoded default.
    # max-threads = ... (detected at runtime)
  }
  # Parameters for the work stealing scheduler. Only takes effect if
  # caf.scheduler.policy is set to "stealing".
  work-stealing {
    # Number of zero-sleep-interval polling attempts.
    aggressive-poll-attempts = 100
    # Frequency of steal attempts during aggressive polling.
    aggressive-steal-interval = 10
    # Number of moderately aggressive polling attempts.
    moderate-poll-attempts = 500
    # Frequency of steal attempts during moderate polling.
    moderate-steal-interval = 5
    # Sleep interval between poll attempts.
    moderate-sleep-duration = 50us
    # Frequency of steal attempts during relaxed polling.
    relaxed-steal-interval = 1
    # Sleep interval between poll attempts.
    relaxed-sleep-duration = 10ms
  }
  # Parameters for the I/O module.
  middleman {
    # Configures whether MMs try to span a full mesh.
    enable-automatic-connections = false
    # Application identifiers of this node, prevents connection to other CAF
    # instances with incompatible identifiers.
    app-identifiers = ["generic-caf-app"]
    # Maximum number of consecutive I/O reads per broker.
    max-consecutive-reads = 50
    # Heartbeat message interval in ms (0 disables heartbeating).
    heartbeat-interval = 0ms
    # Configures whether the MM attaches its internal utility actors to the
    # scheduler instead of dedicating individual threads (needed only for
    # deterministic testing).
    attach-utility-actors = false
    # # Configures how many background workers are spawned for deserialization.
    # # No hardcoded default.
    # workers = ... (detected at runtime)
  }
  # Parameters for logging.
  logger {
    # # Note: File logging is disabled unless a 'file' section exists that
    # # contains a setting for 'verbosity'.
    # file {
    #   # File name template for output log files.
    #   path = "actor_log_[PID]_[TIMESTAMP]_[NODE].log"
    #   # Format for rendering individual log file entries.
    #   format = "%r %c %p %a %t %M %F:%L %m%n"
    #   # Minimum severity of messages that are written to the log. One of:
    #   # 'quiet', 'error', 'warning', 'info', 'debug', or 'trace'.
    #   verbosity = "trace"
    #   # A list of components to exclude in file output.
    #   excluded-components = []
    # }
    # # Note: Console output is disabled unless a 'console' section exists that
    # # contains a setting for 'verbosity'.
    # console {
    #   # Enabled colored output when writing to a TTY if set to true.
    #   colored = true
    #   # Format for printing log lines (implicit newline at the end).
    #   format = "[%c:%p] %d %m"
    #   # Minimum severity of messages that are written to the console. One of:
    #   # 'quiet', 'error', 'warning', 'info', 'debug', or 'trace'.
    #   verbosity = "trace"
    #   # A list of components to exclude in console output.
    #   excluded-components = []
    # }
  }
}

Adding Custom Message Types

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.

struct foo;
struct foo2;

CAF_BEGIN_TYPE_ID_BLOCK(custom_types_1, first_custom_type_id)

  CAF_ADD_TYPE_ID(custom_types_1, (foo))
  CAF_ADD_TYPE_ID(custom_types_1, (foo2))
  CAF_ADD_TYPE_ID(custom_types_1, (std::pair<int32_t, int32_t>) )

CAF_END_TYPE_ID_BLOCK(custom_types_1)

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.

struct foo {
  std::vector<int> a;
  int b;
};

template <class Inspector>
bool inspect(Inspector& f, foo& x) {
  return f.object(x).fields(f.field("a", x.a), f.field("b", x.b));
}

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 of 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 Custom Error Types

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 Add Custom Error Categories.

Adding Custom Actor Types ^experimental

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 Spawning of Actors). For our example configuration, we consider the following simple calculator actor.

struct calculator_trait {
  using signatures
    = caf::type_list<caf::result<int32_t>(caf::add_atom, int32_t, int32_t),
                     caf::result<int32_t>(caf::sub_atom, int32_t, int32_t)>;
};
using calculator = caf::typed_actor<calculator_trait>;

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>.

auto x = system.spawn<calculator>("calculator", make_message());
if (! x) {
  std::cerr << "*** unable to spawn calculator: " << to_string(x.error())
            << std::endl;
  return;
}
calculator c = std::move(*x);

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:

auto worker = system.spawn<actor>("foo", make_message("bar"));

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.

Log Output

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

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

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.

Format Strings

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	Recognized only for historic reasons. Will always print null.
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.

Filtering

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.