Directive Development

Directives are implemented by a class, which must be a subclass of Directive. Each use of the directive in a configuraiton creates a new instance of the class.

Required Methods

Instance Loader

The first requirement for a directive implementation is creating the instance loader. This is a functor to be invoked by the configuration loader when the directive is used to create the instance. By convention this is named load.

The signature is

swoc::Rv<Directive::Handle> load(Config &cfg, CfgStaticData const *rtti, YAML::Node drtv_node, swoc::TextView const &name, swoc::TextView const &arg, YAML::Node key_value)
Parameters

  • cfg – Configuration instance.

  • rtti – Directive static data.

  • drtv_node – YAML node for the directive use.

  • name – Name of the directive.

  • arg – Argument to the directive.

  • key_value – Value of drtv_node.

This function is responsible for either creating a fully initialized instance of the directive class or an error report if that fails.

The configuration instance cfg is the configuration that is loading.

For each directive class, there is some configuration static data. This is passed via the rtti parameter which points at an instance of CfgStaticData. This value will also be available to the instance later via Directive::_rtti. This will be set by the configuration loader, it does not need to be set by the instance loader. In some cases, however, it is needed by the instance loader and because the instance has not yet been created it can’t be loaded from the directive instance.

A directive is always a map. drtv_node is the map node and key_value is the node for the value of the key that determined which directive the map is. name is the name of the directive as used to look up the instance loader and arg is the argument, if any. I.e. if the directive key is “proxy-rsp-field<Best-Band>” then name will be “proxy-rsp-field” and arg will be “Best-Band”.

The instance loader is responsible for all directive parsing, including any nested keys and the argument.

Optional Methods

Configuration Initializer

A directive can specify a static method to invoke the first time the directive is used in a configuration.

swoc::Errata cfg_init(Config &cfg, CfgStaticData const *rtti)
Parameters

  • cfg – Configuration instance.

  • rtti – Directive static data.

cfg`is the configuration instance and :arg:`rtti is the directive related static information. The primary use of this is a data structure that is shared among instances. This can be constructed in this method and stored in the rtti member _cfg_store.