doc/sdk/plugin-configurations.en.rst

Plugin Configurations
*********************

.. Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at
 
   http://www.apache.org/licenses/LICENSE-2.0
 
  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.

This chapter contains the following section:

.. toctree::
   :maxdepth: 1

Plugin Configurations
---------------------

The ``TSConfig`` 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" <../plugin-management/reading-trafficserver-settings-and-statistics>`__

The ``TSConfig`` 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 ``TSConfig`` 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
``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:

::

        ::::c
    /* 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 TSConfig pointer to access a snapshot of the 
     * current plugin_config. 
     */
    TSConfig config_ptr;

    /* Initialize plugin_config. */
    plugin_config = plugin_config_allocator();

    /* Assign plugin_config an identifier using TSConfigSet. */
    my_id = TSConfigSet (my_id, plugin_config, plugin_config_destructor);

    /* Get a snapshot of the current configuration using TSConfigGet. */
    config_ptr = TSConfigGet (my_id);

    /* With an TSConfig pointer to the current configuration, you can 
     * retrieve the configuration's current data using TSConfigDataGet. 
     */
    plugin_config = (ConfigData*) TSConfigDataGet (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 TSConfigRelease.
     */
    TSConfigRelease (my_id, config_ptr);

    /* Any time you want to modify plugin_config, you must repeat these
     * steps, starting with 
     * my_id = TSConfigSet (my_id,plugin_config, plugin_config_destructor);
     * and continuing up to TSConfigRelease. 
     */

The configuration functions are:

-  ```TSConfigDataGet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#aed2a6f9d350935ac890f75fdd80605db>`__

-  ```TSConfigGet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a478189d6ad87c6b873d8676cb51508c5>`__

-  ```TSConfigRelease`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a06711d4a0e70f1ff27f9b5ca34bb649c>`__

-  ```TSConfigSet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a8bba9468fdca478e68035a9776f6e9ca>`__