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/21 20:55:27 UTC
git commit: Doc: fix minor issues in configuration var implementation
documentation.
Repository: trafficserver
Updated Branches:
refs/heads/master f9172eb6d -> a4fc1dfea
Doc: fix minor issues in configuration var implementation documentation.
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/a4fc1dfe
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/a4fc1dfe
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/a4fc1dfe
Branch: refs/heads/master
Commit: a4fc1dfea6fa4227484eb81ddac4c499f0e18acb
Parents: f9172eb
Author: Alan M. Carroll <am...@network-geographics.com>
Authored: Wed May 21 13:54:52 2014 -0500
Committer: Alan M. Carroll <am...@network-geographics.com>
Committed: Wed May 21 13:55:18 2014 -0500
----------------------------------------------------------------------
doc/arch/hacking/config-var-impl.en.rst | 26 ++++++++++------------
doc/reference/commands/traffic_cop.en.rst | 2 ++
doc/reference/commands/traffic_manager.en.rst | 2 ++
doc/reference/commands/traffic_server.en.rst | 2 ++
4 files changed, 18 insertions(+), 14 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a4fc1dfe/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
index 722e358..75a80e1 100644
--- a/doc/arch/hacking/config-var-impl.en.rst
+++ b/doc/arch/hacking/config-var-impl.en.rst
@@ -86,9 +86,9 @@ type:``RecT``
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.
+ cluster in which case ``RECT_LOCAL`` should be used. If you use ``RECT_LOCAL`` you must also start the line with ``LOCAL`` instead of ``CONFIG`` and the name should use ``.local.`` instead of ``.config.``.
-name:string
+name:``char const*``
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.
@@ -96,7 +96,7 @@ name:string
value_type:``RecDataT``
The data type of the value. It should be one of ``RECD_INT``, ``RECD_STRING``, ``RECD_FLOAT`` as appropriate.
-default:string
+default:``char const*``
The default value for the variable. This is always a string regardless of the *value_type*.
update:``RecUpdateT``
@@ -111,13 +111,13 @@ update:``RecUpdateT``
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.
+ The :ref:`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.
+ The :ref:`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.
+ The :ref:`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
@@ -139,7 +139,7 @@ check:``RecCheckT``
``RECC_IP``
Verify the value is an IP address. Unknown if this checks for IPv6.
-pattern:regular expression
+pattern:``char const*``
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.
@@ -159,7 +159,7 @@ access:``RecAccessT``
Variable Infrastructure
=====================================
-The primary effort in defining a configuration variable is handling updates, generally via :program:`traffic_line`. This
+The primary effort in defining a configuration variable is handling updates, generally via :option:`traffic_line -x`. 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
@@ -198,9 +198,7 @@ If you need to refer to another configuration variable in the documentation, you
This will display the name as a link to the definition.
-In general a new configuration variable should be present in the default :file:`records.config`. Although users should peruse this documentation that is not as frequent an occurence as we would like. It is much more common to read through :file:`records.config` for values that can be tuned.
-
-Such defaults should be added to the file ``proxy/config/records.config.default.in``. This is used to generate the default :file:`records.config`. Just add the variable to the file in an appropriate place with a proper default as this will now override whatever default you put in the code for new installs.
+In general a new configuration variable should not be present in the default :file:`records.config`. If it is added, such defaults should be added to the file ``proxy/config/records.config.default.in``. This is used to generate the default :file:`records.config`. Just add the variable to the file in an appropriate place with a proper default as this will now override whatever default you put in the code for new installs.
------------------------------
Handling Updates
@@ -208,7 +206,7 @@ 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.
+This is done asynchronously using atomic operations. Use of these variables must keep that in mind. Adding ``volatile`` to the declaration is likely to be a good idea.
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
@@ -227,9 +225,9 @@ To register a configuration variable callback, call ``RecRegisterConfigUpdateCb`
``REC_ERR_OKAY``.
``void*`` *cookie*
- A value passed to the *callback*.
+ A value passed to the *callback*. This is only for the callback, the internals simply store it and pass it on.
-The *callback* is called under lock so it should be quick and not block. If that is necessary a continuation should be
+*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::
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a4fc1dfe/doc/reference/commands/traffic_cop.en.rst
----------------------------------------------------------------------
diff --git a/doc/reference/commands/traffic_cop.en.rst b/doc/reference/commands/traffic_cop.en.rst
index 8d6e09b..23808c3 100644
--- a/doc/reference/commands/traffic_cop.en.rst
+++ b/doc/reference/commands/traffic_cop.en.rst
@@ -15,6 +15,8 @@
specific language governing permissions and limitations
under the License.
+.. _traffic_cop:
+
===========
traffic_cop
===========
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a4fc1dfe/doc/reference/commands/traffic_manager.en.rst
----------------------------------------------------------------------
diff --git a/doc/reference/commands/traffic_manager.en.rst b/doc/reference/commands/traffic_manager.en.rst
index 09494ce..1267cf2 100644
--- a/doc/reference/commands/traffic_manager.en.rst
+++ b/doc/reference/commands/traffic_manager.en.rst
@@ -15,6 +15,8 @@
specific language governing permissions and limitations
under the License.
+.. _traffic_manager:
+
===============
traffic_manager
===============
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a4fc1dfe/doc/reference/commands/traffic_server.en.rst
----------------------------------------------------------------------
diff --git a/doc/reference/commands/traffic_server.en.rst b/doc/reference/commands/traffic_server.en.rst
index 2c8b586..75c11ea 100644
--- a/doc/reference/commands/traffic_server.en.rst
+++ b/doc/reference/commands/traffic_server.en.rst
@@ -15,6 +15,8 @@
specific language governing permissions and limitations
under the License.
+.. _traffic_server:
+
==============
traffic_server
==============