Plugin Configuration

The functions discussed in this section do not examine or modify Traffic Server configuration variables. To examine Traffic Server configuration and statistics variables, see Settings and Statistics.

The collection of TSConfig* functions are designed to provide a fast and efficient mechanism for accessing and changing global configuration information within a plugin. Such a mechanism is simple enough to provide in a single-threaded program, but the translation to a multi-threaded program such as Traffic Server is difficult. A common technique is to have a single mutex protect the global configuration information; however, the problem with this solution is that a single mutex becomes a performance bottleneck very quickly.

These functions define an interface to storing and retrieving an opaque data pointer. Internally, Traffic Server maintains reference count information about the data pointer so that a call to TSConfigSet() will not disturb another thread using the current data pointer. The philosophy is that once a user has a hold of the configuration pointer, it is okay for it to be used even if the configuration changes. All that a user typically wants is a non-changing snapshot of the configuration. You should use TSConfigSet() for all global data updates.

Here’s how the interface works:

  1. /* Assume that you have previously defined a plugin configuration
  2.  * data structure named ConfigData, along with its constructor
  3.  * plugin_config_allocator () and its destructor
  4.  * plugin_config_destructor (ConfigData *data)
  5.  */
  6. ConfigData *plugin_config;
  8. /* You will need to assign plugin_config a unique identifier of type
  9.  * unsigned int. It is important to initialize this identifier to zero
  10.  * (see the documentation of the  function).
  11.  */
  12. static unsigned int   my_id = 0;
  14. /* You will need an TSConfig pointer to access a snapshot of the
  15.  * current plugin_config.
  16.  */
  17. TSConfig config_ptr;
  19. /* Initialize plugin_config. */
  20. plugin_config = plugin_config_allocator();
  22. /* Assign plugin_config an identifier using TSConfigSet. */
  23. my_id = TSConfigSet (my_id, plugin_config, plugin_config_destructor);
  25. /* Get a snapshot of the current configuration using TSConfigGet. */
  26. config_ptr = TSConfigGet (my_id);
  28. /* With an TSConfig pointer to the current configuration, you can
  29.  * retrieve the configuration's current data using TSConfigDataGet.
  30.  */
  31. plugin_config = (ConfigData*) TSConfigDataGet (config_ptr);
  33. /* Do something with plugin_config here. */
  35. /* When you are done with retrieving or modifying the plugin data, you
  36.  * release the pointers to the data with a call to TSConfigRelease.
  37.  */
  38. TSConfigRelease (my_id, config_ptr);
  40. /* Any time you want to modify plugin_config, you must repeat these
  41.  * steps, starting with
  42.  * my_id = TSConfigSet (my_id,plugin_config, plugin_config_destructor);
  43.  * and continuing up to TSConfigRelease.
  44.  */

The configuration functions are: