You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by am...@apache.org on 2014/05/19 22:07:50 UTC
git commit: Add documenation about adding configuration variables.
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 <am...@network-geographics.com>
Authored: Mon May 19 14:31:58 2014 -0500
Committer: Alan M. Carroll <am...@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