You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by jp...@apache.org on 2015/11/03 07:09:38 UTC
[02/51] trafficserver git commit: Documentation reorganization
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`.