NAME

       TSConfig Functions - TSConfig API function

SYNOPSIS

          #include <ts/ts.h>

       typedef void (*TSConfigDestroyFunc)(void*)

       unsigned int TSConfigSet(unsigned int id, void *data, TSConfigDestroyFunc funcp)

       TSConfig TSConfigGet(unsigned int id)

       void TSConfigRelease(unsigned int id, TSConfig configp)

       void *TSConfigDataGet(TSConfig configp)

DESCRIPTION

       These functions provide a mechanism to safely update configurations for a plugin.

       If  a  plugin stores its configuration in a data structure, updating that structure due to changes in the
       configuration file can be dangerous due to the asynchronous nature of plugin  callbacks.  To  avoid  that
       problem these functions allow a plugin to register a configuration and then later replace it with another
       instance  without  changing  the  instance  in  use by plugin callbacks. This works in the same manner as
       shared pointer. When a plugin needs to access  the  configuration  data,  it  calls  TSConfigGet()  which
       returns  a  pointer  that  will  remain valid until the plugin calls TSConfigRelease(). The configuration
       instance is updated with TSConfigSet() which will update an internal pointer  but  will  not  change  any
       instance  in  use  via  TSConfigGet(). When the last in use pointer is released, the old configuration is
       destructed using the function passed to func:TSConfigSet.  This  handles  the  overlapping  configuration
       update case correctly.

       Initialization is done with TSConfigSet(). The id should be zero on the first call.  This will allocate a
       slot  for  the  configuration,  which is returned. Subsequent calls must use this value. If the id is not
       zero, that value is returned. In general, the code will look something like

          class Config { ... }; // Configuration data.
          int Config_Id = 0;
          //...
          void ConfigUpdate() {
             Config* cfg = new Config;
             cfg.load(); // load config...
             Config_Id = TSConfigSet(Config_Id, cfg,
                [](void* cfg){delete static_cast<Config*>(config);});
          }
          //...
          PluginInit() {
             // ...
             ConfigUpdate();
             // ...
          }

       Config_Id is a global variable holding the configuration id, which is updated  by  the  return  value  of
       TSConfigSet().

       The  configuration  instance is retrieved with TSConfigGet(). This returns a wrapper class from which the
       configuration can be extracted with TSConfigDataGet(). The wrapper is used to release  the  configuration
       instance when it is no longer in use. The code in a callback tends to look like

          int callback() {
             auto cfg_ref = TSConfigGet(Config_Id);
             Config* cfg = static_cast<Config*>(TSConfigDataGet(cfg_ref));
             // ... use cfg
             TSConfigRelease(Config_Id, cfg_ref);
          }

COPYRIGHT

       2024, dev@trafficserver.apache.org

9.2                                               Apr 01, 2024                           TSCONFIG FUNCTIONS(3ts)