trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jpe...@apache.org
Subject [02/51] trafficserver git commit: Documentation reorganization
Date Tue, 03 Nov 2015 06:09:38 GMT
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/mutex-guide.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/mutex-guide.en.rst b/doc/sdk/mutex-guide.en.rst
deleted file mode 100644
index 3dcb461..0000000
--- a/doc/sdk/mutex-guide.en.rst
+++ /dev/null
@@ -1,401 +0,0 @@
-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:
-
-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 :ref:`blacklist-1.c` code;
-start by looking at the :c:func:`TSPluginInit` function.
-
-General guidelines for locking shared data are as follows:
-
-1. Create a mutex for the shared data with
-   :c:func:`TSMutexCreate`.
-
-2. Whenever you need to read or modify this data, first lock it by
-   calling
-   :c:func:`TSMutexLockTry`;
-   then read or modify the data.
-
-3. When you are done with the data, unlock it with
-   :c:func:`TSMutexUnlock`.
-   If you are unlocking data accessed during the processing of an HTTP
-   transaction, then you must unlock it before calling
-   :c:func:`TSHttpTxnReenable`.
-
-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:
-
-   .. code-block:: c
-
-       TSMutex mutexp;
-       mutexp = TSMutexCreate ();
-
-2. | When you create the continuation, specify this mutex as the
-     continuation's mutex.
-   | For example:
-
-   .. code-block:: 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``.
-
-.. code-block:: 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``:
-
-.. code-block:: 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.
-
-.. code-block:: 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:
-
-.. code-block:: 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``
-
-.. code-block:: 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:
-
-.. code-block:: 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:
-
-.. code-block:: 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``:
-
-.. code-block:: 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:
-
--  :c:func:`TSMutexCreate`
--  :c:func:`TSMutexLock`
--  :c:func:`TSMutexLockTry`
-

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
deleted file mode 100644
index f7e281b..0000000
--- a/doc/sdk/new-protocol-plugins.en.rst
+++ /dev/null
@@ -1,372 +0,0 @@
-.. _new-protocol-plugins:
-
-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:
-
-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
-:file:`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 :ref:`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 :file:`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 :file:`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:: ../static/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 :term:`continuation`, Traffic Server's **asynchronous event model**, and
-basic Traffic Server **plugin structure**. If you are not familiar with
-these concepts, then reference :ref:`Getting
-Started <sdk-getting-started>` and :doc:`How to Create
-Traffic Server Plugins <how-to-create-trafficserver-plugins.en>`
-
-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 :term:`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 :ref:`Protocol Plugin
-Overview <ProtocolPluginOverview>` diagram below.
-
-**Protocol Plugin Overview**
-
-.. _ProtocolPluginOverview:
-
-.. figure:: ../static/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 :file:`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:: ../static/images/sdk/protocol_evt.jpg
-   :alt: Protocol Plugin Flow of Events
-
-   Protocol Plugin Flow of Events
-
-The flow of events is illustrated in the :ref:`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:
-
-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 :ref:`"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 :ref:`the image
-   below <ImplementTransStMachine>` below, the current handler is
-   called ``state2_handler``.
-
-4. The ``current_handler`` handles the event and updates the data.
-   In :ref:`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:: ../static/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``.

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/plugin-configurations.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/plugin-configurations.en.rst b/doc/sdk/plugin-configurations.en.rst
deleted file mode 100644
index 2dc222a..0000000
--- a/doc/sdk/plugin-configurations.en.rst
+++ /dev/null
@@ -1,115 +0,0 @@
-Plugin Configurations
-*********************
-
-.. 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 section:
-
-.. toctree::
-   :maxdepth: 1
-
-Plugin Configurations
----------------------
-
-The ``TSConfig`` family of functions provides a mechanism for accessing
-and changing global configuration information within a plugin.
-
-The functions discussed in this section do not examine or modify Traffic
-Server configuration variables. To examine Traffic Server configuration
-and statistics variables, see :doc:`"Reading Traffic Server Settings and
-Statistics" <plugin-management/reading-trafficserver-settings-and-statistics.en>`.
-
-The ``TSConfig`` family of functions is designed to provide a fast and
-efficient mechanism for accessing and changing global configuration
-information within a plugin. Such a mechanism is simple enough to
-provide in a single-threaded program, but the translation to a
-multi-threaded program such as Traffic Server is difficult. A common
-technique is to have a single mutex protect the global configuration
-information; however, the problem with this solution is that a single
-mutex becomes a performance bottleneck very quickly.
-
-The ``TSConfig`` family of functions define an interface to storing and
-retrieving an opaque data pointer. Internally, Traffic Server maintains
-reference count information about the data pointer so that a call to
-``TSConfigSet`` will not disturb another thread using the current data
-pointer. The philosophy is that once a user has a hold of the
-configuration pointer, it is okay for it to be used even if the
-configuration changes; all that a user typically wants is a non-changing
-snapshot of the configuration. You should use ``TSConfigSet`` for all
-global data updates.
-
-Here's how the interface works:
-
-.. code-block:: c
-
-    /* Assume that you have previously defined a plugin configuration
-     * data structure named ConfigData, along with its constructor
-     * plugin_config_allocator () and its destructor 
-     * plugin_config_destructor (ConfigData *data)
-     */
-    ConfigData *plugin_config;
-
-    /* You will need to assign plugin_config a unique identifier of type
-     * unsigned int. It is important to initialize this identifier to zero
-     * (see the documentation of the  function). 
-     */
-    static unsigned int   my_id = 0;
-
-    /* You will need an TSConfig pointer to access a snapshot of the 
-     * current plugin_config. 
-     */
-    TSConfig config_ptr;
-
-    /* Initialize plugin_config. */
-    plugin_config = plugin_config_allocator();
-
-    /* Assign plugin_config an identifier using TSConfigSet. */
-    my_id = TSConfigSet (my_id, plugin_config, plugin_config_destructor);
-
-    /* Get a snapshot of the current configuration using TSConfigGet. */
-    config_ptr = TSConfigGet (my_id);
-
-    /* With an TSConfig pointer to the current configuration, you can 
-     * retrieve the configuration's current data using TSConfigDataGet. 
-     */
-    plugin_config = (ConfigData*) TSConfigDataGet (config_ptr);
-
-    /* Do something with plugin_config here. */
-
-    /* When you are done with retrieving or modifying the plugin data, you
-     * release the pointers to the data with a call to TSConfigRelease.
-     */
-    TSConfigRelease (my_id, config_ptr);
-
-    /* Any time you want to modify plugin_config, you must repeat these
-     * steps, starting with 
-     * my_id = TSConfigSet (my_id,plugin_config, plugin_config_destructor);
-     * and continuing up to TSConfigRelease. 
-     */
-
-The configuration functions are:
-
--  :c:func:`TSConfigDataGet`
-
--  :c:func:`TSConfigGet`
-
--  :c:func:`TSConfigRelease`
-
--  :c:func:`TSConfigSet`
-
-

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/plugin-management.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/plugin-management.en.rst b/doc/sdk/plugin-management.en.rst
deleted file mode 100644
index 84d587e..0000000
--- a/doc/sdk/plugin-management.en.rst
+++ /dev/null
@@ -1,28 +0,0 @@
-Plugin Management
-*****************
-
-.. 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 covers the following topics:
-
-.. toctree::
-   :maxdepth: 2
-
-   plugin-management/reading-trafficserver-settings-and-statistics.en
-   plugin-management/guide-to-the-logging-api.en
-

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/plugin-management/guide-to-the-logging-api.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/plugin-management/guide-to-the-logging-api.en.rst b/doc/sdk/plugin-management/guide-to-the-logging-api.en.rst
deleted file mode 100644
index c6c4d81..0000000
--- a/doc/sdk/plugin-management/guide-to-the-logging-api.en.rst
+++ /dev/null
@@ -1,116 +0,0 @@
-Guide to the Logging API
-************************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
-   or more contributor license agreements.  See the NOTICE file
-  distributed with this work for additional information
-  regarding copyright ownership.  The ASF licenses this file
-  to you under the Apache License, Version 2.0 (the
-  "License"); you may not use this file except in compliance
-  with the License.  You may obtain a copy of the License at
- 
-   http://www.apache.org/licenses/LICENSE-2.0
- 
-  Unless required by applicable law or agreed to in writing,
-  software distributed under the License is distributed on an
-  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-  KIND, either express or implied.  See the License for the
-  specific language governing permissions and limitations
-  under the License.
-
-The logging API enables your plugin to log entries in a custom text log
-file that you create with the call ``TSTextLogObjectCreate``. This log
-file is part of Traffic Server's logging system; by default, it is
-stored in the logging directory. Once you have created the log object,
-you can set log properties.
-
-The logging API enables you to:
-
--  Establish a custom text log for your plugin: see
-   :c:func:`TSTextLogObjectCreate`
-
--  Set the log header for your custom text log: see
-   :c:func:`TSTextLogObjectHeaderSet`
-
--  Enable or disable rolling your custom text log: see
-   :c:func:`TSTextLogObjectRollingEnabledSet`
-
--  Set the rolling interval (in seconds) for your custom text log: see
-   :c:func:`TSTextLogObjectRollingIntervalSecSet`
-
--  Set the rolling offset for your custom text log: see
-   :c:func:`TSTextLogObjectRollingOffsetHrSet`
-
--  Set the rolling size for your custom text log: see
-   :c:func:`TSTextLogObjectRollingSizeMbSet`
-
--  Write text entries to the custom text log: see
-   :c:func:`TSTextLogObjectWrite`
-
--  Flush the contents of the custom text log's write buffer to disk: see
-   :c:func:`TSTextLogObjectFlush`
-
--  Destroy custom text logs when you are done with them: see
-   :c:func:`TSTextLogObjectDestroy`
-
-The steps below show how the logging API is used in the
-``blacklist-1.c`` sample plugin. For the complete source code, see the
-:doc:`*Sample Source Code* <../sample-source-code.en>` appendix.
-
-1. A new log file is defined as a global variable.
-
-   .. code-block:: c
-
-         static TSTextLogObject log;
-
-2. In ``TSPluginInit``, a new log object is allocated:
-
-   .. code-block:: c
-
-           TSReturnCode error = TSTextLogObjectCreate("blacklist",
-                                TS_LOG_MODE_ADD_TIMESTAMP, &log);
-
-   The new log is named ``blacklist.log``. Each entry written to the log
-   will have a timestamp. The ``NULL`` argument specifies that the new
-   log does not have a log header. The error argument stores the result
-   of the log creation; if the log is created successfully, then an
-   error will be equal to ``TS_LOG_ERROR_NO_ERROR``.
-
-3. After creating the log, the plugin makes sure that the log was
-   created successfully:
-
-   .. code-block:: c
-
-       if (error != TS_SUCCESS) {
-           printf("Blacklist plugin: error %d while creating log\n", error);
-       }
-
-4. The ``blacklist-1`` plugin matches the host portion of the URL (in
-   each client request) with a list of blacklisted sites (stored in the
-   array ``sites[``]):
-
-   .. code-block:: c
-
-       for (i = 0; i < nsites; i++) { if (strncmp (host, sites[i],
-       host\_length) == 0) {
-
-   If the host matches one of the blacklisted
-   sites (such as ``sites[i]``), then the plugin writes a blacklist
-   entry to ``blacklist.log``:
-
-   .. code-block:: c
-
-       if (log) { TSTextLogObjectWrite(log, "blacklisting site: %s",
-       sites[i]);
-
-   The format of the log entry is as follows:
-
-   ::
-
-       blacklisting site: sites[i]
-
-   The log is not flushed or
-   destroyed in the ``blacklist-1`` plugin - it lives for the life of
-   the plugin.
-
-

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/plugin-management/reading-trafficserver-settings-and-statistics.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/plugin-management/reading-trafficserver-settings-and-statistics.en.rst b/doc/sdk/plugin-management/reading-trafficserver-settings-and-statistics.en.rst
deleted file mode 100644
index c275dfa..0000000
--- a/doc/sdk/plugin-management/reading-trafficserver-settings-and-statistics.en.rst
+++ /dev/null
@@ -1,55 +0,0 @@
-Reading Traffic Server Settings and Statistics
-**********************************************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
-   or more contributor license agreements.  See the NOTICE file
-   distributed with this work for additional information
-   regarding copyright ownership.  The ASF licenses this file
-   to you under the Apache License, Version 2.0 (the
-   "License"); you may not use this file except in compliance
-   with the License.  You may obtain a copy of the License at
-  
-    http://www.apache.org/licenses/LICENSE-2.0
-  
-   Unless required by applicable law or agreed to in writing,
-   software distributed under the License is distributed on an
-   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-   KIND, either express or implied.  See the License for the
-   specific language governing permissions and limitations
-   under the License.
-
-Your plugin might need to know information about Traffic Server's
-current configuration and performance. The functions described in this
-section read this information from the Traffic Server :file:`records.config`
-file. Configuration settings are stored in ``CONFIG`` variables and
-statistics are stored in ``PROCESS`` variables.
-
-.. caution::
-
-   Not all ``CONFIG`` and ``PROCESS`` variables in :file:`records.config` are
-   relevant to Traffic Server's configuration and statistics. Therefore,
-   retrieve only the :file:`records.config` variables that are documented in
-   the :doc:`Traffic Server Administrator's Guide <../../admin/index.en>`.
-
-To retrieve a variable, you need to know its type (``int``, ``counter``,
-``float``, or ``string``). Plugins store the :file:`records.config` values
-as an ``TSMgmtInt``, ``TSMgmtCounter``, ``TSMgmtFloat``, or
-``TSMgmtString``. You can look up :file:`records.config` variable types in
-the :doc:`Traffic Server Administrator's Guide <../../admin/index.en>`.
-
-Depending on the result type, you'll use ``TSMgmtIntGet``,
-``TSMgmtCounterGet``, ``TSMgmtFloatGet``, or ``TSMgmtStringGet`` to
-obtain the variable value (see the example for
-:c:func:`TSMgmtIntGet`.
-
-The ``TSMgmt*Get`` functions are:
-
--  :c:func:`TSMgmtCounterGet`
-
--  :c:func:`TSMgmtFloatGet`
-
--  :c:func:`TSMgmtIntGet`
-
--  :c:func:`TSMgmtStringGet`
-
-

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/preface.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/preface.en.rst b/doc/sdk/preface.en.rst
deleted file mode 100644
index c2c6318..0000000
--- a/doc/sdk/preface.en.rst
+++ /dev/null
@@ -1,47 +0,0 @@
-.. _sdk-preface:
-
-Preface
-********
-
-.. 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
-
-   preface/how-to-use-this-book.en
-   preface/typographical-conventions.en
-
-The *Traffic Server Software Developer's Kit* is a reference for
-creating plugins. **Plugins** are programs that add services (such as
-filtering or content transformation) or entire features (such as new
-protocol support) to Traffic Server. If you are new to writing Traffic
-Server plugins, then read the first two chapters, :ref:`sdk-getting-started`
-and :ref:`how-to-create-trafficserver-plugins`, and use the
-remaining chapters as needed. :ref:`header-based-plugin-examples` provides details about
-plugins that work on HTTP headers, while :ref:`http-transformation-plugin` explains how to write a
-plugin that transforms or scans the body of an HTTP response. If you
-want to support your own protocol on Traffic Server, then reference :ref:`new-protocol-plugins`.
-
-Audience
---------
-
-This manual is intended for programmers who want to write plugin
-programs that add services or features to Traffic Server. It assumes a
-cursory knowledge of the C programming language, Hyper-Text Transfer
-Protocol (HTTP), and Multipurpose Internet Mail Extensions (MIME).
-

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/preface/how-to-use-this-book.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/preface/how-to-use-this-book.en.rst b/doc/sdk/preface/how-to-use-this-book.en.rst
deleted file mode 100644
index 6c437fd..0000000
--- a/doc/sdk/preface/how-to-use-this-book.en.rst
+++ /dev/null
@@ -1,130 +0,0 @@
-How to Use This Book
-********************
-
-.. 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 book has the following basic components:
-
--  Introduction and overview
-
--  Tutorials about writing specific kinds of plugins: HTTP header-based
-   plugins, content transformation plugins, and protocol plugins
-
--  Guides about specific interfaces
-
--  Reference material
-
-If you're new to writing Traffic Server plugins, then read
-:doc:`../getting-started.en` and :doc:`../how-to-create-trafficserver-plugins.en`,
-and use the remaining chapters as needed. :doc:`../header-based-plugin-examples.en`
-provides details about plugins that work on HTTP headers, while
-:doc:`../http-transformation-plugin.en` explains how to write a plugin that
-transforms or scans the body of an HTTP response. :doc:`../new-protocol-plugins.en`
-provides essential information if you want to support your own protocol on
-Traffic Server.
-
-You can look up information in the following reference sections:
-
--  `Index <concept-index>`_: lists information by subject
--  `Function
-   Index <http://ci.apache.org/projects/trafficserver/trunk/doxygen/>`_:
-   Doxygen reference
--  `Type
-   Index <http://ci.apache.org/projects/trafficserver/trunk/doxygen/classes.html>`_
--  :doc:`Sample Source Code <../sample-source-code.en>`
--  `Deprecated
-   Functions <http://ci.apache.org/projects/trafficserver/trunk/doxygen/deprecated.html>`_
-
-Below is a section-by-section breakdown of this guide:
-
--  :doc:`Getting Started <../getting-started.en>`
-   How to compile and load plugins. Walks through a simple "hello
-   world" example; explains how to initialize and register plugins.
-
--  :doc:`How to Create Traffic Server
-   Plugins <../how-to-create-trafficserver-plugins.en>`
-   Basic structures that all plugins use: events, continuations, and
-   how to hook on to Traffic Server processes. Detailed explication of a
-   sample blacklisting plugin.
-
--  :doc:`Remap Plugin <../remap-plugin.en>`
-   This chapter demonstrates on a practical example how you can
-   exploit the Traffic Server remap API for your plugins.
-
--  :doc:`Header-Based Plugin Examples <../header-based-plugin-examples.en>`
-   Detailed explanation about writing plugins that work on HTTP
-   headers; discusses sample blacklisting and basic authorization
-   plugins.
-
--  :doc:`HTTP Transformation Plugins <../http-transformation-plugin.en>`
-   Detailed explanation of the null-transform example; also discusses
-   ``VConnections``, ``VIOs``, and IO buffers.
-
--  :doc:`New Protocol Plugins <../new-protocol-plugins.en>`
-   Detailed explanation of a sample protocol plugin that supports a
-   synthetic protocol. Discusses ``VConnections`` and mutexes, as well
-   as the new ``NetConnection``, DNS lookup, logging, and cache APIs.
-
-The remaining sections comprise the API function reference and are
-organized by function type:
-
--  :doc:`Miscellaneous Interface Guide <../misc-interface-guide.en>`
-   Details error-writing and tracing functions, thread functions, and
-   Traffic Server API versions of the ``malloc`` and ``fopen`` families.
-   The Traffic Server API versions overcome various C library
-   limitations.
-
--  :doc:`HTTP Hooks and Transactions <../http-hooks-and-transactions.en>`
-   Functions in this chapter hook your plugin to Traffic Server HTTP
-   processes.
-
--  :doc:`HTTP Headers <../http-headers.en>`
-   Contains instructions for implementing performance enhancements for
-   all plugins that manipulate HTTP headers. These functions examine and
-   modify HTTP headers, MIME headers, URLs, and the marshal buffers that
-   contain header information. If you are working with headers, then be
-   sure to read this chapter.
-
--  :doc:`Mutex Guide <../mutex-guide.en>`
-
--  :doc:`Continuations <../continuations.en>`
-   Continuations provide the basic callback mechanism and data
-   abstractions used in Traffic Server.
-
--  :doc:`Plugin Configurations <../plugin-configurations.en>`
-
--  :doc:`Actions Guide <../actions-guide.en>`
-   Describes how to use ``TSActions`` and the ``TSDNSLookup`` API.
-
--  :doc:`IO Guide <../io-guide.en>`
-   Describes how to use the Traffic Server IO interfaces:
-   ``TSVConnection``, ``TSVIO``, ``TSIOBuffer``, ``TSNetVConnection``,
-   the Cache API.
-
--  :doc:`Plugin Management <../plugin-management.en>`
-   These functions enable you to set up a configuration interface for
-   plugins, access installed plugin files, and set up plugin licensing.
-
--  :doc:`Adding Statistics <../adding-statistics.en>`
-   These functions add statistics to your plugin.
-
--  `Function
-   Index <http://ci.apache.org/projects/trafficserver/trunk/doxygen/>`_
-   Doxygen generated Traffic Server API Documentation
-
-

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/preface/typographical-conventions.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/preface/typographical-conventions.en.rst b/doc/sdk/preface/typographical-conventions.en.rst
deleted file mode 100644
index 3b75c04..0000000
--- a/doc/sdk/preface/typographical-conventions.en.rst
+++ /dev/null
@@ -1,36 +0,0 @@
-Typographical Conventions
-*************************
-
-.. 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 document uses the following typographic conventions:
-
-\_italics \_ or *\* bold*\ \*
-    Used to introduce terms.
-
-``monospaced face``
-    Represents C language statements, commands, file content, and
-    computer output.
-
-*``monospaced italic``*
-    Represents variables for which you should substitute a value.
-
-``...`` (ellipsis)
-    Indicates the omission of irrelevant or unimportant information.
-
-

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/remap-plugin.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/remap-plugin.en.rst b/doc/sdk/remap-plugin.en.rst
deleted file mode 100644
index 9a22cc3..0000000
--- a/doc/sdk/remap-plugin.en.rst
+++ /dev/null
@@ -1,75 +0,0 @@
-Remap Plugin
-************
-
-.. 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
-
-   remap-plugin/example-query-remap.en
-
-
-The Remap plugin provides a more flexible, dynamic way of specifying
-remap rules. It is not built on top of the Traffic Server APIs and
-exists solely for the purpose of URL remapping. The remap plugin is not
-global --it is configured on a per-remap rule basis, which enables you
-to customize how URLs are redirected based on individual rules in the
-``remap.config`` file.
-
-The Traffic Server Remap API enables a plugin to dynamically map a
-client request to a target URL. Each plugin is associated with one or
-more remap rules in ``remap.config`` (an "instance"). If a request URL
-matches a remap rule's "fromURL", then Traffic Server calls the
-plugin-defined remap function for that request.
-
-((Editor's note: additional text TBD; text in this chapter is still
-under development))
-
-Getting Started
----------------
-
-Remap Header File
-~~~~~~~~~~~~~~~~~
-
-The ``remap.h`` header file contains the Traffic Server remap API. By
-default, the header file location is: ``/usr/local/include/ts/remap.h``
-
-Required Functions
-~~~~~~~~~~~~~~~~~~
-
-A remap plugin is required to implement the following functions:
-
--  `TSRemapInit <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#af7e9b1eee1c38c6f8dcc67a65ba02c24>`_:
-   the remap initialization function, called once when the plugin is
-   loaded
-
--  `TSRemapNewInstance <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#a963de3eeed2ed7a2da483acf77dc42ca>`_:
-   a new instance is created for each rule associated with the plugin.
-   Called each time the plugin used in a remap rule (this function is
-   what processes the pparam values)
-
--  `TSRemapDoRemap <http://people.apache.org/~amc/ats/doc/html/remap_8h.html#acf73f0355c591e145398211b3c0596fe>`_:
-   the entry point used by Traffic Server to find the new URL to which
-   it remaps; called every time a request comes in
-
-Configuration
-~~~~~~~~~~~~~
-
-To associate a remap plugin with a remap rule, use the ``@plugin``
-parameter. See the Admin Guide section (?TBD?) for details on
-configuring remap plugins

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/remap-plugin/example-query-remap.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/remap-plugin/example-query-remap.en.rst b/doc/sdk/remap-plugin/example-query-remap.en.rst
deleted file mode 100644
index 9c359f4..0000000
--- a/doc/sdk/remap-plugin/example-query-remap.en.rst
+++ /dev/null
@@ -1,150 +0,0 @@
-Example: Query Remap Plugin
-***************************
-
-.. 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 sample remap plugin, ``query_remap.c``, maps client requests to a
-number of servers based on a hash of the request's URL query parameter.
-This can be useful for spreading load for a given type of request among
-backend servers, while still maintaining "stickiness" to a single server
-for similar requests. For example, a search engine may want to send
-repeated queries for the same keywords to a server that has likely
-cached the result from a prior query.
-
-Configuration of query\_remap
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The query remap plugin will allow the query parameter name to be
-specified, along with the hostnames of the servers to hash across.
-Sample ``remap.config`` rules using ``query_remap`` will look like:
-
-::
-
-    map http://www.example.com/search http://srch1.example.com/search @plugin=query_remap.so @pparam=q @pparam=srch1.example.com @pparam=srch2.example.com @pparam=srch3.example.com
-    map http://www.example.com/profiles http://prof1.example.com/profiles @plugin=query_remap.so @pparam=user_id @pparam=prof1.example.com @pparam=prof2.example.com
-
-The first ``@pparam`` specifies the query param key for which the value
-will be hashed. The remaining parameters list the hostnames of the
-servers. A request for ``http://www.example.com/search?q=apache`` will
-match the first rule. The plugin will look for the *``q``* parameter and
-hash the value '``apache``\ ' to pick from among
-``srch_[1-3]_.example.com`` to send the request.
-
-If the request does not include a *``q``* query parameter and the plugin
-decides not to modify the request, the default toURL
-'``http://srch1.example.com/search``\ ' will be used by TS.
-
-The parameters are passed to the plugin's ``tsremap_new_instance``
-function. In ``query_remap``, ``tsremap_new_instance`` creates a
-plugin-defined ``query_remap_info`` struct to store its configuration
-parameters. The ihandle, an opaque pointer that can be used to pass
-per-instance data, is set to this struct pointer and will be passed to
-the ``tsremap_remap`` function when it is triggered for a request.
-
-.. code-block:: c
-
-    typedef struct _query_remap_info {
-      char *param_name;
-      size_t param_len;
-      char **hosts;
-      int num_hosts;
-    } query_remap_info;
-        
-        
-    int tsremap_new_instance(int argc,char *argv[],ihandle *ih,char *errbuf,int errbuf_size)
-    {
-      int i;
-        
-      if (argc param_name = strdup(argv[2]);
-      qri->param_len = strlen(qri->param_name);
-      qri->num_hosts = argc - 3;
-      qri->hosts = (char**) TSmalloc(qri->num_hosts*sizeof(char*));
-        
-      for (i=0; i num_hosts; ++i) {
-        qri->hosts[i] = strdup(argv[i+3]);
-      }
-        
-      *ih = (ihandle)qri;
-      return 0;
-    }
-
-Another way remap plugins may want handle more complex configuration is
-to specify a configuration filename as a ``pparam`` and parse the
-specified file during instance initialization.
-
-Performing the Remap
-~~~~~~~~~~~~~~~~~~~~
-
-The plugin implements the ``tsremap_remap`` function, which is called
-when TS has read the client HTTP request headers and matched the request
-to a remap rule configured for the plugin. The ``TSRemapRequestInfo``
-struct contains input and output members for the remap operation.
-
-``tsremap_remap`` uses the configuration information passed via the
-``ihandle`` and checks the ``request_query`` for the configured query
-parameter. If the parameter is found, the plugin sets a ``new_host`` to
-modify the request host:
-
-.. code-block:: c
-
-    int tsremap_remap(ihandle ih, rhandle rh, TSRemapRequestInfo *rri)
-    {
-      int hostidx = -1;
-      query_remap_info *qri = (query_remap_info*)ih;
-        
-      if (!qri) {
-        TSError("[remap] NULL ihandle");
-        return 0;
-      }
-          
-      if (rri && rri->request_query && rri->request_query_size > 0) {
-        char *q, *s, *key;
-            
-        //make a copy of the query, as it is read only
-        q = (char*) TSmalloc(rri->request_query_size+1);
-        strncpy(q, rri->request_query, rri->request_query_size);
-        q[rri->request_query_size] = '\0';
-            
-        s = q;
-        //parse query parameters
-        for (key = strsep(&s, "&"); key != NULL; key = strsep(&s, "&")) {
-          char *val = strchr(key, '=');
-          if (val && (size_t)(val-key) == qri->param_len &&
-              !strncmp(key, qri->param_name, qri->param_len)) {
-            ++val;
-            //the param key matched the configured param_name
-            //hash the param value to pick a host
-            hostidx = hash_fnv32(val, strlen(val)) % (uint32_t)qri->num_hosts;
-            break;
-          }
-        }
-            
-        TSfree(q);
-            
-        if (hostidx >= 0) {
-          rri->new_host_size = strlen(qri->hosts[hostidx]);
-          if (rri->new_host_size new_host, qri->hosts[hostidx], rri->new_host_size);
-            return 1; //host has been modified
-          }
-        }
-      }
-        
-      //the request was not modified, TS will use the toURL from the remap rule
-      return 0;
-    }
-

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/sample-source-code.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/sample-source-code.en.rst b/doc/sdk/sample-source-code.en.rst
deleted file mode 100644
index d216a6a..0000000
--- a/doc/sdk/sample-source-code.en.rst
+++ /dev/null
@@ -1,307 +0,0 @@
-Sample Source Code
-******************
-
-.. 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 appendix provides several source code examples. In the online
-formats of this book, function calls are linked to their references in
-the previous chapters. The following sample plugins are provided:
-
--  `blacklist-1.c`_
-
-.. _blacklist-1.c:
-
-blacklist-1.c
--------------
-
-The sample blacklisting plugin included in the Traffic Server SDK is
-``blacklist-1.c``. This plugin checks every incoming HTTP client request
-against a list of blacklisted web sites. If the client requests a
-blacklisted site, then the plugin returns an ``Access forbidden``
-message to the client.
-
-This plugin illustrates:
-
--  An HTTP transaction extension
-
--  How to examine HTTP request headers
-
--  How to use the logging interface
-
--  How to use the plugin configuration management interface
-
-.. code-block:: c
-
-       /* blacklist-1.c:  An example program that denies client access
-        *                 to blacklisted sites. This plugin illustrates
-        *                 how to use configuration information from the
-        *                 blacklist.txt configuration file.
-        *
-        * Usage:
-        * (Solaris) : blacklist-1.so
-        *
-        *
-        */
-
-       #include <stdio.h>
-       #include <string.h>
-       #include <ts/ts.h>
-
-       #define MAX_NSITES 500
-
-       static char* sites[MAX_NSITES];
-       static int nsites;
-       static TSMutex sites_mutex;
-       static TSTextLogObject log;
-
-       static void
-       handle_dns (TSHttpTxn txnp, TSCont contp)
-       {
-           TSMBuffer bufp;
-           TSMLoc hdr_loc;
-           TSMLoc url_loc;
-           const char *host;
-           int i;
-           int host_length;
-
-           if (!TSHttpTxnClientReqGet (txnp, &bufp, &hdr_loc)) {
-               TSError ("[blacklist-1] Couldn't retrieve client request header");
-               goto done;
-           }
-
-           url_loc = TSHttpHdrUrlGet (bufp, hdr_loc);
-           if (!url_loc) {
-               TSError ("[blacklist-1] Couldn't retrieve request url");
-               TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
-               goto done;
-           }
-
-           host = TSUrlHostGet (bufp, url_loc, &host_length);
-           if (!host) {
-               TSError ("[blacklist-1] Couldn't retrieve request hostname");
-               TSHandleMLocRelease (bufp, hdr_loc, url_loc);
-               TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
-               goto done;
-           }
-
-           TSMutexLock(sites_mutex);
-
-           for (i = 0; i < nsites; i++) {
-               if (strncmp (host, sites[i], host_length) == 0) {
-                   if (log) {
-                       TSTextLogObjectWrite(log, "blacklisting site: %s", sites[i]);
-                   } else {
-                       printf ("blacklisting site: %s\n", sites[i]);
-                   }
-                   TSHttpTxnHookAdd (txnp, TS_HTTP_SEND_RESPONSE_HDR_HOOK, contp);
-                   TSHandleMLocRelease (bufp, hdr_loc, url_loc);
-                   TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
-                   TSHttpTxnReenable (txnp, TS_EVENT_HTTP_ERROR);
-                   TSMutexUnlock(sites_mutex);
-                   return;
-               }
-           }
-
-           TSMutexUnlock(sites_mutex);
-           TSHandleMLocRelease (bufp, hdr_loc, url_loc);
-           TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
-
-        done:
-           TSHttpTxnReenable (txnp, TS_EVENT_HTTP_CONTINUE);
-       }
-
-       static void
-       handle_response (TSHttpTxn txnp)
-       {
-           TSMBuffer bufp;
-           TSMLoc hdr_loc;
-           TSMLoc url_loc;
-           char *url_str;
-           char *buf;
-           int url_length;
-
-           if (!TSHttpTxnClientRespGet (txnp, &bufp, &hdr_loc)) {
-               TSError ("[blacklist-1] Couldn't retrieve client response header");
-               goto done;
-           }
-
-           TSHttpHdrStatusSet (bufp, hdr_loc, TS_HTTP_STATUS_FORBIDDEN);
-           TSHttpHdrReasonSet (bufp, hdr_loc,
-               TSHttpHdrReasonLookup (TS_HTTP_STATUS_FORBIDDEN),
-               strlen (TSHttpHdrReasonLookup (TS_HTTP_STATUS_FORBIDDEN)) );
-
-           if (!TSHttpTxnClientReqGet (txnp, &bufp, &hdr_loc)) {
-               TSError ("[blacklist-1] Couldn't retrieve client request header");
-               TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
-               goto done;
-           }
-
-           url_loc = TSHttpHdrUrlGet (bufp, hdr_loc);
-           if (!url_loc) {
-               TSError ("[blacklist-1] Couldn't retrieve request url");
-               TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
-               goto done;
-           }
-
-           buf = (char *)TSmalloc (4096);
-
-           url_str = TSUrlStringGet (bufp, url_loc, &url_length);
-           sprintf (buf, "You are forbidden from accessing \"%s\"\n", url_str);
-           TSfree (url_str);
-           TSHandleMLocRelease (bufp, hdr_loc, url_loc);
-           TSHandleMLocRelease (bufp, TS_NULL_MLOC, hdr_loc);
-
-           TSHttpTxnErrorBodySet (txnp, buf, strlen (buf), NULL);
-
-        done:
-           TSHttpTxnReenable (txnp, TS_EVENT_HTTP_CONTINUE);
-       }
-
-       static void
-       read_blacklist (void)
-       {
-           char blacklist_file[1024];
-           TSFile file;
-
-           sprintf (blacklist_file, "%s/blacklist.txt", TSPluginDirGet());
-           file = TSfopen(blacklist_file, "r");
-
-           TSMutexLock (sites_mutex);
-           nsites = 0;
-
-           if (file != NULL) {
-               char buffer[1024];
-
-               while (TSfgets (file, buffer, sizeof(buffer)-1) != NULL && nsites < MAX_NSITES) {
-                   char* eol;
-                   if ((eol = strstr(buffer, "\r\n")) != NULL) {
-                       /* To handle newlines on Windows */
-                       *eol = '\0';
-                   } else if ((eol = strchr(buffer, '\n')) != NULL) {
-                       *eol = '\0';
-                   } else {
-                       /* Not a valid line, skip it */
-                       continue;
-                  }
-                  if (sites[nsites] != NULL) {
-                       TSfree (sites[nsites]);
-                  }
-                  sites[nsites] = TSstrdup (buffer);
-                  nsites++;
-              }
-
-               TSfclose (file);
-           } else {
-              TSError ("[blacklist-1] Unable to open %s", blacklist_file);
-              TSError ("[blacklist-1] All sites will be allowed", blacklist_file);
-           }
-
-           TSMutexUnlock (sites_mutex);
-       }
-
-       static int
-       blacklist_plugin (TSCont contp, TSEvent event, void *edata)
-       {
-           TSHttpTxn txnp = (TSHttpTxn) edata;
-
-           switch (event) {
-           case TS_EVENT_HTTP_OS_DNS:
-               handle_dns (txnp, contp);
-               return 0;
-           case TS_EVENT_HTTP_SEND_RESPONSE_HDR:
-               handle_response (txnp);
-               return 0;
-           case TS_EVENT_MGMT_UPDATE:
-               read_blacklist ();
-               return 0;
-           default:
-               break;
-           }
-           return 0;
-       }
-
-       int
-       check_ts_version()
-       {
-
-          const char *ts_version = TSTrafficServerVersionGet();
-          int result = 0;
-
-          if (ts_version) {
-              int major_ts_version = 0;
-              int minor_ts_version = 0;
-              int patch_ts_version = 0;
-
-              if (sscanf(ts_version, "%d.%d.%d", &major_ts_version, &minor_ts_version, &patch_ts_version) != 3) {
-                   return 0;
-              }
-
-              /* Need at least TS 2.0 */
-              if (major_ts_version >= 2) {
-                   result = 1;
-              }
-
-          }
-
-          return result;
-       }
-
-       void
-       TSPluginInit (int argc, const char *argv[])
-       {
-           int i;
-           TSCont contp;
-           TSPluginRegistrationInfo info;
-
-           info.plugin_name = "blacklist-1";
-           info.vendor_name = "DsCompany";
-           info.support_email = "ts-api-support@DsCompany.com";
-
-           if (!TSPluginRegister(&info)) {
-               TSError ("[blacklist-1] Plugin registration failed.");
-           }
-
-           if (!check_ts_version()) {
-              TSError ("[blacklist-1] Plugin requires Traffic Server 2.0 or later");
-              return;
-           }
-
-           /* create an TSTextLogObject to log blacklisted requests to */
-           TSReturnCode error = TSTextLogObjectCreate("blacklist", TS_LOG_MODE_ADD_TIMESTAMP,
-                    &log);
-           if (error != TS_SUCCESS) {
-               printf("Blacklist plugin: error %d while creating log\n", error);
-           }
-
-           sites_mutex = TSMutexCreate ();
-
-           nsites = 0;
-           for (i = 0; i < MAX_NSITES; i++) {
-               sites[i] = NULL;
-           }
-
-           read_blacklist ();
-
-           contp = TSContCreate (blacklist_plugin, NULL);
-
-           TSHttpHookAdd (TS_HTTP_OS_DNS_HOOK, contp);
-
-           TSMgmtUpdateRegister (contp, "Super Blacklist Plugin", "blacklist.cgi");
-       }
-
-

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/skeleton
----------------------------------------------------------------------
diff --git a/doc/sdk/skeleton b/doc/sdk/skeleton
deleted file mode 100755
index 0e56f80..0000000
--- a/doc/sdk/skeleton
+++ /dev/null
@@ -1,134 +0,0 @@
-#! /usr/bin/env perl
-
-#  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 
-
-# usage: skeleton [--header=PATH ...] API ...
-# Using declarations from the given headers, generate a skeleton man page
-# for the named APIs.
-
-use 5.012;
-use warnings;
-use autodie;
-use Getopt::Long;
-
-sub slurp
-{
-  my $path = shift;
-  open(my $fh, "<", $path);
-  return do { local $/; <$fh> }
-}
-
-sub datestamp
-{
-  use POSIX qw/strftime/;
-
-  return strftime "%B %d, %Y", localtime;
-}
-
-# Extract the function declarations from an ATS header file.
-sub parse
-{
-  my $decls = [];
-
-  foreach my $header (@_) {
-    my $defs = slurp($header);
-
-    while ($defs =~ m/
-        tsapi\s+        # Start with 'tsapi'
-        ([^;\(]+)       # Capture the followinf return value
-        \s+(\w+)\s*     # Capture the word before the opening parenthesis
-        \(([^\)]+)\)    # Capture the arguments
-        .*\;/xg) {
-      chomp $1; chomp $2; chomp $3;
-      my $d ={ return => $1, name => $2, args => $3 };
-      $d->{args} =~ s/\n//g;
-      push @$decls, $d;
-    }
-  }
-
-  return $decls;
-}
-
-# Return a mandoc declaration for the given API name.
-sub define
-{
-  my $decls = shift;
-  my $name = shift;
-
-  foreach my $d (@$decls) {
-    if ($d->{name} eq $name) {
-      my @args;
-      my $mdoc;
-      @args = split(/,\s+/, $d->{args}); # split args at comma boundaries
-      @args = map { "\"$_\"" } @args; # quote each arg list element
-      $mdoc =
-          ".Ft \"" . $d->{return} . "\"\n" .
-          ".Fo " . $name . "\n" .
-          ".Fa " . join("\n.Fa ", @args) . "\n" .
-          ".Fc";
-      $mdoc =~ s/^\s+(.*)\s+$/$1/;
-      return $mdoc;
-    }
-  }
-}
-
-my @headers = ();
-my $options = GetOptions(
-  "header=s" => \@headers
-);
-
-my $decls = parse(@headers);
-#say define($decls, @ARGV);
-
-print <<EOF;
-.\\"  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 .\\"
-.Dd @{[ datestamp() ]}
-.Dt @{[ $ARGV[0] ]} 3ts TSAPI
-.Sh NAME
-.Nm @{[ join(",\n.Nm ", @ARGV) ]}
-.Nd XXX Api short description
-.Sh LIBRARY
-Apache Traffic Server plugin API
-.Sh SYNOPSIS
-.In ts/ts.h
-EOF
-
-print @{[ map { define($decls, $_) . "\n" } @ARGV ]};
-
-print <<EOF;
-.Sh DESCRIPTION
-.Sh RETURN VALUES
-.Sh EXAMPLES
-.nf
-#include <ts/ts.h>
-.fi
-.Sh SEE ALSO
-.Xr TSAPI 3ts
-EOF
-# vim: set ts=2 sw=2 et :

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/troubleshooting-tips.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/troubleshooting-tips.en.rst b/doc/sdk/troubleshooting-tips.en.rst
deleted file mode 100644
index 3a312bf..0000000
--- a/doc/sdk/troubleshooting-tips.en.rst
+++ /dev/null
@@ -1,55 +0,0 @@
-Troubleshooting Tips
-********************
-
-.. 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 appendix lists the following troubleshooting tips.
-
-.. toctree::
-   :maxdepth: 2
-
-   troubleshooting-tips/unable-to-load-plugins.en
-   troubleshooting-tips/unable-to-debug-tags.en
-   troubleshooting-tips/using-a-debugger.en
-   troubleshooting-tips/debugging-memory-leaks.en
-
-
-Unable to Compile Plugins
--------------------------
-
-The process for compiling a shared library varies with the platform
-used, so the Traffic Server API includes the :program:`tsxs` script you can use
-to create shared libraries on all supported Traffic Server platforms.
-
-Example
-~~~~~~~
-
-Assuming the sample program is stored in the file ``hello-world.c``, you
-could use the following commands to building a shared library:
-
-::
-
-        tsxs -c hello-world.c -o hello-world.so
-
-To install this plugin in your ``plugindir`` use the equivalent of sudo
-on your platform to execute:
-
-::
-
-        sudo tsxs -o hello-world.so -i
-

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/troubleshooting-tips/debugging-memory-leaks.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/troubleshooting-tips/debugging-memory-leaks.en.rst b/doc/sdk/troubleshooting-tips/debugging-memory-leaks.en.rst
deleted file mode 100644
index a2c87dc..0000000
--- a/doc/sdk/troubleshooting-tips/debugging-memory-leaks.en.rst
+++ /dev/null
@@ -1,31 +0,0 @@
-Debugging Memory Leaks
-**********************
-
-.. 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.
-
-Memory leaks in a plugin can be detected using e.g. an MRTG graph
-related to memory - you can use memory dump information. Enable
-``mem dump`` in :file:`records.config` as follows:
-
-::
-
-      CONFIG proxy.config.dump_mem_info_frequency INT <value>
-
-This causes Traffic Server to dump memory information to ``traffic.out``
-at ``<value>`` (intervals are in seconds). A zero value means that it is
-disabled.

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/troubleshooting-tips/unable-to-debug-tags.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/troubleshooting-tips/unable-to-debug-tags.en.rst b/doc/sdk/troubleshooting-tips/unable-to-debug-tags.en.rst
deleted file mode 100644
index a72d160..0000000
--- a/doc/sdk/troubleshooting-tips/unable-to-debug-tags.en.rst
+++ /dev/null
@@ -1,109 +0,0 @@
-Using Debug Tags
-****************
-
-.. 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 the API
-``void TSDebug (const char *tag, const char *format_str, ...)`` to add
-traces in your plugin. In this API:
-
--  ``tag`` is the Traffic Server parameter that enables Traffic Server
-   to print out *``format_str``*
-
--  ``...`` are variables for *``format_str``* in the standard ``printf``
-   style.
-
-Run Traffic Server with the ``-Ttag`` option. For example, if the tag is
-``my-plugin``, then the debug output goes to ``traffic.out.``\ See
-below:
-
-::
-
-       traffic_server -T"my-plugin"
-
-Set the following variables in :file:`records.config` (in the Traffic Server
-``config`` directory):
-
-::
-
-       CONFIG proxy.config.diags.debug.enabled INT 1
-       CONFIG proxy.config.diags.debug.tags STRING debug-tag-name
-
-In this case, debug output goes to ``traffic.out``.
-
-Example:
-
-.. code-block:: c
-
-       TSDebug ("my-plugin", "Starting my-plugin at %d\n", the_time);
-
-The statement ``"Starting my-plugin at <time>"`` appears whenever you
-run Traffic Server with the ``my-plugin`` tag:
-
-::
-
-       traffic_server -T"my-plugin"
-
-Other Useful Internal Debug Tags
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Embedded in the base Traffic Server code are many debug tags for
-internal debugging purposes. These can also be used to follow Traffic
-Server behavior for testing and analysis.
-
-The debug tag setting (``-T`` and ``proxy.config.diag.debug.tags``) is a
-anchored regular expression against which the tag for a specific debug
-message is matched. This means the value "http" matches debug emssages
-with the tag "http" but also "http\_seq" and "http\_trans". If you want
-multiple tags then use a pipe symbol to separate the tags. For example
-"http\_tproxy\|dns\|hostdb" will match any of the message tags
-"http\_tproxy", "dns", "hostdb", or "dns\_srv" (but not "http\_trans"
-nor "splitdns").
-
-Some of the useful HTTP debug tags are:
-
--  ``http_hdrs`` - traces all incoming and outgoing HTTP headers.
-
--  ``http_trans`` - traces actions in an HTTP transaction.
-
--  ``http_seq`` - traces the sequence of the HTTP state machine.
-
--  ``http_tproxy`` - transparency related HTTP events
-
--  ``dns`` - DNS operations
-
--  ``hostdb`` - Host name lookup
-
--  ``iocore_net`` - Socket and low level IO (very voluminous)
-
--  ``socket`` - socket operations
-
--  ``ssl`` - SSL related events
-
--  ``cache`` - Cache operations (many subtags, examine the output to
-   narrow the tag set)
-
--  ``cache_update`` - Cache updates including writes
-
--  ``cache_read`` - Cache read events.
-
--  ``dir_probe`` - Cache searches.
-
--  ``sdk`` - gives some warning concerning API usage.
-
-

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst b/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst
deleted file mode 100644
index 0d8f7f3..0000000
--- a/doc/sdk/troubleshooting-tips/unable-to-load-plugins.en.rst
+++ /dev/null
@@ -1,36 +0,0 @@
-Unable to Load 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.
-
-To load plugins, follow the steps below.
-
-1. Make sure that your plugin source code contains an ``TSPluginInit``
-   initialization function.
-
-2. Compile your plugin source code, creating a shared library.
-
-3. Add an entry to the ``plugin.config`` file for your plugin.
-
-4. Add the path to your plugin shared library to the :file:`records.config`
-   file.
-
-5. Restart Traffic Server.
-
-For detailed information about each step above, refer to
-:doc:`../getting-started/a-simple-plugin.en`.


Mime
View raw message