Table of Contents
This chapter contains the following section:
The INKConfig
family of functions provides a
mechanism for accessing and changing global configuration information
within a plugin.
The functions discussed in this section do not examine or modify Traffic Server configuration variables. To examine Traffic Server configuration and statistics variables, see “Reading Traffic Server Settings and Statistics”.
The INKConfig
family of functions is 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.
The INKConfig
family of 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 INKConfigSet
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
INKConfigSet
for all global data updates.
Here’s how the interface works:
/* Assume that you have previously defined a plugin configuration * data structure named ConfigData, along with its constructor * plugin_config_allocator () and its destructor * plugin_config_destructor (ConfigData *data) */ ConfigData *plugin_config; /* You will need to assign plugin_config a unique identifier of type * unsigned int. It is important to initialize this identifier to zero * (see the documentation of the function). */ static unsigned int my_id = 0; /* You will need an INKConfig pointer to access a snapshot of the * current plugin_config. */ INKConfig config_ptr; /* Initialize plugin_config. */ plugin_config = plugin_config_allocator(); /* Assign plugin_config an identifier using INKConfigSet. */ my_id = INKConfigSet (my_id, plugin_config, plugin_config_destructor); /* Get a snapshot of the current configuration using INKConfigGet. */ config_ptr = INKConfigGet (my_id); /* With an INKConfig pointer to the current configuration, you can * retrieve the configuration’s current data using INKConfigDataGet. */ plugin_config = (ConfigData*) INKConfigDataGet (config_ptr); /* Do something with plugin_config here. */ /* When you are done with retrieving or modifying the plugin data, you * release the pointers to the data with a call to INKConfigRelease. */ INKConfigRelease (my_id, config_ptr); /* Any time you want to modify plugin_config, you must repeat these * steps, starting with * my_id = INKConfigSet (my_id,plugin_config, plugin_config_destructor); * and continuing up to INKConfigRelease. */
The configuration functions are: