trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jpe...@apache.org
Subject [15/26] Separate the Admin and SDK guides.
Date Sun, 02 Jun 2013 05:02:12 GMT
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/index.en.rst b/doc/sdk/index.en.rst
new file mode 100644
index 0000000..3b60e69
--- /dev/null
+++ b/doc/sdk/index.en.rst
@@ -0,0 +1,71 @@
+Apache Traffic Server Programmers 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.
+
+*In progress*
+
+**Abstract**
+
+The *Traffic Server Software Developers Kit* shows you how to create
+plugins using the Traffic Server SDK.
+
+--------------
+
+This documentation is a work in progress. It was originally written for
+a previous, commercially-available version of Traffic Server that
+supported different operating systems and more functions than the
+current version. As a result, some of the sections may refer to
+functionality that no longer exists.
+
+If you find any such issues, you may want to submit a `bug or a
+patch <https://issues.apache.org/jira/secure/CreateIssue!default.jspa?pid=12310963>`__.
+Or find out how to `find bugs <>`__, `create useful bug reports <>`__ or
+`patches <>`__.
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+    preface.en
+    getting-started.en
+    how-to-create-trafficserver-plugins.en
+    remap-plugin.en
+    header-based-plugin-examples.en
+    http-transformation-plugin.en
+    new-protocol-plugins.en
+    http-hooks-and-transactions.en
+    misc-interface-guide.en
+    http-headers.en
+    mutex-guide.en
+    continuations.en
+    plugin-configurations.en
+    actions-guide.en
+    io-guide.en
+    plugin-management.en
+    adding-statistics.en
+    sample-source-code.en
+    troubleshooting-tips.en
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/io-guide.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide.en.rst b/doc/sdk/io-guide.en.rst
new file mode 100644
index 0000000..40bf54d
--- /dev/null
+++ b/doc/sdk/io-guide.en.rst
@@ -0,0 +1,194 @@
+IO 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.
+
+This chapter contains the following sections:
+
+.. toctree::
+   :maxdepth: 2
+
+   io-guide/net-vconnections.en
+   io-guide/transformations.en
+   io-guide/vios.en
+   io-guide/io-buffers.en
+   io-guide/guide-to-cache-api.en
+
+
+Vconnections
+------------
+
+Vconnections: a User's Perspective
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To use a vconnection, a user must first get a handle to one. This is
+usually accomplished by having it handed to the user; the user may also
+simply issue a call that creates a vconnection (such as
+``TSNetConnect)``. In the case of transform plugins, the plugin creates
+a transformation vconnection viav ``TSTransformCreate`` and then
+accesses the output vconnection using ``TSTransformOutputVConnGet``.
+
+After getting a handle to a vconnection, the user can then issue a read
+or write call. It's important to note that not all vconnections support
+both reading and writing - as of yet, there has not been a need to query
+a vconnection about whether it can perform a read or write operation.
+That ability should be obvious from context.
+
+To issue a read or write operation, a user calls ``TSVConnRead`` or
+``TSVConnWrite``. These two operations both return ``VIO (TSVIO)``. The
+VIO describes the operation being performed and how much progress has
+been made. Transform plugins initiate output to the downstream
+vconnection by calling ``TSVConnWrite``.
+
+A vconnection read or write operation is different from a normal UNIX
+``read(2)`` or ``write(2)`` operation. Specifically, the vconnection
+operation can specify more data to be read or written than exists in the
+buffer handed to the operation. For example, it's typical to issue a
+read for ``INT64_MAX`` (9 quintillion) bytes from a network vconnection
+in order to read all the data from the network connection until the end
+of stream is reached. This contrasts with the usual UNIX fashion of
+issuing repeated calls to ``read(2)`` until one of the calls finally
+returns ``0`` to indicate the end of stream was reached (indeed, the
+underlying implementation of vconnections on UNIX still does issue those
+calls to ``read(2)``, but the interface does not expose that detail).
+
+At most, a given vconnection can have one read operation and one write
+operation being performed on it. This is restricted both by design and
+common sense: if two write operations were performed on a single
+vconnection, then the user would not be able to specify which should
+occur first and the output would occur in an intermingled fashion. Note
+that both a read operation and a write operation can happen on a single
+vconnection at the same time; the restriction is for more than one
+operation of the same type.
+
+One obvious issue is that the buffer passed to ``TSVConnRead`` and
+``TSVConnWrite`` won't be large enough - there is no reasonable way to
+make a buffer that can hold ``INT64_MAX`` (9 quintillion) bytes! The
+secret is that vconnections engage in a protocol whereby they signal to
+the user (via the continuation passed to ``TSVConnRead`` and
+``TSVConnWrite``) that they have emptied the buffers passed to them and
+are ready for more data. When this occurs, it is up to the user to add
+more data to the buffers (or wait for more data to be added) and then
+wake up the vconnection by calling ``TSVIOReenable`` on the VIO
+describing the operation. ``TSVIOReenable`` specifies that the buffer
+for the operation has been modified and that the vconnection should
+reexamine it to see if it can make further progress.
+
+The null transform plugin provides an example of how this is done. Below
+is a prototype for ``TSVConnWrite``:
+
+::
+
+     ::::c
+     TSVIO TSVConnWrite (TSVConn connp, TSCont contp, TSIOBufferReader readerp, int nbytes)
+
+The ``connp`` is the vconnection the user is writing to and ``contp`` is
+the "user" - i.e., the continuation that ``connp`` calls back when it
+has emptied its buffer and is ready for more data.
+
+The call made in the null transform plugin is:
+
+::
+
+      :::c
+      TSVConnWrite (output_conn, contp, data->output_reader, TSVIONBytesGet (input_vio));
+
+In the example above, ``contp`` is the transformation vconnection that
+is writing to the output vconnection. The number of bytes to be written
+is obtained from ``input_vio`` by ``TSVIONBytesGet``.
+
+When a vconnection calls back its user to indicate that it wants more
+data (or when some other condition has occurred), it issues a call to
+``TSContCall``. It passes the ``TSVIO`` describing the operation as the
+data parameter, and one of the values below as the event parameter.
+
+``TS_EVENT_ERROR``
+    Indicates an error has occurred on the vconnection. This will happen
+    for network IO if the underlying ``read(2)`` or ``write(2)`` call
+    returns an error.
+
+``TS_EVENT_VCONN_READ_READY``
+    The vconnection has placed data in the buffer passed to an
+    ``TSVConnRead`` operation and it would like to do more IO, but the
+    buffer is now full. When the user consumes the data from the buffer,
+    this should re-enable the VIO so it indicates to the vconnection
+    that the buffer has been modified.
+
+``TS_EVENT_VCONN_WRITE_READY``
+    The vconnection has removed data from the buffer passed to an
+    ``TSVConnWrite`` operation and it would like to do more IO, but the
+    buffer does not have enough data in it. When placing more data in
+    the buffer, the user should re-enable the VIO so it indicates to the
+    vconnection that the buffer has been modified.
+
+``TS_EVENT_VCONN_READ_COMPLETE``
+    The vconnection has read all the bytes specified by an
+    ``TSVConnRead`` operation. The vconnection can now be used to
+    initiate a new IO operation.
+
+``TS_EVENT_VCONN_WRITE_COMPLETE``
+    The vconnection has written all the bytes specified by an
+    ``TSVConnWrite`` operation and can now be used to initiate a new IO
+    operation.
+
+``TS_EVENT_VCONN_EOS``
+    An attempt was made to read past the end of the stream of bytes
+    during the handling of an ``TSVConnRead`` operation. This event
+    occurs when the number of bytes available for reading from a
+    vconnection is less than the number of bytes the user specifies
+    should be read from the vconnection in a call to ``TSVConnRead``. A
+    common case where this occurs is when the user specifies that
+    ``INT64_MAX`` bytes are to be read from a network connection.
+
+For example: the null transform plugin's transformation receives
+``TS_EVENT_VCONN_WRITE_READY`` and ``TS_EVENT_VCONN_WRITE_COMPLETE``
+events from the downstream vconnection as a result of the call to
+``TSVConnWrite``.
+
+After using a vconnection, the user must call ``TSVConnClose`` or
+``TSVConnAbort``. While both calls indicate that the vconnection can
+destroy itself, ``TSVConnAbort`` should be used when the connection is
+being closed abnormally. After a call to ``TSVConnClose`` or
+``TSVConnAbort``, the user will not be called back by the vconnection
+again.
+
+Sometimes it's desirable to simply close down the write portion of a
+connection while keeping the read portion open. This can be accomplished
+via the ``TSVConnShutdown`` function, which shuts down either the read
+or write portion of a vconnection. *Shutdown* means that the vconnection
+will no longer call back the user with events for the portion of the
+connection that was shut down. For example: if the user shuts down the
+write portion of a connection, then the ``TS_EVENT_VCONN_WRITE_READY``
+or ``TS_EVENT_VCONN_WRITE_COMPLETE`` events will not be produced. In the
+null transform plugin, the write operation is shut down with a call to
+``TSVConnShutdown``. To learn how vconnections are used in
+transformation plugins, see `Writing Content Transform
+Plugins <../http-transformation-plugin#WritingContentTransformPlugins>`__.
+
+The vconnection functions are listed below:
+
+-  ```TSVConnAbort`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a08444a9b2fee637672e177ede78b6218>`__
+-  ```TSVConnClose`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a69344c2c6e57ece0990a5cee73b75215>`__
+-  ```TSVConnClosedGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a441d74cd77bf5d5564048682ca83b6ec>`__
+-  ```TSVConnRead`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a29674799a8deffdde3d6ae3231aba1dc>`__
+-  ```TSVConnReadVIOGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#aa6f8788f062737f211c788ad5fcd2813>`__
+-  ```TSVConnShutdown`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a5935b6c762b65fe87057adf94b1b00b4>`__
+-  ```TSVConnWrite`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#acea65496d1fcaf01924b0210f3129e6b>`__
+-  ```TSVConnWriteVIOGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#ae9a38dbd4866c59131a1f3b806a18aab>`__
+
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/io-guide/guide-to-cache-api.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/guide-to-cache-api.en.rst b/doc/sdk/io-guide/guide-to-cache-api.en.rst
new file mode 100644
index 0000000..ea63967
--- /dev/null
+++ b/doc/sdk/io-guide/guide-to-cache-api.en.rst
@@ -0,0 +1,69 @@
+Guide to the Cache 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.
+
+.. toctree::
+   :maxdepth: 2
+
+   guide-to-cache-api/how-to-do-a-cache-write.en
+   guide-to-cache-api/how-to-do-a-cache-remove.en
+   guide-to-cache-api/errors.en
+   guide-to-cache-api/example.en
+
+
+The cache API enables plugins to read, write, and remove objects in the
+Traffic Server cache. All cache APIs are keyed by an object called an
+``TSCacheKey``; cache keys are created via ``TSCacheKeyCreate``; keys
+are destroyed via ``TSCacheKeyDestroy``. Use ``TSCacheKeyDigestSet`` to
+set the hash of the cache key.
+
+Note that the cache APIs differentiate between HTTP data and plugin
+data. The cache APIs do not allow you to write HTTP docs in the cache;
+you can only write plugin-specific data (a specific type of data that
+differs from the HTTP type).
+
+**Example:**
+
+::
+
+            :::c
+        const unsigned char *key_name = "example key name";
+
+        TSCacheKey key;
+        TSCacheKeyCreate (&key);
+        TSCacheKeyDigestSet (key, (unsigned char *) key_name , strlen(key_name));
+        TSCacheKeyDestroy (key);
+
+How to Do a Cache Read
+~~~~~~~~~~~~~~~~~~~~~~
+
+``TSCacheRead`` does not really read - it is used for lookups (see the
+sample Protocol plugin). Possible callback events include:
+
+-  ``TS_EVENT_CACHE_OPEN_READ`` - indicates the lookup was successful.
+   The data passed back along with this event is a cache vconnection
+   that can be used to initiate a read on this keyed data.
+
+-  ``TS_EVENT_CACHE_OPEN_READ_FAILED`` - indicates the lookup was
+   unsuccessful. Reasons for this event could be that another
+   continuation is writing to that cache location, or the cache key
+   doesn't refer to a cached resource. Data payload for this event
+   indicates the possible reason the read failed (``TSCacheError``).
+
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/io-guide/guide-to-cache-api/errors.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/guide-to-cache-api/errors.en.rst b/doc/sdk/io-guide/guide-to-cache-api/errors.en.rst
new file mode 100644
index 0000000..f45866b
--- /dev/null
+++ b/doc/sdk/io-guide/guide-to-cache-api/errors.en.rst
@@ -0,0 +1,31 @@
+Errors
+******
+
+.. 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.
+
+Errors pertaining to the failure of various cache operations are
+indicated by ``TSCacheError`` (enumeration). They are as follows:
+
+-  ``TS_CACHE_ERROR_NO_DOC`` - the key does not match a cached resource
+
+-  ``TS_CACHE_ERROR_DOC_BUSY`` - e.g, another continuation could be
+   writing to the cache location
+
+-  ``TS_CACHE_ERROR_NOT_READY`` - the cache is not ready
+
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/io-guide/guide-to-cache-api/example.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/guide-to-cache-api/example.en.rst b/doc/sdk/io-guide/guide-to-cache-api/example.en.rst
new file mode 100644
index 0000000..c00dbea
--- /dev/null
+++ b/doc/sdk/io-guide/guide-to-cache-api/example.en.rst
@@ -0,0 +1,76 @@
+Example
+*******
+
+.. 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.
+
+In the example below, suppose there is a cache hit and the cache returns
+a vconnection that enables you to read the document from cache. To do
+this, you need to prepare a buffer (``cache_bufp``) to hold the
+document; meanwhile, use ``TSVConnCachedObjectSizeGet`` to find out the
+actual size of the document (``content_length``). Then, issue
+``TSVConnRead`` to read the document with the total data length required
+as ``content_length``. Assume the following data:
+
+::
+
+            ::::c
+        TSIOBuffer       cache_bufp = TSIOBufferCreate ();
+        TSIOBufferReader cache_readerp = TSIOBufferReaderAlloc (out_bufp);
+        TSVConn          cache_vconnp = NULL;
+        TSVIO            cache_vio = NULL;
+        int               content_length = 0;
+
+In the ``TS_CACHE_OPEN_READ`` handler:
+
+::
+
+        ::::c
+    cache_vconnp = (TSVConn) data;
+        TSVConnCachedObjectSizeGet (cache_vconnp, &content_length);
+        cache_vio = TSVConnRead (cache_vconn, contp, cache_bufp, content_length);
+
+In the ``TS_EVENT_VCONN_READ_READY`` handler:
+
+::
+
+        ::::c
+    (usual VCONN_READ_READY handler logic)
+    int nbytes = TSVIONBytesGet (cache_vio);
+    int ntodo  = TSVIONTodoGet (cache_vio);
+    int ndone  = TSVIONDoneGet (cache_vio);
+    (consume data in cache_bufp)
+    TSVIOReenable (cache_vio);
+
+Do not try to get continuations or VIOs from ``TSVConn`` objects for
+cache vconnections. Also note that the following APIs can only be used
+on transformation vconnections and must not be used on cache
+vconnections or net vconnections:
+
+-  ``TSVConnWriteVIOGet``
+
+-  ``TSVConnReadVIOGet``
+
+-  ``TSVConnClosedGet``
+
+APIs such as ``TSVConnRead``, ``TSVConnWrite``, ``TSVConnClose``,
+``TSVConnAbort``, and ``TSVConnShutdown`` can be used on any kind of
+vconnections.
+
+When you are finished:
+
+``TSCacheKeyDestroy (key);``

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.rst b/doc/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.rst
new file mode 100644
index 0000000..0edadf6
--- /dev/null
+++ b/doc/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.rst
@@ -0,0 +1,31 @@
+How to Do a Cache Remove
+************************
+
+.. 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 ``TSCacheRemove`` to remove items from the cache. Possible callback
+events include:
+
+-  ``TS_EVENT_CACHE_REMOVE`` - the item was removed. There is no data
+   payload for this event.
+
+-  ``TS_EVENT_CACHE_REMOVE_FAILED`` - indicates the cache was unable to
+   remove the item identified by the cache key. ``TSCacheError`` data
+   indicates why the remove failed.
+
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.rst b/doc/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.rst
new file mode 100644
index 0000000..1a9eacc
--- /dev/null
+++ b/doc/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.rst
@@ -0,0 +1,34 @@
+How to Do a Cache Write
+***********************
+
+.. 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 ``TSCacheWrite`` to write to a cache (see the `sample Protocol
+plugin <../../new-protocol-plugins#AboutSampleProtocol>`__). Possible
+callback events include:
+
+-  ``TS_EVENT_CACHE_WRITE_READ`` - indicates the lookup was successful.
+   The data passed back along with this event is a cache vconnection
+   that can be used to initiate a cache write.
+
+-  ``TS_EVENT_CACHE_OPEN_WRITE_FAILED`` - event returned when another
+   continuation is currently writing to this location in the cache. Data
+   payload for this event indicates the possible reason for the write
+   failing (``TSCacheError``).
+
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/io-guide/io-buffers.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/io-buffers.en.rst b/doc/sdk/io-guide/io-buffers.en.rst
new file mode 100644
index 0000000..8c4cc40
--- /dev/null
+++ b/doc/sdk/io-guide/io-buffers.en.rst
@@ -0,0 +1,52 @@
+IO Buffers
+**********
+
+.. 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 IO buffer data structure is the building block of the vconnection
+abstraction. An **IO buffer** (``TSIOBuffer``) is composed of a list of
+buffer blocks that point to buffer data. Both the buffer block
+(``TSIOBufferBlock``) and buffer data (``TSIOBufferData``) data
+structures are reference-counted, so they can reside in multiple buffers
+at the same time. This makes it extremely efficient to copy data from
+one IO buffer to another via ``TSIOBufferCopy``, since Traffic Server
+must only copy pointers and adjust reference counts appropriately (and
+doesn't actually copy any data).
+
+The IO buffer abstraction provides for a single writer and multiple
+readers. In order for the readers to have no knowledge of each other,
+they manipulate IO buffers through the ``TSIOBufferReader`` data
+structure. Since only a single writer is allowed, there is no
+corresponding ``TSIOBufferWriter`` data structure. The writer simply
+modifies the IO buffer directly. To see an example that illustrates how
+to use IOBuffers, refer to the sample code in the description of
+```TSIOBufferBlockReadStart`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a367203e6e2cf4349e019952782deb96c>`__.
+
+Additional information about IO buffer functions:
+
+-  The ``TSIOBufferReader`` data structure tracks how much data in
+   ``TSIOBuffer`` has been read. It has an offset number of bytes that
+   is the current start point of a particular buffer reader (for every
+   read operation on an ``TSIOBuffer``, you must allocate an
+   ``TSIOBufferReader``).
+
+-  Bytes that have already been read may not necessarily be freed within
+   the ``TSIOBuffer``. To consume bytes that have been read, you must
+   call ``TSIOBufferConsume``.
+
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/io-guide/net-vconnections.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/net-vconnections.en.rst b/doc/sdk/io-guide/net-vconnections.en.rst
new file mode 100644
index 0000000..1dfe8a2
--- /dev/null
+++ b/doc/sdk/io-guide/net-vconnections.en.rst
@@ -0,0 +1,31 @@
+Net Vconnections
+****************
+
+.. 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.
+
+A **network** **vconnection** (or*\* netvconnection*\ \*) is a wrapper
+around a TCP socket that enables the socket to work within the Traffic
+Server vconnection framework. See
+`vconnections <index.en.html#Vconnections>`__ for more information about
+the Traffic Server abstraction for doing asynchronous IO.
+
+The netvconnection functions are listed below:
+
+-  [dox 'TSNetAccept'] in [dox "TSNetAccept" :src\_file]
+-  [dox %TSNetConnect%] in [dox :src\_file]
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/io-guide/transformations.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/transformations.en.rst b/doc/sdk/io-guide/transformations.en.rst
new file mode 100644
index 0000000..667e611
--- /dev/null
+++ b/doc/sdk/io-guide/transformations.en.rst
@@ -0,0 +1,182 @@
+Transformations
+***************
+
+.. 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 Vconnection Implementor's View
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A VConnection implementor writes only transformations. All other
+VConnections (net VConnections and cache VConnections) are implemented
+in iocore. As mentioned earlier, a given vconnection can have a maximum
+of one read operation and one write operation being performed on it. The
+vconnection user gets information about the operation being performed by
+examining the VIO returned by a call to ``TSVConnRead`` or
+``TSVConnWrite``. The implementor, in turn, gets a handle on the VIO
+operation by examining the VIO returned by ``TSVConnReadVIOGet`` or
+``TSVConnWriteVIOGet`` (recall that every vconnection created through
+the Traffic Server API has an associated read VIO and write VIO, even if
+it only supports reading or writing).
+
+For example, the null transform plugin's transformation examines the
+input VIO by calling:
+
+::
+
+     :::c
+     input_vio = TSVConnWriteVIOGet (contp);
+
+where ``contp`` is the transformation.
+
+A vconnection is a continuation. This means it has a handler function
+that is run when an event is sent to it, or more accurately, when an
+event that was sent to it is received. It is the handler function's job
+to examine the event, the current state of its read VIO and write VIO,
+and any other internal state the vconnection might have and potentially
+make some progress on the IO operations.
+
+It is common for the handler function for all vconnections to look
+similar. Their basic form looks something like the code fragment below:
+
+::
+
+        ::::c
+    int
+    vconnection_handler (TSCont contp, TSEvent event, void *edata)
+    {
+    if (TSVConnClosedGet (contp)) {
+            /* Destroy any vconnection specific data here. */
+            TSContDestroy (contp);
+            return 0;
+       } else {
+            /* Handle the incoming event */
+       }
+    }
+
+This code fragment basically shows that many vconnections simply want to
+destroy themselves when they are closed. However, the situation might
+also require the vconnection to do some cleanup processing - which is
+why ``TSVConnClose`` does not simply just destroy the vconnection.
+
+Vconnections are state machines that are animated by the events they
+receive. An event is sent to the vconnection whenever an
+``TSVConnRead``, ``TSVConnWrite``, ``TSVConnClose``,
+``TSVConnShutdown``, or ``TSVIOReenable`` call is performed.
+``TSVIOReenable`` indirectly references the vconnection through a
+back-pointer in the VIO structure to the vconnection. The vconnection
+itself only knows which call was performed by examining its state and
+the state of its VIOs. For example, when ``TSVConnClose`` is called, the
+vconnection is sent an immediate event (``TS_EVENT_IMMEDIATE``). For
+every event the vconnection receives, it needs to check its closed flag
+to see if it has been closed. Similarly, when ``TSVIOReenable`` is
+called, the vconnection is sent an immediate event. For every event the
+vconnection receives, it must check its VIOs to see if the buffers have
+been modified to a state in which it can continue processing one of its
+operations.
+
+Finally, a vconnection is likely the user of other vconnections. It also
+receives events as the user of these other vconnections. When it
+receives such an event, like ``TS_EVENT_VCONN_WRITE_READY``, it might
+just enable another vconnection that's writing into the buffer used by
+the vconnection reading from it. The above description is merely
+intended to give the overall idea for what a vconnection needs to do.
+
+Transformation VConnection
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A `transformation <HTTPTransformationPlugins.html#Transformations>`__ is
+a specific type of vconnection. It supports a subset of the vconnection
+functionality that enables one or more transformations to be chained
+together. A transformation sits as a bottleneck between an input data
+source and an output data sink, which enables it to view and modify all
+the data passing through it. Alternatively, some transformations simply
+scan the data and pass it on. A common transformation is one that
+compresses data in some manner.
+
+A transformation can modify either the data stream being sent *to* an
+HTTP client (e.g. the document) or the data stream being sent *from* an
+HTTP client (e.g. post data). To do this, the transformation should hook
+on to one of the following hooks:
+
+-  ``TS_HTTP_REQUEST_TRANSFORM_HOOK``
+
+-  ``TS_HTTP_RESPONSE_TRANSFORM_HOOK``
+
+Note that because a transformation is intimately associated with a given
+transaction, it is only possible to add the hook to the transaction
+hooks - not to the global or session hooks. Transformations reside in a
+chain, so their ordering is quite easily determined: transformations
+that add themselves to the chain are simply appended to it.
+
+Data is passed in to the transformation by initiating a vconnection
+write operation on the transformation. As a consequence of this design,
+a transformation must support the vconnection write operation. In other
+words, your transformation must expect an upstream vconnection to write
+data to it. The transformation has to read the data, consume it, and
+tell the upstream vconnection it is finished by sending it an
+``TS_EVENT_WRITE_COMPLETE`` event. Transformations cannot send the
+``TS_EVENT_VCONN_WRITE_COMPLETE`` event to the upstream vconnection
+unless they are finished consuming all incoming data. If
+``TS_EVENT_VCONN_WRITE_COMPLETE`` is sent prematurely, then certain
+internal Traffic Server data structures will not be deallocated, thereby
+causing a memory leak.
+
+Here's how to make sure that all incoming data is consumed:
+
+-  After reading or copying data, make sure that you consume the data
+   and increase the value of ndone for the input VIO, as in the
+   following example taken from ``null-transform.c``:
+
+   ::
+
+               :::c
+       TSIOBufferCopy (TSVIOBufferGet (data->output_vio),
+       TSVIOReaderGet (input_vio), towrite, 0);
+       /* Tell the read buffer that we have read the data and are no longer interested in it. */
+       TSIOBufferReaderConsume (TSVIOReaderGet (input_vio), towrite);
+       /* Modify the input VIO to reflect how much has been read.*/
+       TSVIONDoneSet (input_vio, TSVIONDoneGet (input_vio) + towrite);
+
+-  Before sending ``TS_EVENT_VCONN_WRITE_COMPLETE``, your transformation
+   should check the number of bytes remaining in the upstream
+   vconnection's write VIO (input VIO) using the function
+   ``TSVIONTodoGet`` (``input_vio``). This value should go to zero when
+   all of the upstream data is consumed
+   (``TSVIONTodoGet = nbytes - ndone``). Do not send
+   ``TS_EVENT_VCONN_WRITE_COMPLETE`` events if ``TSVIONTodoGet`` is
+   greater than zero.
+-  The transformation passes data out of itself by using the output
+   vconnection retrieved by ``TSTransformOutputVConnGet``. Immediately
+   before Traffic Server initiates the write operation (which inputs
+   data into the transformation), it sets the output vconnection either
+   to the next transformation in the chain of transformations or to a
+   special terminating transformation (if it's the last transformation
+   in the chain). Since the transformation is handed ownership of the
+   output vconnection, it must close it at some point in order for it to
+   be deallocated.
+-  All of the transformations in a transformation chain share the
+   transaction's mutex. This small restriction (enforced by
+   ``TSTransformCreate``) removes many of the locking complications of
+   implementing general vconnections. For example, a transformation does
+   not have to grab its write VIO mutex before accessing its write VIO
+   because it knows it already holds the mutex.
+
+The transformation functions are: \*
+```TSTransformCreate`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a54c4902bb537d3d40763bd947ed753b9>`__
+\*
+```TSTransformOutputVConnGet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ac6832718a2d9f2658409ad231811e1e3>`__

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/io-guide/vios.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/vios.en.rst b/doc/sdk/io-guide/vios.en.rst
new file mode 100644
index 0000000..48e5d12
--- /dev/null
+++ b/doc/sdk/io-guide/vios.en.rst
@@ -0,0 +1,59 @@
+VIOs
+****
+
+.. 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.
+
+A **VIO**, or **virtual IO**, is a description of an IO operation that's
+currently in progress. The VIO data structure is used by vconnection
+users to determine how much progress has been made on a particular IO
+operation and to re-enable an IO operation when it stalls due to buffer
+space issues. VIOs are used by vconnection implementors to determine the
+buffer for an IO operation, how much work to do on the IO operation, and
+which continuation to call back when progress on the IO operation is
+made.
+
+The ``TSVIO`` data structure itself is opaque, but it could be defined
+as follows:
+
+::
+
+        ::::c
+    typedef struct {
+        TSCont continuation;
+        TSVConn vconnection;
+        TSIOBufferReader reader;
+        TSMutex mutex;
+        int nbytes;
+        int ndone;
+    } *TSVIO;
+
+The VIO functions below access and modify various parts of the data
+structure.
+
+-  ```TSVIOBufferGet`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a55df75b6ba6e9152292a01e0b4e21963>`__
+-  ```TSVIOVConnGet`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a32b9eaaadf2145f98ceb4d64b7c06c2f>`__
+-  ```TSVIOContGet`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a071f12b307885c02aceebc41601bbdcf>`__
+-  ```TSVIOMutexGet`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#ab4e8c755cf230918a14a4411af8b3e63>`__
+-  ```TSVIONBytesGet`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#af6fc57adc7308864b343b6b7fd30c5ff>`__
+-  ```TSVIONBytesSet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a27594723f14891ac43da3e1368328d0e>`__
+-  ```TSVIONDoneGet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ad71156f68a119c00502ff1fd598824ab>`__
+-  ```TSVIONDoneSet`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#af4590966899039571d874e0c090042ad>`__
+-  ```TSVIONTodoGet`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a1dd145ddd60822a5f892becf7b8e8f84>`__
+-  ```TSVIOReaderGet`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a471ee1fde01fbeabce6c39944dfe9da6>`__
+-  ```TSVIOReenable`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a792ef9d6962193badad2877a81d8bcff>`__
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/misc-interface-guide.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/misc-interface-guide.en.rst b/doc/sdk/misc-interface-guide.en.rst
new file mode 100644
index 0000000..2b4675c
--- /dev/null
+++ b/doc/sdk/misc-interface-guide.en.rst
@@ -0,0 +1,60 @@
+Miscellaneous Interface 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.
+
+Most of the functions in the Traffic Server API provide an interface to
+specific code modules within Traffic Server. The miscellaneous functions
+described in this chapter provide some useful general capabilities. They
+are categorized as follows:
+
+.. toctree::
+   :maxdepth: 2
+
+   misc-interface-guide/tsfopen-family.en
+   misc-interface-guide/memory-allocation.en
+   misc-interface-guide/thread-functions.en
+
+
+The C library already provides functions such as ``printf``, ``malloc``,
+and ``fopen`` to perform these tasks. The Traffic Server API versions,
+however, overcome various C library limitations (such as portability to
+all Traffic Server-support platforms).
+
+Debugging Functions
+-------------------
+
+-  ```TSDebug`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#afccd91047cc46eb35478a751ec65c78d>`__
+   prints out a formatted statement if you are running Traffic Server in
+   debug mode.
+
+-  ```TSIsDebugTagSet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a2d3ceac855c1cde83eff5484bc952288>`__
+   checks to see if a debug tag is set. If the debug tag is set, then
+   Traffic Server prints out all debug statements associated with the
+   tag.
+
+-  ```TSError`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a19ff77fecfc3e331b03da6e358907787>`__
+   prints error messages to Traffic Server's error log
+
+-  ```TSAssert`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ad94eb4fb1f08082ea1634f169cc49c68>`__
+   enables the use of assertion in a plugin.
+
+-  ```TSReleaseAssert`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a5e751769785de91c52bd503bcbc28b0a>`__
+   enables the use of assertion in a plugin.
+
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/misc-interface-guide/memory-allocation.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/misc-interface-guide/memory-allocation.en.rst b/doc/sdk/misc-interface-guide/memory-allocation.en.rst
new file mode 100644
index 0000000..f2e2e88
--- /dev/null
+++ b/doc/sdk/misc-interface-guide/memory-allocation.en.rst
@@ -0,0 +1,46 @@
+Memory Allocation
+*****************
+
+.. 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.
+
+Traffic Server provides five routines for allocating and freeing memory.
+These routines correspond to similar routines in the C library. For
+example, ``TSrealloc`` behaves like the C library routine ``realloc``.
+
+There are two main reasons for using the routines provided by Traffic
+Server. The first is portability: the Traffic Server API routines behave
+the same on all of Traffic Server's supported platforms. For example,
+``realloc`` does not accept an argument of ``NULL`` on some platforms.
+The second reason is that the Traffic Server routines actually track the
+memory allocations by file and line number. This tracking is very
+efficient, always turned on, and quite useful when tracking down memory
+leaks.
+
+The memory allocation functions are:
+
+-  ```TSfree`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#afe7f18beddf31a80436a03a5ab7e759f>`__
+
+-  ```TSmalloc`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#af030092823148cbbc5525c4fcde9bb37>`__
+
+-  ```TSrealloc`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a3abaf3d50d82377dccd1c16bc7b631ab>`__
+
+-  ```TSstrdup`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a92c01584655c52e46a58986435e17c86>`__
+
+-  ```TSstrndup`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a11072c11fa6d8470ace2963615229146>`__
+
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/misc-interface-guide/thread-functions.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/misc-interface-guide/thread-functions.en.rst b/doc/sdk/misc-interface-guide/thread-functions.en.rst
new file mode 100644
index 0000000..65fdf3c
--- /dev/null
+++ b/doc/sdk/misc-interface-guide/thread-functions.en.rst
@@ -0,0 +1,34 @@
+Thread Functions
+****************
+
+.. 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 Traffic Server API thread functions enable you to create, destroy,
+and identify threads within Traffic Server. Multithreading enables a
+single program to have more than one stream of execution and to process
+more than one transaction at a time. Threads serialize their access to
+shared resources and data using the ``TSMutex`` type, as described in
+`Mutexes <../mutex-guide/#Mutexes>`__.
+
+The thread functions are listed below:
+
+-  ```TSThreadCreate`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#ad087d67be30b68b6d608a5094fceed2a>`__
+-  ```TSThreadDestroy`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a600e8ad830081bdcf6caabc07b54c9e4>`__
+-  ```TSThreadInit`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a11088d9aaba362827841687864e55242>`__
+-  ```TSThreadSelf`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a5cc33c5182755e3d62b4aa55277425d9>`__
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/misc-interface-guide/tsfopen-family.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/misc-interface-guide/tsfopen-family.en.rst b/doc/sdk/misc-interface-guide/tsfopen-family.en.rst
new file mode 100644
index 0000000..0952a4b
--- /dev/null
+++ b/doc/sdk/misc-interface-guide/tsfopen-family.en.rst
@@ -0,0 +1,54 @@
+The TSfopen Family
+******************
+
+.. 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 ``fopen`` family of functions in C is normally used for reading
+configuration files, since ``fgets`` is an easy way to parse files on a
+line-by-line basis. The ``TSfopen`` family of functions aims at solving
+the same problem of buffered IO and line at a time IO in a
+platform-independent manner. The ``fopen`` family of C library functions
+can only open a file if a file descriptor less than 256 is available.
+Since Traffic Server often has more than 2000 file descriptors open at
+once, however, the likelihood of an available file descriptor less than
+256 very small. To solve this problem, the ``TSfopen`` family can open
+files with descriptors greater than 256.
+
+The ``TSfopen`` family of routines is not intended for high speed IO or
+flexibility - they are blocking APIs (not asynchronous). For performance
+reasons, you should not directly use these APIs on a Traffic Server
+thread (when being called back on an HTTP hook); it is better to use a
+separate thread for doing the blocking IO. The ``TSfopen`` family is
+intended for reading and writing configuration information when
+corresponding usage of the ``fopen`` family of functions is
+inappropriate due to file descriptor and portability limitations. The
+``TSfopen`` family of functions consists of the following:
+
+-  ```TSfclose`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a2efebe7583752668e6136de0b47bee4f>`__
+
+-  ```TSfflush`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a3cb0cb348ed189a98577f84e0629ca9a>`__
+
+-  ```TSfgets`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a6dcc724a432a287836352b31984e0de8>`__
+
+-  ```TSfopen`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a53b0430d5b0c042bdb3d06689cf244f3>`__
+
+-  ```TSfread`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a29f83c50b52e4fcabfe2b829de5742e2>`__
+
+-  ```TSfwrite`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a596a5562db5180ea8818f7bb87336a15>`__
+
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/mutex-guide.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/mutex-guide.en.rst b/doc/sdk/mutex-guide.en.rst
new file mode 100644
index 0000000..5320754
--- /dev/null
+++ b/doc/sdk/mutex-guide.en.rst
@@ -0,0 +1,411 @@
+Mutex 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.
+
+Mutexes are used to lock shared data. This chapter explains how to use
+the mutex interface.
+
+.. toctree::
+   :maxdepth: 1
+
+Mutexes
+-------
+
+A **mutex** is the basic synchronization method used within Traffic
+Server to protect data from simultaneous access by multiple threads. A
+mutex acts as a lock that protects data in one program thread from being
+accessed by another thread.
+
+The Traffic Server API provides two functions that attempt to access and
+lock the data: ``InkMutexLockTry`` and ``TSMutexLock``.
+**``TSMutexLock``** is a blocking call - if you use it, you can slow
+Traffic Server performance because transaction processing pauses until
+the mutex is unlocked. It should be used only on threads created by the
+plugin ``TSContThreadCreate``. Never use it on a continuation handler
+called back by the Cache, Net, or Event Processor. Even if the critical
+section is very small, do not use it. If you need to update a flag, then
+set a variable and/or use atomic operations. If ``TSMutexLock`` is used
+in any case other than the one recommended above, then the result will
+be a serious performance impact.
+
+**``TSMutexLockTry``**, on the other hand, attempts to lock the mutex
+only if it is unlocked (i.e., not being used by another thread). It
+should be used in all cases other than the above mentioned
+``TSMutexLock`` case. If the ``TSMutexLockTry`` attempt fails, then you
+can schedule a future attempt (which must be at least 10 milliseconds
+later).
+
+In general, you should use ``TSMutexLockTry`` instead of
+``TSMutexLock``.
+
+-  ``InkMutexLockTry`` is required if you are tying to lock Traffic
+   Server internal or system resources (such as the network, cache,
+   event processor, HTTP state machines, and IO buffers).
+
+-  ``InkMutexLockTry`` is required if you are making any blocking calls
+   (such as network, cache, or file IO calls).
+
+-  ``TSMutexLock`` might *not* be necessary if you are not making
+   blocking calls and if you are only accessing local resources.
+
+The Traffic Server API uses the ``TSMutex`` type for a mutex. There are
+two typical uses of mutex. One use is for locking global data or data
+shared by various continuations. The other typical usage is for locking
+data associated with a continuation (i.e., data that might be accessed
+by other continuations).
+
+Locking Global Data
+~~~~~~~~~~~~~~~~~~~
+
+The ``blacklist-1.c`` sample plugin implements a mutex that locks global
+data. The blacklist plugin reads its blacklisted sites from a
+configuration file; file read operations are protected by a mutex
+created in ``TSPluginInit``. The ``blacklist-1.c`` code uses
+``TSMutexLockTry`` instead of ``InkMutexLock``. For more detailed
+information, see the
+```blacklist-1.c`` <../sample-source-code#Sample_blacklist-1.c>`__ code;
+start by looking at the
+```TSPluginInit`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a9a0b0ac9cbce9d6644f66bbe93098313>`__
+function.
+
+General guidelines for locking shared data are as follows:
+
+1. Create a mutex for the shared data with
+   ```TSMutexCreate`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#aa4300d8888c6962a44c9e827d633e433>`__.
+
+2. Whenever you need to read or modify this data, first lock it by
+   calling
+   ```TSMutexLockTry`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ac9c08451aa529851b9474e3c035f44bb>`__;
+   then read or modify the data.
+
+3. When you are done with the data, unlock it with
+   ```TSMutexUnlock`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#afbb474c217fd5b927f1f8487c45646dd>`__.
+   If you are unlocking data accessed during the processing of an HTTP
+   transaction, then you must unlock it before calling
+   ```TSHttpTxnReenable`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ac367347e02709ac809994dfb21d3288a>`__.
+
+Protecting a Continuation's Data
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You must create a mutex to protect a continuation's data if it might be
+accessed by other continuations or processes. Here's how:
+
+1. | Create a mutex for the continuation using ``TSMutexCreate``.
+   | For example:
+
+   ::
+
+               ::::c
+       TSMutex mutexp;
+       mutexp = TSMutexCreate ();
+
+2. | When you create the continuation, specify this mutex as the
+   continuation's mutex.
+   | For example:
+
+   ::
+
+               :::c
+               TSCont contp;
+       contp = TSContCreate (handler, mutexp);
+
+If any other functions want to access ``contp``'s data, then it is up to
+them to get ``contp``'s mutex (using, for example, ``TSContMutexGet``)
+to lock it. For usage, ssee the sample Protocol plugin.
+
+How to Associate a Continuation With Every HTTP Transaction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There could be several reasons why you'd want to create a continuation
+for each HTTP transaction that calls back your plugin.
+
+Some potential scenarios are listed below.
+
+-  You want to register hooks locally with the new continuation instead
+   of registering them globally to the continuation plugin.
+
+-  You want to store data specific to each HTTP transaction that you
+   might need to reuse across various hooks.
+
+-  You're using APIs (like ``TSHostLookup``) that will call back the
+   continuation with a certain event.
+
+How to Add the New Continuation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A typical way of adding the new continuation is by registering the
+plugin continuation to be called back by HTTP transactions globally when
+they reach ``TS_HTTP_TXN_START_HOOK``. Refer to the example below, which
+uses a transaction-specific continuation called ``txn_contp``.
+
+::
+
+           ::::c
+           void TSPluginInit(int argc, const char *argv[]) 
+           { 
+               /* Plugin continuation */ 
+               TSCont contp; 
+               if ((contp = TSContCreate (plugin_cont_handler, NULL)) == TS_ERROR_PTR) { 
+                   LOG_ERROR("TSContCreate"); 
+               } else { 
+                   if (TSHttpHookAdd (TS_HTTP_TXN_START_HOOK, contp) == TS_ERROR) { 
+                       LOG_ERROR("TSHttpHookAdd"); 
+                   } 
+               } 
+           }
+
+In the plugin continuation handler, create the new continuation
+``txn_contp`` and then register it to be called back at
+``TS_HTTP_TXN_CLOSE_HOOK``:
+
+::
+
+           ::::c
+           static int plugin_cont_handler(TSCont contp, TSEvent event, void *edata) 
+           { 
+               TSHttpTxn txnp = (TSHttpTxn)edata; 
+               TSCont txn_contp; 
+
+               switch (event) { 
+                   case TS_EVENT_HTTP_TXN_START: 
+                       /* Create the HTTP txn continuation */ 
+                       txn_contp = TSContCreate(txn_cont_handler, NULL); 
+
+                       /* Register txn_contp to be called back when txnp reaches TS_HTTP_TXN_CLOSE_HOOK */ 
+                       if (TSHttpTxnHookAdd (txnp, TS_HTTP_TXN_CLOSE_HOOK, txn_contp) == TS_ERROR) { 
+                           LOG_ERROR("TSHttpTxnHookAdd"); 
+                       } 
+
+                       break; 
+
+                   default: 
+                       TSAssert(!"Unexpected Event"); 
+                       break; 
+               } 
+
+               if (TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE) == TS_ERROR) { 
+                   LOG_ERROR("TSHttpTxnReenable"); 
+               } 
+
+               return 0; 
+           }
+
+Remember that the ``txn_contp`` handler must destory itself when the
+HTTP transaction is closed. If you forget to do this, then your plugin
+will have a memory leak.
+
+::
+
+           ::::c
+           static int txn_cont_handler(TSCont txn_contp, TSEvent event, void *edata) 
+           { 
+               TSHttpTxn txnp; 
+               switch (event) { 
+                   case TS_EVENT_HTTP_TXN_CLOSE: 
+                       txnp = (TSHttpTxn) edata; 
+                       TSContDestroy(txn_contp); 
+                       break; 
+
+                   default: 
+                       TSAssert(!"Unexpected Event"); 
+                       break; 
+               } 
+
+               if (TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE) == TS_ERROR) { 
+                   LOG_ERROR("TSHttpTxnReenable"); 
+               } 
+
+               return 0; 
+           }
+
+How to Store Data Specific to Each HTTP Transaction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For the example above, store the data in the ``txn_contp`` data
+structure - this means that you'll create your own data structure. Now
+suppose you want to store the state of the HTTP transaction:
+
+::
+
+           ::::c
+       typedef struct { 
+             int state; 
+         } ContData;
+
+You need to allocate the memory and initialize this structure for each
+HTTP ``txnp``. You can do that in the plugin continuation handler when
+it is called back with ``TS_EVENT_HTTP_TXN_START``
+
+::
+
+           ::::c
+           static int plugin_cont_handler(TSCont contp, TSEvent event, void *edata) 
+           { 
+               TSHttpTxn txnp = (TSHttpTxn)edata; 
+               TSCont txn_contp; 
+               ContData *contData; 
+
+               switch (event) { 
+                   case TS_EVENT_HTTP_TXN_START: 
+                       /* Create the HTTP txn continuation */ 
+                       txn_contp = TSContCreate(txn_cont_handler, NULL); 
+
+                       /* Allocate and initialize the txn_contp data */ 
+                       contData = (ContData*) TSmalloc(sizeof(ContData)); 
+                       contData->state = 0; 
+                       if (TSContDataSet(txn_contp, contData) == TS_ERROR) { 
+                           LOG_ERROR("TSContDataSet"); 
+                       } 
+
+                       /* Register txn_contp to be called back when txnp reaches TS_HTTP_TXN_CLOSE_HOOK */ 
+                       if (TSHttpTxnHookAdd (txnp, TS_HTTP_TXN_CLOSE_HOOK, txn_contp) == TS_ERROR) { 
+                           LOG_ERROR("TSHttpTxnHookAdd"); 
+                       } 
+
+                       break; 
+
+                   default: 
+                       TSAssert(!"Unexpected Event"); 
+                       break; 
+               } 
+
+               if (TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE) == TS_ERROR) { 
+                   LOG_ERROR("TSHttpTxnReenable"); 
+               } 
+
+               return 0; 
+           }
+
+For accessing this data from anywhere, use TSContDataGet:
+
+::
+
+           ::::c
+           TSCont txn_contp; 
+           ContData *contData; 
+
+           contData = TSContDataGet(txn_contp); 
+           if (contData == TS_ERROR_PTR) { 
+               LOG_ERROR("TSContDataGet"); 
+           } 
+           contData->state = 1;
+
+Remember to free this memory before destroying the continuation:
+
+::
+
+           ::::c
+           static int txn_cont_handler(TSCont txn_contp, TSEvent event, void *edata) 
+           { 
+               TSHttpTxn txnp; 
+               ContData *contData; 
+               switch (event) { 
+                   case TS_EVENT_HTTP_TXN_CLOSE: 
+                       txnp = (TSHttpTxn) edata; 
+                       contData = TSContDataGet(txn_contp); 
+                       if (contData == TS_ERROR_PTR) { 
+                           LOG_ERROR("TSContDataGet"); 
+                       } else { 
+                           TSfree(contData); 
+                       } 
+                       TSContDestroy(txn_contp); 
+                       break; 
+
+                   default: 
+                       TSAssert(!"Unexpected Event"); 
+                       break; 
+               } 
+
+               if (TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE) == TS_ERROR) { 
+                   LOG_ERROR("TSHttpTxnReenable"); 
+               } 
+
+               return 0; 
+           }
+
+Using Locks
+~~~~~~~~~~~
+
+You do not need to use locks when a continuation has registered itself
+to be called back by HTTP hooks and it only uses the HTTP APIs. In the
+example above, the continuation ``txn_contp`` has registered itself to
+be called back at HTTP hooks and it only uses the HTTP APIs. In this
+case only, it's safe to access data shared between ``txnp`` and
+``txn_contp`` without grabbing a lock. In the example above,
+``txn_contp`` is created with a ``NULL`` mutex. This works because the
+HTTP transaction ``txnp`` is the only one that will call back
+``txn_contp``, and you are guaranteed that ``txn_contp`` will be called
+back only one hook at a time. After processing is finished,
+``txn_contp`` will reenable ``txnp``.
+
+In all other cases, you should create a mutex with the continuation. In
+general, a lock is needed when you're using iocore APIs or any other API
+where ``txn_contp`` is scheduled to be called back by a processor (such
+as the cache processor, the DNS processor, etc.). This ensures that
+``txn_contp`` is called back sequentially and not simultaneously. In
+other words, you need to ensure that ``txn_contp`` will not be called
+back by both ``txnp`` and the cache processor at the same time, since
+this will result in a situation wherein you're executing two pieces of
+code in conflict.
+
+Special Case: Continuations Created for HTTP Transactions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your plugin creates a new continuation for each HTTP transaction,
+then you probably don't need to create a new mutex for it because each
+HTTP transaction (``TSHttpTxn`` object) already has its own mutex.
+
+In the example below, it's not necessary to specify a mutex for the
+continuation created in ``txn_handler``:
+
+::
+
+        ::::c
+    static void
+    txn_handler (TSHttpTxn txnp, TSCont contp) {
+        TSCont newCont;
+        ....
+            newCont = TSContCreate (newCont_handler, NULL);
+        //It's not necessary to create a new mutex for newCont.
+
+        ...
+
+            TSHttpTxnReenable (txnp, TS_EVENT_HTTP_CONTINUE);
+    }
+
+        static int
+        test_plugin (TSCont contp, TSEvent event, void *edata) {
+            TSHttpTxn txnp = (TSHttpTxn) edata;
+
+            switch (event) {
+                case TS_EVENT_HTTP_READ_REQUEST_HDR:
+                    txn_handler (txnp, contp);
+                    return 0;
+                default:
+                    break;
+            }
+            return 0;
+        }
+
+The mutex functions are listed below:
+
+-  ```TSMutexCreate`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#aa4300d8888c6962a44c9e827d633e433>`__
+-  ```TSMutexLock`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a306f9923bc9d3c0f417c185919531934>`__
+-  ```TSMutexLockTry`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ac9c08451aa529851b9474e3c035f44bb>`__
+

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/sdk/new-protocol-plugins.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/new-protocol-plugins.en.rst b/doc/sdk/new-protocol-plugins.en.rst
new file mode 100644
index 0000000..c8aa318
--- /dev/null
+++ b/doc/sdk/new-protocol-plugins.en.rst
@@ -0,0 +1,359 @@
+New Protocol Plugins
+********************
+
+.. 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: 1
+
+The new protocol APIs enable you to extend Traffic Server to be a web
+proxy for any protocol. This chapter describes new protocol APIs and the
+plugins that support new protocols. It also provides a detailed review
+of code for a sample Protocol plugin that supports a very simple
+artificial HTTP-like protocol.
+
+About the Sample Protocol
+-------------------------
+
+The sample protocol enables a client to ask a server for a file. Clients
+send requests to a specific Traffic Server port (specified in
+``plugin.config``); each request has the following structure:
+
+::
+
+    server_name file_name
+
+Using the Protocol plugin, Traffic Server can accept these requests,
+parse them, and act as a proxy cache (i.e., request the file from the
+origin server on the client's behalf and store copies of response
+messages in cache). The Protocol plugin is a state machine that flows
+through the states illustrated in the `Sample Protocol State
+Diagram <#SampleProtocolStDiag>`__. This figure illustrates the steps
+that Traffic Server and the Protocol plugin go through in order to
+support the sample protocol.
+
+In more specific terms, Traffic Server and the Protocol plugin must:
+
+-  Listen for and accept client connections (on the accept port
+   specified in ``plugin.config``)
+
+-  Read incoming client requests
+
+-  Look up the requested content in the Traffic Server cache
+
+-  Serve content from cache if the request is a cache hit (this simple
+   example does not do freshness checking)
+
+-  Open a connection to the origin server if the request is a cache miss
+   (on the server port specified in ``plugin.config``)
+
+-  Forward the request to the origin server
+
+-  Receive the origin server response
+
+-  Cache the response and send it on to the client
+
+**Sample Protocol State Diagram** {#SampleProtocolStDiag}
+
+.. figure:: /images/sdk/Protocol_state_diagram.jpg
+   :alt: Sample Protocol State Diagram
+
+   Sample Protocol State Diagram
+Protocol Plugin Structure
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To see how the Protocol plugin works, you need to understand some
+broader concepts. This section assumes you're familiar with the concepts
+of **continuation**, Traffic Server's **asynchronous event model**, and
+basic Traffic Server **plugin structure**. If you are not familiar with
+these concepts, then reference `Getting
+Started <../getting-started#GettingStarted>`__ and `How to Create
+Traffic Server Plugins <../how-to-create-trafficserver-plugins>`__
+
+Continuations in the Protocol Plugin
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Protocol plugin creates a static continuation that is an **"accept"
+state machine** - that is, a state machine whose job is to accept client
+connections on the appropriate port. When Traffic Server accepts a net
+connection from a client on that port, the accept state machine is
+activated. It then creates a new continuation: a transaction state
+machine. The accept state machine creates one transaction state machine
+for each transaction (where a **transaction** consists of a client
+request and Traffic Server's response). Each transaction state machine
+lives until the transaction completes; then it is destroyed. If the
+client's request for content is a cache miss, then a transaction state
+machine might need to open a connection to the origin server. This is
+illustrated in the `Protocol Plugin
+Overview <#ProtocolPluginOverview>`__ diagram below.
+
+**Protocol Plugin Overview** {#ProtocolPluginOverview}
+
+.. figure:: /images/sdk/protocol_sm_big.jpg
+   :alt: Protocol Plugin Overview
+
+   Protocol Plugin Overview
+The first steps for writing the Protocol plugin are now clear: in
+``TSPluginInit``, you must create a continuation that listens for net
+connections on the client port specified in ``plugin.config`` (this
+continuation is the accept state machine).
+
+Below is a summary of the continuations implemented for the Protocol
+plugin:
+
+-  An **accept state machine** that listens for client connections, and
+   then creates transaction state machines whenever Traffic Server
+   accepts a new client connection. The accept state machine lives as
+   long as Traffic Server is running.
+
+-  **Transaction state machines** that read client requests, process
+   them, and are then destroyed when the transaction is finished.
+
+Event Flow
+~~~~~~~~~~
+
+Implementing the rest of the Protocol plugin requires that you
+understand the flow of events during the course of a transaction. Unlike
+HTTP transaction plugins, this plugin must read data from network
+connections and then read/write data to the Traffic Server cache. This
+means that its continuations do not receive HTTP state machine events;
+they receive events from Traffic Server's processor subsystems. For
+example: the accept state machine is activated by an
+``TS_EVENT_NET_ACCEPT`` event from Traffic Server's Net Processor; the
+handler function for the accept state machine must therefore be able to
+handle that event.
+
+The transaction state machines are activated when the client connection
+receives incoming request data. The **Net Processor** notifies the
+transaction state machine of incoming data. The transaction state
+machine reads the data; when finished, it initiates a cache lookup of
+the requested file. When the cache lookup completes, the transaction
+state machine is activated by the Traffic Server **Cache Processor**.
+
+If the transaction state machine needs to open a connection to the
+origin server to fetch content (in the case of a cache miss), then the
+transaction state machine initiates a DNS lookup of the server name. The
+transaction state machine is activated by a DNS lookup event from the
+Traffic Server **Host Database Processor**. If the transaction must
+connect to the origin server, then the transaction state machine
+initiates a net connection and waits for an event from the Net
+Processor.
+
+**Protocol Plugin Flow of Events** {#ProtocolPluginFlow}
+
+.. figure:: /images/sdk/protocol_evt.jpg
+   :alt: Protocol Plugin Flow of Events
+
+   Protocol Plugin Flow of Events
+The flow of events is illustrated in the `Protocol Plugin Flow of
+Events <#ProtocolPluginFlow>`__ diagram above. The thin straight lines
+show Net Processor event flow, the thin dashed lines represent Host
+Database event flow, and the thick dashed lines show Cache event flow.
+
+Notice that this flow of events is independent of the Protocol plugin's
+design (i.e., whether you build **accept** or **transaction** state
+machines). Any plugin that supports network connections uses the net
+vconnection interfaces (``TSNetAccept``, ``TSNetConnect``) and thus
+receives events from the Net Processor. Any plugin that performs cache
+lookups or cache writes uses ``TSCacheRead``, ``TSCacheWrite``,
+``TSVConnRead``, and ``TSVConnWrite`` and thus receives events from the
+Cache Processor and Traffic Server event system. Similarly, any plugin
+that does DNS lookups receives events from the Host Database Processor.
+
+One Way to Implement a Transaction State Machine
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+**Transaction state machines** (**TSMs**) in the Protocol plugin must do
+the following:
+
+-  Keep track of the state of the transaction
+
+-  Handle events received (based on the state of the transaction and the
+   event received)
+
+-  Update the state of the transaction as it changes
+
+Below is one way you can implement TSMs. Details about how the Protocol
+plugin does this are provided in the next section.
+
+-  Create a data structure for transactions that contains all of the
+   state data you need to keep track of. In the Protocol plugin this is
+   a struct, ``Txn_SM``.
+
+-  When you create the TSM's continuation, initialize data of type
+   ``Txn_SM``. Initialize the data to the initial state of a transaction
+   (in this case, a net connection has just been accepted). Associate
+   this data to the TSM continuation using ``TSContDataSet``.
+
+-  Write state handler functions that handle the expected events for
+   each state.
+
+-  Write the handler for the TSM. Its job is to receive events, examine
+   the current state, and execute the appropriate state handler
+   function. In the Protocol plugin, the handler is ``main_handler``.
+   ``main_handler`` calls the state handler functions to handle each
+   state.
+
+The steps below describe the flow of execution illustrated in `"How
+Transaction State Machines are Implemented in the Protocol
+Plugin" <#ImplementTransStMachine>`__.
+
+1. The handler for the TSM, (called **``main_handler``** in the Protocol
+   plugin) receives events from the TSM.
+
+2. **``main_handler``** examines the state of the transaction-in
+   particular, it examines the current handler.
+
+3. **``main_handler``** calls the **``current_handler``** (which is one
+   of the state handler functions), and then passes the current event to
+   **``current_handler``**. In `the image
+   below <#ImplementTransStMachine>`__ below, the current handler is
+   called **``state2_handler``**.
+
+4. The **``current_handler``** handles the event and updates the data.
+   In `the image below <#ImplementTransStMachine>`__ below, the state is
+   changed from **``state2``** to **``state3``** (and the current
+   handler is changed from **``state2_handler``** to
+   **``state3_handler``**). The next time **``main_handler``** receives
+   an event, it will be processed by **``state3_handler``**.
+
+5. **``state2_handler``** arranges the next callback of the TSM.
+   Typically, it gives Traffic Server additional work to do (such as
+   writing a file to cache) so that it can progress to the next state.
+   The TSM (**``main_handler``**) then waits for the next event to
+   arrive from Traffic Server.
+
+**How Transaction State Machines are Implemented in the Protocol
+Plugin** {#ImplementTransStMachine}
+
+.. figure:: /images/sdk/txn_sm.jpg
+   :alt: How Transaction State Machines are Implemented in the Protocol
+   Plugin
+
+   How Transaction State Machines are Implemented in the Protocol Plugin
+Processing a Typical Transaction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The code is contained in the following files:
+
+-  ``Protocol.c`` and ``Protocol.h``
+
+-  ``Accept.c`` and ``Accept.h``
+
+-  ``TxnSM.c`` and ``TxnSM.h``
+
+Below is a step-by-step walk-through of the code that processes a
+typical transaction.
+
+1.  The ``TSPluginInit`` function is in the ``Protocol.c`` file. It
+    checks the validity of the ``plugin.config`` entries (there must be
+    two: a client accept port and a server port) and runs an
+    initialization routine, ``init``.
+
+2.  The **``init``** function (in ``Protocol.c``) creates the plugin's
+    log file using **``TSTextLogObjectCreate``**.
+
+3.  The **``init``** function creates the accept state machine using
+    **``AcceptCreate``**. The code for **``AcceptCreate``** is in the
+    ``Accept.c`` file.
+
+4.  The accept state machine, like the transaction state machine, keeps
+    track of its state with a data structure. This data structure,
+    **``Accept``**, is defined in the ``Accept.h`` file. State data in
+    **``AcceptCreate``** is associated with the new accept state machine
+    via **``TSContDataSet``**.
+
+5.  The **``init``** function arranges the callback of the accept state
+    machine when there is a network connection by using
+    **``TSNetAccept``**.
+
+6.  The handler for the accept state machine is **``accept_event``** in
+    the ``Accept.c`` file. When Traffic Server's Net Processor sends
+    **``TS_EVENT_NET_ACCEPT``** to the accept state machine,
+    **``accept_event``** creates a transaction state machine
+    (**``txn_sm``**) by calling **``TxnSMCreate``**. Notice that
+    **``accept_event``** creates a mutex for the transaction state
+    machine, since each transaction state machine has its own mutex.
+
+7.  The **``TxnSMCreate``** function is in the ``TxnSM.c`` file. The
+    first thing it does is initialize the transaction's data, which is
+    of type ``TxnSM`` (as defined in ``TxnSM.h``). Notice that the
+    current handler (**``q_current_handler``**) is set to
+    **``state_start``**.
+
+8.  **``TxnSMCreate``** then creates a transaction state machine using
+    **``TSContCreate``**. The handler for the transaction state machine
+    is **``main_handler``**, which is in the ``TxnSM.c`` file.
+
+9.  When **``accept_event``** receives **``TS_EVENT_NET_ACCEPT``**, it
+    calls the transaction state machine (
+    **``TSContCall (txn_sm, 0, NULL);``** ). The event passed to
+    **``main_handler``** is ``0`` (**``TS_EVENT_NONE``**).
+
+10. The first thing **``main_handler``** does is examine the current
+    **``txn_sm``** state by calling **``TSContDataGet``**. The state is
+    **``state_start``**.
+
+11. **``main_handler``** then invokes the handler for
+    **``state_start``** by using the function pointer
+    **``TxnSMHandler``** (as defined in ``TxnSM.h``).
+
+12. The **``state_start``** handler function (in the ``TxnSM.c`` file)
+    is handed an event (at this stage, the event is
+    **``TS_EVENT_NET_ACCEPT``**) and a client vconnection.
+    **``state_start``** checks to see if this client vconnection is
+    closed; if it is not, then **``state_start``** attempts to read data
+    from the client vconnection into an **``TSIOBuffer``**
+    (**``state_start``** is handling the event it receives).
+
+13. **``state_start``** changes the current handler to
+    **``state_interface_with_client``** (that is, it updates the state
+    of the transaction to the next state).
+
+14. **``state_start``** initiates a read of the client vconnection
+    (arranges for Traffic Server to send
+    **``TS_EVENT_VCONN_READ_READY``** events to the TSM) by calling
+    **``TSVConnRead``**.
+
+15. **``state_interface_with_client``** is activated by the next event
+    from Traffic Server. It checks for errors and examines the read VIO
+    for the read operation initiated by **``TSVConnRead``**.
+
+16. If the read VIO is the **``client_read_VIO``** (which we are
+    expecting at this stage in the transaction), then
+    **``state_interface_with_client``** updates the state to
+    **``state_read_request_from_client``** .
+
+17. **``state_read_request_from_client``** handles actual
+    **``TS_EVENT_READ_READY``** events and reads the client request.
+
+18. **``state_read_request_from_client``** parses the client request.
+
+19. **``state_read_request_from_client``** updates the current state to
+    the next state, **``state_handle_cache_lookup``** .
+
+20. **``state_read_request_from_client``** arranges for Traffic Server
+    to call back the TSM with the next set of events (initiating the
+    cache lookup) by calling **``TSCacheRead``**.
+
+21. When the **``TSCacheRead``** sends the TSM either
+    **``TS_EVENT_OPEN_READ``** (a cache hit) or
+    **``TS_EVENT_OPEN_READ_FAILED``** (a cache miss),
+    **``main_handler``** calls **``state_handle_cache_lookup``**.
+
+


Mime
View raw message