You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by zw...@apache.org on 2013/06/04 18:46:20 UTC
[26/50] [abbrv] Separate the Admin and SDK guides.
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``**.
+
+