trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a..@apache.org
Subject git commit: Add documenation about adding configuration variables.
Date Mon, 19 May 2014 20:07:50 GMT
Repository: trafficserver
Updated Branches:
  refs/heads/master 442defed1 -> 05f4db0d9


Add documenation about adding configuration variables.


Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/05f4db0d
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/05f4db0d
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/05f4db0d

Branch: refs/heads/master
Commit: 05f4db0d91f7ab5480aaf984fa356e4629bf042c
Parents: 442defe
Author: Alan M. Carroll <amc@network-geographics.com>
Authored: Mon May 19 14:31:58 2014 -0500
Committer: Alan M. Carroll <amc@network-geographics.com>
Committed: Mon May 19 14:31:58 2014 -0500

----------------------------------------------------------------------
 doc/arch/hacking/config-var-impl.en.rst | 248 +++++++++++++++++++++++++++
 doc/arch/hacking/index.en.rst           |   2 -
 2 files changed, 248 insertions(+), 2 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/trafficserver/blob/05f4db0d/doc/arch/hacking/config-var-impl.en.rst
----------------------------------------------------------------------
diff --git a/doc/arch/hacking/config-var-impl.en.rst b/doc/arch/hacking/config-var-impl.en.rst
new file mode 100644
index 0000000..5f2df2d
--- /dev/null
+++ b/doc/arch/hacking/config-var-impl.en.rst
@@ -0,0 +1,248 @@
+.. 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.
+
+.. Referenced source files
+
+.. |RecCore.cc| replace:: ``RecCore.cc``
+
+.. _RecCore.cc: https://github.com/apache/trafficserver/blob/master/lib/records/RecCore.cc
+
+.. |RecordsConfig.cc| replace:: ``RecordsConfig.cc``
+
+.. _RecordsConfig.cc: https://github.com/apache/trafficserver/blob/master/mgmt/RecordsConfig.cc
+
+.. |ts.h.in| replace:: ``ts.h.in``
+
+.. _ts.h.in: https://github.com/apache/trafficserver/blob/master/proxy/api/ts/ts.h.in
+
+.. |InkAPI.cc| replace:: ``InkAPI.cc``
+
+.. _InkAPI.cc: https://github.com/apache/trafficserver/blob/master/proxy/api/InkAPI.cc
+
+.. |InkAPITest.cc| replace:: ``InkAPITest.cc``
+
+.. _InkAPITest.cc: https://github.com/apache/trafficserver/blob/master/proxy/api/InkAPITest.cc
+
+.. Referenced enumeration values
+
+.. |RECU_DYNAMIC| replace:: ``RECU_DYNAMIC``
+
+.. _RECU_DYNAMIC: recu-dynamic_
+
+
+=====================================
+Configuration Variable Implementation
+=====================================
+
+Adding a new configuration variable in :file:`records.config` requires a number of steps
which are mostly documented
+here.
+
+Before adding a new configuration variable, please discuss it on the mailing list. It will
commonly be the case that a
+better name will be suggested or a more general approach to the problem which solves several
different issues.
+
+=====================================
+Defining the Variable
+=====================================
+
+To begin the new configuration variables must be added to |RecordsConfig.cc|_. This contains
a long array of
+configuration variable records. The fields for each record are
+
+type:``RecT``
+   Type of record. There valid values are
+
+   ``RECT_NULL``
+      Undefined record.
+
+   ``RECT_CONFIG``
+      General configuration variable.
+
+   ``RECT_PROCESS``
+      Process related statistic.
+
+   ``RECT_NODE``
+      Local statistic.
+
+   ``RECT_CLUSTER``
+      Cluster statistic.
+
+   ``RECT_LOCAL``
+      Configuration variable that is explicitly not shared across a cluster.
+
+   ``RECT_PLUGIN``
+      Plugin created statistic.
+
+   In general ``RECT_CONFIG`` should be used unless it is required that the value not be
shared among members of a
+   cluster in which case ``RECT_LOCAL`` should be used.
+
+name:string
+   The fully qualified name of the configuration variable. Although there appears to be a
hierarchial naming scheme,
+   that's just a convention, it is not actually used by the code. Nonetheless new variables
should adhere to the
+   hierarchial scheme.
+
+value_type:``RecDataT``
+   The data type of the value. It should be one of ``RECD_INT``, ``RECD_STRING``, ``RECD_FLOAT``
as appropriate.
+
+default:string
+   The default value for the variable. This is always a string regardless of the *value_type*.
+
+update:``RecUpdateT``
+   Information about how the variable is updated. The valid values are
+
+   ``RECU_NULL``
+      Behavior is unknown or unspecified.
+
+.. _recu-dynamic:
+
+   ``RECU_DYNAMIC``
+      This can be updated via command line tools.
+
+   ``RECD_RESTART_TS``
+      The :program:`traffic_server` process must be restarted for a new value to take effect.
+
+   ``RECD_RESTART_TM``
+      The :program:`traffic_manager`` process must be restarted for a new value to take effect.
+
+   ``RECD_RESTART_TC``
+      The :program:`traffic_cop`` process must be restarted for a new value to take effect.
+
+required:``RecordRequiredType``
+   Effectively a boolean that specifies if the record is required to be present, with ``RR_NULL``
meaning not required
+   and ``RR_REQUIRED`` indicating that it is required. Given that using ``RR_REQUIRED`` would
be a major
+   incompatibility, ``RR_NULL`` is generally the better choice.
+
+check:``RecCheckT``
+   Additional type checking. It is unclear if this is actually implemented. The valid values
are
+
+   ``RECC_NULL``
+      No additional checking.
+
+   ``RECC_STR``
+      Verify the value is a string.
+
+   ``RECC_INT``
+      Verify the value is an integer.
+
+   ``RECC_IP``
+      Verify the value is an IP address. Unknown if this checks for IPv6.
+
+pattern:regular expression
+   Even more validity checking. This provides a regular expressions (PCRE format) for validating
the value. This can be
+   ``NULL`` if there is no regular expression to use.
+
+access:``RecAccessT``
+   Access control. The valid values are
+
+   ``RECA_NULL``
+      The value is read / write.
+
+   ``RECA_READ_ONLY``
+      The value is read only.
+
+   ``RECA_NO_ACCESS``
+      No access to the value - only privileged levels parts of the ATS can access the value.
+
+=====================================
+Variable Infrastructure
+=====================================
+
+The primary effort in defining a configuration variable is handling updates, generally via
:program:`traffic_line`. This
+is handled in a generic way, as described in the next section, or in a :ref:`more specialized
way
+<http-config-var-impl>` (built on top of the generic mechanism) for HTTP related configuration
variables. This is only
+needed if the variable is marked as dynamically updateable (|RECU_DYNAMIC|_) although HTTP
configuration variables
+should be dynamic if possible.
+
+------------------------------
+Handling Updates
+------------------------------
+
+The simplest mechanism for handling updates is the ``REC_EstablishStaticConfigXXX`` family
of functions. This mechanism
+will cause the value in the indicated instance to be updated in place when an update to :file:`records.config`
occurs.
+This is done asynchronously using atomic operations. Use of these variables must keep that
in mind.
+
+If a variable requires additional handling when updated a callback can be registered which
is called when the variable
+is updated. This is what the ``REC_EstablishStaticConfigXXX`` calls do internally with a
callback that simply reads the
+new value and writes it to storage indicated by the call parameters. The functions used are
the ``link_XXX`` static
+functions in |RecCore.cc|_.
+
+To register a configuration variable callback, call ``RecRegisterConfigUpdateCb`` with the
arguments
+
+``char const*`` *name*
+   The variable name.
+
+*callback*
+   A function with the signature ``<int (char const* name, RecDataT type, RecData data,
void* cookie)>``. The *name*
+   value passed is the same as the *name* passed to the registration function as is the *cookie*
argument. The *type* and
+   *data* are the new value for the variable. The return value is currently ignored. For
future compatibility return
+   ``REC_ERR_OKAY``.
+
+``void*`` *cookie*
+   A value passed to the *callback*.
+
+The *callback* is called under lock so it should be quick and not block. If that is necessary
a continuation should be
+scheduled to handle the required action.
+
+.. note::
+   The callback occurs asynchronously. For HTTP variables as described in the next section,
this is handled by the more
+   specialized HTTP update mechanisms. Otherwise it is the implementor's responsibility to
avoid race conditions.
+
+.. _http-config-var-impl:
+
+------------------------
+HTTP Configuation Values
+------------------------
+
+Variables used for HTTP processing should be declared as members of the ``HTTPConfigParams``
structure (but :ref:`see
+<overridable-config-vars>`) and use the specialized HTTP update mechanisms which handle
synchronization and
+initialization issues.
+
+The configuration logic maintains two copies of the ``HTTPConfigParams`` structure - the
master copy and the current
+copy. The master copy is kept in the ``m_master`` member of the ``HttpConfig`` singleton.
The current copy is kept in
+the ConfigProcessor. The goal is to provide a (somewhat) atomic update for configuration
variables which are loaded
+individually in to the master copy as updates are received and then bulk copied to a new
instance which is then swapped
+in as the current copy. The HTTP state machine interacts with this mechanism to avoid race
conditions.
+
+For each variable a mapping between the variable name and the appropriate member in the master
copy should be
+established between in the ``HTTPConfig::startup`` method. The ``HttpEstablishStaticConfigXXX``
functions should be used
+unless there is an strong, explicit reason to not do so.
+
+The ``HTTPConfig::reconfigure`` method handles the current copy of the HTTP configuration
variables. Logic should be
+added here to copy the value from the master copy to the current copy. Generally this will
be a simple assignment. If
+there are dependencies between variables those should be enforced / checked in this method.
+
+.. _overridable-config-vars:
+
+-----------------------
+Overridable Variables
+-----------------------
+
+HTTP related variables that are changeable per transaction are stored in the ``OverridableHttpConfigParams``
structure,
+an instance of which is the ``oride`` member of ``HTTPConfigParams`` and therefore the points
in the previous section
+still apply. The only difference for that is the further ``.oride`` in the structure references.
+
+In addition the variable is required to be accessible from the transaction API. In addition
to any custom API functions
+used to access the value, the following items are required for generic access
+
+#. Add a value to the ``TSOverridableConfigKey`` enumeration in |ts.h.in|_.
+
+#. Augment the ``TSHttpTxnConfigFind`` function to return this enumeration value when given
the name of the configuration
+   variable. Be sure to count the charaters very carefully.
+
+#. Augment the ``_conf_to_memberp`` function in |InkAPI.cc|_ to return a pointer to the appropriate
member of
+   ``OverridableHttpConfigParams`` and set the type if not a byte value.
+
+#. Update the testing logic in |InkAPITest.cc|_ by adding the string name of the configuration
variable to the
+   ``SDK_Overridable_Configs`` array.

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/05f4db0d/doc/arch/hacking/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/arch/hacking/index.en.rst b/doc/arch/hacking/index.en.rst
index 1c5b2c2..84e997a 100644
--- a/doc/arch/hacking/index.en.rst
+++ b/doc/arch/hacking/index.en.rst
@@ -27,6 +27,4 @@ and run unit or regression tests or how to inspect the state of the core
with a
 .. toctree::
    :maxdepth: 1
 
-.. This is not used it seems, certainly doesn't exist...
-
    config-var-impl.en


Mime
View raw message