You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by ig...@apache.org on 2013/04/18 15:20:26 UTC
[6/7] git commit: add sdk docs.
add sdk docs.
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/80368908
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/80368908
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/80368908
Branch: refs/heads/sphinx-docs
Commit: 80368908985efcd29fc59ea81bb39cd83fbd61a3
Parents: 85ef722
Author: Igor Galić <i....@brainsware.org>
Authored: Thu Apr 18 15:18:51 2013 +0200
Committer: Igor Galić <i....@brainsware.org>
Committed: Thu Apr 18 15:18:51 2013 +0200
----------------------------------------------------------------------
doc/source/index.en.rst | 2 +-
doc/source/sdk/actions-guide.en.rst | 180 ++++++
.../sdk/actions-guide/hosts-lookup-api.en.rst | 28 +
doc/source/sdk/adding-statistics.en.rst | 72 +++
.../adding-statistics/coupled-statistics.en.rst | 122 ++++
.../viewing-statistics-using-traffic-line.en.rst | 33 ++
doc/source/sdk/continuations.en.rst | 135 +++++
.../how-to-activate-continuations.en.rst | 36 ++
.../continuations/writing-handler-functions.en.rst | 109 ++++
doc/source/sdk/getting-started.en.rst | 249 ++++++++
.../sdk/getting-started/a-simple-plugin.en.rst | 118 ++++
.../sdk/getting-started/naming-conventions.en.rst | 51 ++
...plugin-registration-and-version-checking.en.rst | 86 +++
doc/source/sdk/header-based-plugin-examples.en.rst | 68 +++
.../basic-authorization-plugin.en.rst | 43 ++
...-and-getting-a-handle-to-the-transaction.en.rst | 45 ++
.../setting-a-transaction-hook.en.rst | 56 ++
.../working-with-http-headers.en.rst | 98 ++++
.../blacklist-plugin.en.rst | 107 ++++
...ccessing-the-transaction-being-processed.en.rst | 61 ++
.../blacklist-plugin/setting-a-global-hook.en.rst | 37 ++
.../setting-up-a-transaction-hook.en.rst | 81 +++
.../working-with-http-header-functions.en.rst | 63 ++
.../sdk/how-to-create-trafficserver-plugins.en.rst | 227 ++++++++
.../roadmap-for-creating-plugins.en.rst | 90 +++
doc/source/sdk/http-headers.en.rst | 141 +++++
...uide-to-trafficserver-http-header-system.en.rst | 63 ++
.../duplicate-mime-fields-are-not-coalesced.en.rst | 30 +
...ways-belong-to-an-associated-mime-header.en.rst | 70 +++
.../release-marshal-buffer-handles.en.rst | 88 +++
doc/source/sdk/http-headers/http-headers.en.rst | 172 ++++++
doc/source/sdk/http-headers/marshal-buffers.en.rst | 56 ++
doc/source/sdk/http-headers/mime-headers.en.rst | 437 +++++++++++++++
doc/source/sdk/http-headers/urls.en.rst | 134 +++++
doc/source/sdk/http-hooks-and-transactions.en.rst | 83 +++
.../adding-hooks.en.rst | 149 +++++
.../http-alternate-selection.en.rst | 192 +++++++
.../http-sessions.en.rst | 52 ++
.../http-transactions.en.rst | 205 +++++++
.../initiate-http-connection.en.rst | 25 +
.../intercepting-http-transactions.en.rst | 30 +
doc/source/sdk/http-transformation-plugin.en.rst | 159 ++++++
.../append-transform-plugin.en.rst | 145 +++++
...mple-buffered-null-transformation-plugin.en.rst | 213 +++++++
.../sample-null-transformation-plugin.en.rst | 231 ++++++++
doc/source/sdk/index.en.rst | 63 ++
doc/source/sdk/io-guide.en.rst | 194 +++++++
doc/source/sdk/io-guide/guide-to-cache-api.en.rst | 69 +++
.../sdk/io-guide/guide-to-cache-api/errors.en.rst | 31 +
.../sdk/io-guide/guide-to-cache-api/example.en.rst | 76 +++
.../how-to-do-a-cache-remove.en.rst | 31 +
.../how-to-do-a-cache-write.en.rst | 34 ++
doc/source/sdk/io-guide/io-buffers.en.rst | 52 ++
doc/source/sdk/io-guide/net-vconnections.en.rst | 31 +
doc/source/sdk/io-guide/transformations.en.rst | 182 ++++++
doc/source/sdk/io-guide/vios.en.rst | 59 ++
doc/source/sdk/misc-interface-guide.en.rst | 60 ++
.../misc-interface-guide/memory-allocation.en.rst | 46 ++
.../misc-interface-guide/thread-functions.en.rst | 34 ++
.../sdk/misc-interface-guide/tsfopen-family.en.rst | 54 ++
doc/source/sdk/mutex-guide.en.rst | 411 ++++++++++++++
doc/source/sdk/new-protocol-plugins.en.rst | 359 ++++++++++++
doc/source/sdk/plugin-configurations.en.rst | 116 ++++
doc/source/sdk/plugin-management.en.rst | 28 +
.../guide-to-the-logging-api.en.rst | 103 ++++
...ng-trafficserver-settings-and-statistics.en.rst | 59 ++
doc/source/sdk/preface.en.rst | 49 ++
doc/source/sdk/preface/how-to-use-this-book.en.rst | 132 +++++
.../sdk/preface/typographical-conventions.en.rst | 36 ++
doc/source/sdk/remap-plugin.en.rst | 75 +++
.../sdk/remap-plugin/example-query-remap.en.rst | 152 +++++
doc/source/sdk/sample-source-code.en.rst | 309 ++++++++++
doc/source/sdk/troubleshooting-tips.en.rst | 57 ++
.../debugging-memory-leaks.en.rst | 32 +
.../unable-to-debug-tags.en.rst | 113 ++++
.../unable-to-load-plugins.en.rst | 36 ++
.../troubleshooting-tips/using-a-debugger.en.rst | 40 ++
77 files changed, 7994 insertions(+), 1 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/index.en.rst b/doc/source/index.en.rst
index f99cef6..4fd3efe 100644
--- a/doc/source/index.en.rst
+++ b/doc/source/index.en.rst
@@ -1,5 +1,5 @@
Apache Traffic Server Title: Documentation
-**************************************************************
+******************************************
.. Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/actions-guide.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/actions-guide.en.rst b/doc/source/sdk/actions-guide.en.rst
new file mode 100644
index 0000000..f73d12d
--- /dev/null
+++ b/doc/source/sdk/actions-guide.en.rst
@@ -0,0 +1,180 @@
+Actions Guide
+*************
+
+.. 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.
+
+.. toctree::
+ :maxdepth: 2
+
+ actions-guide/hosts-lookup-api.en
+
+
+Actions
+-------
+
+An **action** is a handle to an operation initiated by a plugin that has
+not yet completed. For example: when a plugin connects to a remote
+server, it uses the call ``TSNetConnect`` - which takes ``TSCont`` as an
+argument to call back when the connection is established.
+``TSNetConnect`` might not call the continuation back immediately and
+will return an ``TSAction`` structure that the caller can use to cancel
+the operation. Cancelling the operation does not necessarily mean that
+the operation will not occur; it simply means that the continuation
+passed into the operation will not be called back. In such an example,
+the connection might still occur if the action is cancelled; however,
+the continuation that initiated the connection would not be called back.
+
+In the preceding example, it is also possible that the connection will
+complete and call back the continuation before ``TSNetConnect`` returns.
+If that occurs, then ``TSNetConnect`` returns a special action that
+causes ``TSActionDone`` to return ``1``. This specifies that the
+operation has already completed, so it's pointless to try to cancel the
+operation. Also note that an action will never change from non-completed
+to completed. When the operation actually succeeds and the continuation
+is called back, the continuation must zero out its action pointer to
+indicate to itself that the operation succeeded.
+
+The asynchronous nature of all operations in Traffic Server necessitates
+actions. You should notice from the above discussion that once a call to
+a function like ``TSNetConnect`` is made by a continuation and that
+function returns a valid action (``TSActionDone`` returns ``0``), it is
+not safe for the continuation to do anything else except return from its
+handler function. It is not safe to modify or examine the continuation's
+data because the continuation may have already been destroyed.
+
+Below is an example of typical usage for an action:
+
+::
+
+ ::::c
+ #include <ts/ts.h>
+ static int
+ handler (TSCont contp, TSEvent event, void *edata)
+ {
+ if (event == TS_EVENT_IMMEDIATE) {
+ TSAction actionp = TSNetConnect (contp, 127.0.0.1, 9999);
+ if (!TSActionDone (actionp)) {
+ TSContDataSet (contp, actionp);
+ } else {
+ /* We've already been called back... */
+ return 0;
+ }
+ } else if (event == TS_EVENT_NET_CONNECT) {
+ /* Net connection succeeded */
+ TSContDataSet (contp, NULL);
+ return 0;
+ } else if (event == TS_EVENT_NET_CONNECT_FAILED) {
+ /* Net connection failed */
+ TSContDataSet (contp, NULL);
+ return 0;
+ }
+ return 0;
+ }
+
+ void
+ TSPluginInit (int argc, const char *argv[])
+ {
+ TSCont contp;
+
+ contp = TSContCreate (handler, TSMutexCreate ());
+
+ /* We don't want to call things out of TSPluginInit
+ directly since it's called before the rest of the
+ system is initialized. We'll simply schedule an event
+ on the continuation to occur as soon as the rest of
+ the system is started up. */
+ TSContSchedule (contp, 0);
+ }
+
+The example above shows a simple plugin that creates a continuation and
+then schedules it to be called immediately. When the plugin's handler
+function is called the first time, the event is ``TS_EVENT_IMMEDIATE``.
+The plugin then tries to open a net connection to port 9999 on
+``localhost`` (127.0.0.1). The IP description was left in cider notation
+to further clarify what is going on; also note that the above won't
+actually compile until the IP address is modified. The action returned
+from ``TSNetConnect`` is examined by the plugin. If the operation has
+not completed, then the plugin stores the action in its continuation.
+Otherwise, the plugin knows it has already been called back and there is
+no reason to store the action pointer.
+
+A final question might be, "why would a plugin want to cancel an
+action?" In the above example, a valid reason could be to place a limit
+on the length of time it takes to open a connection. The plugin could
+schedule itself to get called back in 30 seconds and then initiate the
+net connection. If the timeout expires first, then the plugin would
+cancel the action. The following sample code implements this:
+
+::
+
+ :::::c
+ #include <ts/ts.h>
+ static int
+ handler (TSCont contp, TSEvent event, void *edata)
+ {
+ switch (event) {
+ case (TS_EVENT_IMMEDIATE):
+ TSContSchedule (contp, 30000);
+ TSAction actionp = TSNetConnect(contp, 127.0.0.1, 9999);
+ if (!TSActionDone (actionp)) {
+ TSContDataSet (contp, actionp);
+ } else {
+ /* We've already been called back ... */
+ }
+ break;
+
+ case (TS_EVENT_TIMEOUT):
+ TSAction actionp = TSContDataGet (contp);
+ if (!TSActionDone(actionp)) {
+ TSActionCancel (actionp);
+ }
+ break;
+
+ case (TS_EVENT_NET_CONNECT):
+ /* Net connection succeeded */
+ TSContDataSet (contp, NULL);
+ break;
+
+ case (TS_EVENT_NET_CONNECT_FAILED):
+ /* Net connection failed */
+ TSContDataSet (contp, NULL);
+ break;
+
+ }
+ return 0;
+ }
+
+ void
+ TSPluginInit (int argc, const char *argv[])
+ {
+ TSCont contp;
+
+ contp = TSContCreate (handler, TSMutexCreate ());
+ /* We don't want to call things out of TSPluginInit
+ directly since it's called before the rest of the
+ system is initialized. We'll simply schedule an event
+ on the continuation to occur as soon as the rest of
+ the system is started up. */
+ TSContSchedule (contp, 0);
+ }
+
+The action functions are:
+
+- ```TSActionCancel`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a5d49a6addcc9dbdc7f339ee6b73ac0b6>`__
+- ```TSActionDone`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#abe189274ad59911f2a57d345d11bfecb>`__
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/actions-guide/hosts-lookup-api.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/actions-guide/hosts-lookup-api.en.rst b/doc/source/sdk/actions-guide/hosts-lookup-api.en.rst
new file mode 100644
index 0000000..66fc687
--- /dev/null
+++ b/doc/source/sdk/actions-guide/hosts-lookup-api.en.rst
@@ -0,0 +1,28 @@
+Hosts Lookup API
+****************
+
+.. 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.
+
+The hosts lookup enables plugins to ask Traffic Server to do a host
+lookup of a host name, much like a DNS lookup.
+
+The hosts lookup functions are as follows:
+
+- ```TSHostLookup`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#ab5bf6eea0ed883e5dc69253965935d12>`__
+- ```TSHostLookupResultAddrGet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#aecac0767192746af1867f528e01d167b>`__
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/adding-statistics.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/adding-statistics.en.rst b/doc/source/sdk/adding-statistics.en.rst
new file mode 100644
index 0000000..95ce041
--- /dev/null
+++ b/doc/source/sdk/adding-statistics.en.rst
@@ -0,0 +1,72 @@
+Adding Statistics
+*****************
+
+.. 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 describes how to add statistics to your plugins. Statistics
+can be coupled or uncoupled; **coupled** statistics are quantities that
+are related and must therefore be updated together. The Traffic Server
+API statistics functions add your plugin's statistics to the Traffic
+Server statistics system. You can view your plugin statistics as you
+would any other Traffic Server statistic, using Traffic Line (Traffic
+Server's command line interface). This chapter contains the following
+topics:
+
+.. toctree::
+ :maxdepth: 2
+
+ adding-statistics/coupled-statistics.en
+ adding-statistics/viewing-statistics-using-traffic-line.en
+
+
+Uncoupled Statistics
+--------------------
+
+A statistic is an object of type ``TSStat``. The value of the statistic
+is of type ``TSStatType``. The possible ``TSStatTypes`` are:
+
+- ``TSSTAT_TYPE_INT64``
+
+- ``TSSTAT_TYPE_FLOAT``
+
+There is *no* ``TSSTAT_TYPE_INT32``.
+
+To add uncoupled statistics, follow the steps below:
+
+1. Declare your statistic as a global variable in your plugin. For
+ example:
+
+ ::
+
+ ::::c
+ static TSStat my_statistic;
+
+2. In ``TSPluginInit``, create new statistics using ``TSStatCreate``.
+ When you create a new statistic, you need to give it an "external"
+ name that the Traffic Server command line interface (Traffic Line)
+ uses to access the statistic. For example:
+
+ ::
+
+ ::::c
+ my_statistic = TSStatCreate ("my.statistic", TSSTAT_TYPE_INT64);
+
+3. Modify (increment, decrement, or other modification) your statistic
+ in plugin functions.
+
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/adding-statistics/coupled-statistics.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/adding-statistics/coupled-statistics.en.rst b/doc/source/sdk/adding-statistics/coupled-statistics.en.rst
new file mode 100644
index 0000000..01e1895
--- /dev/null
+++ b/doc/source/sdk/adding-statistics/coupled-statistics.en.rst
@@ -0,0 +1,122 @@
+Coupled Statistics
+******************
+
+.. 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.
+
+Use coupled statistics for quantities that are related and therefore
+must be updated jointly.
+
+As a very simple example, suppose you have three statistics: ``sum``,
+``part_1``, and ``part_2``. They must always preserve the relationship
+that ``sum = part_1 + part_2``. If you update ``part_1`` without
+updating ``sum`` at the same time, then the equation becomes untrue.
+Therefore, the statistics are said to be *coupled*.
+
+The mechanism for updating coupled statistics jointly is to create local
+copies of global coupled statistics in the routines that modifiy them.
+When each local copy is updated appropriately, do a global update using
+``TSStatsCoupledUpdate``. To specify which statistics are related to one
+another, establish a coupled statistic category and make sure that each
+coupled statistic belongs to the appropriate category. When it is time
+to do the global update, specify the category to be updated.
+
+.. figure:: /images/docbook/note.png
+ :alt: [Note]
+
+ [Note]
+**Note**
+
+The local statistic copy must have a duplicate set of statistics as that
+of the master copy. Local statistics must also be added to the local
+statistic category in the same order as their master copy counterparts
+were originally added.
+
+Below are the steps you need to follow, along with a code example taken
+from the ``redirect-1.c`` sample plugin.
+
+To add coupled statistics:
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. Declare the global category for your coupled statistics as a global
+ ``TSCoupledStat`` variable in your plugin.
+
+2. Declare your coupled statistics as global ``TSStat`` variables in
+ your plugin.
+
+3. In ``TSPluginInit``, create a new global coupled category using
+ ``TSStatCoupledGlobalCategoryCreate``.
+
+4. In ``TSPluginInit``, create new global coupled statistics using
+ ``TSStatCoupledGlobalAdd``. When you create a new statistic, you need
+ to give it an "external" name that the Traffic Server command line
+ interface (Traffic Line) uses to access the statistic.
+
+5. In any routine wherein you want to modify (increment, decrement, or
+ other modification) your coupled statistics, declare local copies of
+ the coupled category and coupled statistics.
+
+6. Create local copies using ``TSStatCoupledLocalCopyCreate`` and
+ ``TSStatCoupledLocalAdd``.
+
+7. Modify the local copies of your statistics. Then call
+ ``TSStatsCoupledUpdate`` to update the global copies jointly.
+
+8. When you are finished, you must destroy all of the local copies in
+ the category via ``TSStatCoupledLocalCopyDestroy``.
+
+Example Using the redirect-1.c Sample Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+ :::c
+ static TSCoupledStat request_outcomes;
+
+ static TSStat requests_all;
+ static TSStat requests_redirects;
+ static TSStat requests_unchanged;
+
+ request_outcomes = TSStatCoupledGlobalCategoryCreate ("request_outcomes");
+
+ requests_all = TSStatCoupledGlobalAdd (request_outcomes, "requests.all", TSSTAT_TYPE_FLOAT);
+ requests_redirects = TSStatCoupledGlobalAdd (request_outcomes, "requests.redirects",
+ TSSTAT_TYPE_INT64);
+ requests_unchanged = TSStatCoupledGlobalAdd (request_outcomes, "requests.unchanged",
+ TSSTAT_TYPE_INT64);
+
+ TSCoupledStat local_request_outcomes;
+ TSStat local_requests_all;
+ TSStat local_requests_redirects;
+ TSStat local_requests_unchanged;
+
+ local_request_outcomes = TSStatCoupledLocalCopyCreate("local_request_outcomes",
+ request_outcomes);
+ local_requests_all = TSStatCoupledLocalAdd(local_request_outcomes, "requests.all.local",
+ TSSTAT_TYPE_FLOAT);
+ local_requests_redirects = TSStatCoupledLocalAdd(local_request_outcomes,
+ "requests.redirects.local", TSSTAT_TYPE_INT64);
+ local_requests_unchanged = TSStatCoupledLocalAdd(local_request_outcomes,
+ "requests.unchanged.local", TSSTAT_TYPE_INT64);
+
+ TSStatFloatAddTo( local_requests_all, 1.0 ) ;
+ ...
+ TSStatIncrement (local_requests_unchanged);
+ TSStatsCoupledUpdate(local_request_outcomes);
+
+ TSStatCoupledLocalCopyDestroy(local_request_outcomes);
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/adding-statistics/viewing-statistics-using-traffic-line.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/adding-statistics/viewing-statistics-using-traffic-line.en.rst b/doc/source/sdk/adding-statistics/viewing-statistics-using-traffic-line.en.rst
new file mode 100644
index 0000000..895c0c1
--- /dev/null
+++ b/doc/source/sdk/adding-statistics/viewing-statistics-using-traffic-line.en.rst
@@ -0,0 +1,33 @@
+Viewing Statistics Using Traffic Line
+*************************************
+
+.. 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.
+
+.. XXX: This documentation seeems to be dupplicated from the admin docs.
+
+To view statistics for your plugin, follow the steps below:
+
+1. Make sure you know the name of your statistic (i.e., the name used in
+ the ``TSStatCoupledGlobalAdd``, ``TSStatCreate``, or
+ ``TSStatCoupledGlobalCategoryCreate`` call).
+
+2. In your ``<Traffic Server>/bin`` directory, enter the following:
+
+ ::::text ./traffic\_line -r the\_name
+
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/continuations.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/continuations.en.rst b/doc/source/sdk/continuations.en.rst
new file mode 100644
index 0000000..df93565
--- /dev/null
+++ b/doc/source/sdk/continuations.en.rst
@@ -0,0 +1,135 @@
+Continuations
+*************
+
+.. 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.
+
+.. toctree::
+ :maxdepth: 2
+
+ continuations/how-to-activate-continuations.en
+ continuations/writing-handler-functions.en
+
+The continuation interface is Traffic Server's basic callback mechanism.
+**Continuations** are instances of the opaque data type ``TSCont``. In
+its basic form, a continuation represents a handler function and a
+mutex.
+
+This chapter covers the following topics:
+
+- `Mutexes and Data <MutexesData>`__
+
+- `How to Activate Continuations <ActivateContinuations.html>`__
+
+- `Writing Handler Functions <WritingHandlerFunctions.html>`__
+
+Mutexes and Data
+----------------
+
+A continuation must be created with a mutex if your continuation does
+one of the following:
+
+- is registered globally (``TSHttpHookAdd`` or ``TSHttpSsnHookAdd``) to
+ an HTTP hook and uses ``TSContDataSet/Get``
+
+- is registered locally (``TSHttpTxnHookAdd``), but for multiple
+ transactions uses ``TSContDataSet/Get``
+
+- uses ``TSCacheXXX``, ``TSNetXXX``, ``TSHostLookup``, or
+ ``TSContSchedule`` APIs
+
+Before being activated, a caller must grab the continuation's mutex.
+This requirement makes it possible for a continuation's handler function
+to safely access its data and to prevent multiple callers from running
+it at the same time (see the `sample Protocol
+plugin <../new-protocol-plugins#AboutSampleProtocol>`__ for usage). The
+data protected by the mutex is any global or continuation data
+associated to the continuation by ``TSContDataSet``. This does not
+include the local data created by the continuation handler function. A
+typical example of continuations created with associated data structures
+and mutexes is the transaction state machine created in the sample
+Protocol plugin (see `One Way to Implement a Transaction State
+Machine <../new-protocol-plugins#OneWayImplementaTransactionStateMachine>`__).
+
+A reentrant call occurs when the continuation passed as an argument to
+the API can be called in the same stack trace as the function calling
+the API. For example, if you call ``TSCacheRead`` (``contp, mykey``), it
+is possible that ``contp``'s handler will be called directly and then
+``TSCacheRead`` returns.
+
+Caveats that could cause issues include the following:
+
+- a continuation has data associated with it (``TSContDataGet``).
+
+| \*
+| the reentrant call passes itself as a continuation to the reentrant
+API. In this case, the continuation should not try to access its data
+after calling the reentrant API. The reason for this is that data may be
+modified by the section of code in the continuation's handler that
+handles the event sent by the API. It is recommended that you always
+return after a reentrant call to avoid accessing something that has been
+deallocated.
+
+Below is an example, followed by an explanation.
+
+::
+
+ ::::c
+ continuation_handler (TSCont contp, TSEvent event, void *edata) {
+ switch (event) {
+ case event1:
+ TSReentrantCall (contp);
+ /* Return right away after this call */
+ break;
+ case event2:
+ TSContDestroy (contp);
+ break;
+ }
+ }
+
+The above example first assumes that the continuation is called back
+with ``event1``; it then does the first reentrant call that schedules
+the continuation to receive ``event2``. Because the call is reentrant,
+the processor calls back the continuation right away with ``event2`` and
+the continuation is destroyed. If you try to access the continuation or
+one of its members after the reentrant call, then you might access
+something that has been deallocated. To avoid accessing something that
+has been deallocated, never access the continuation or any of its
+members after a reentrant call - just exit the handler.
+
+**Note:** Most HTTP transaction plugin continuations do not need
+non-null mutexes because they're called within the processing of an HTTP
+transaction, and therefore have the transaction's mutex.
+
+It is also possible to specify a continuation's mutex as ``NULL``. This
+should be done only when registering a continuation to a global hook, by
+a call to ``TSHttpHookAdd``. In this case, the continuation can be
+called simultaneously by different instances of HTTP SM running on
+different threads. Having a mutex here would slow and/or hinder Traffic
+Server performance, since all the threads will try to lock the same
+mutex. The drawback of not having a mutex is that such a continuation
+cannot have data associated with it (i.e., ``TSContDataGet/Set`` cannot
+be used).
+
+When using a ``NULL`` mutex it is dangerous to access the continuation's
+data, but usually continuations with ``NULL`` mutexes have no data
+associated with them anyway. An example of such a continuation is one
+that gets called back every time an HTTP request is read, and then
+determines from the request alone if the request should go through or be
+rejected. An HTTP transaction gives its continuation data to the
+``contp``.
+
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/80368908/doc/source/sdk/continuations/how-to-activate-continuations.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/continuations/how-to-activate-continuations.en.rst b/doc/source/sdk/continuations/how-to-activate-continuations.en.rst
new file mode 100644
index 0000000..1dd23c2
--- /dev/null
+++ b/doc/source/sdk/continuations/how-to-activate-continuations.en.rst
@@ -0,0 +1,36 @@
+How to Activate Continuations
+*****************************
+
+.. 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.
+
+Continuations are activated when they receive an event or by
+``TSContSchedule`` (which schedules a continuation to receive an event).
+Continuations might receive an event because:
+
+- Your plugin calls ``TSContCall``
+
+- The Traffic Server HTTP state machine sends an event corresponding to
+ a particular HTTP hook
+
+- A Traffic Server IO processor (such as a cache processor or net
+ processor) is letting a continuation know there is data (cache or
+ network) available to read or write. These callbacks are a result of
+ using functions such ``TSVConnRead``/``Write`` or
+ ``TSCacheRead``/``Write``
+
+