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

       2022, dev@trafficserver.apache.org