TSConfig Functions

Synopsis

  1. #include <ts/ts.h>

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

  1. class Config { ... }; // Configuration data.
  2. int Config_Id = 0;
  3. //...
  4. void ConfigUpdate() {
  5.    Config* cfg = new Config;
  6.    cfg.load(); // load config...
  7.    Config_Id = TSConfigSet(Config_Id, cfg,
  8.       [](void* cfg){delete static_cast<Config*>(config);});
  9. }
  10. //...
  11. PluginInit() {
  12.    // ...
  13.    ConfigUpdate();
  14.    // ...
  15. }

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

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