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 2013/06/02 07:02:00 UTC
[03/26] Separate the Admin and SDK guides.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/source/sdk/http-transformation-plugin/sample-null-transformation-plugin.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/http-transformation-plugin/sample-null-transformation-plugin.en.rst b/doc/source/sdk/http-transformation-plugin/sample-null-transformation-plugin.en.rst
deleted file mode 100644
index af2b12e..0000000
--- a/doc/source/sdk/http-transformation-plugin/sample-null-transformation-plugin.en.rst
+++ /dev/null
@@ -1,231 +0,0 @@
-The Sample Null Transform 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.
-
-This section provides a step-by-step description of what the null
-transform plugin does, along with sections of code that apply. For
-context, you can find each code snippet in the complete source code.
-Some of the error checking details are left out - to give the
-description a step-by-step flow, only the highlights of the transform
-are included.
-
-Below is an overview of the null transform plugin:
-
-1. Gets a handle to HTTP transactions.
-
- ::
-
- :::c
- void
- TSPluginInit (int argc, const char *argv[]) {
- TSHttpHookAdd (TS_HTTP_READ_RESPONSE_HDR_HOOK,
- TSContCreate (transform_plugin, NULL));
-
- With this ``TSPluginInit`` routine, the plugin is called back every
- time Traffic Server reads a response header.
-
-2. Checks to see if the transaction response is transformable.
-
- ::
-
- :::c
- static int transform_plugin (TSCont contp, TSEvent event, void *edata) {
- TSHttpTxn txnp = (TSHttpTxn) edata;
- switch (event) {
- case TS_EVENT_HTTP_READ_RESPONSE_HDR:
- if (transformable (txnp)) {
- transform_add (txnp);
- }
-
- The default behavior for transformations is to cache the transformed
- content (you can also tell Traffic Server to cache untransformed
- content, if you want). Therefore, only responses received directly
- from an origin server need to be transformed. Objects served from
- cache are already transformed. To determine whether the response is
- from the origin server, the routine ``transformable`` checks the
- response header for the "200 OK" server response.
-
- ::
-
- :::c
- static int transformable (TSHttpTxn txnp)
- {
- TSMBuffer bufp;
- TSMLoc hdr_loc;
- TSHttpStatus resp_status;
- TSHttpTxnServerRespGet (txnp, &bufp, &hdr_loc);
-
- if (TS_HTTP_STATUS_OK == (resp_status =
- TSHttpHdrStatusGet (bufp, hdr_loc)) ) {
- return 1;
- } else {
- return 0;
- }
- }
-
-3. If the response is transformable, then the plugin creates a
- transformation vconnection that gets called back when the response
- data is ready to be transformed (as it is streaming from the origin
- server).
-
- ::
-
- :::c
- static void transform_add (TSHttpTxn txnp)
- {
- TSVConn connp;
- connp = TSTransformCreate (null_transform, txnp);
- TSHttpTxnHookAdd (txnp, TS_HTTP_RESPONSE_TRANSFORM_HOOK, connp);
- }
-
- The previous code fragment shows that the handler function for the
- transformation vconnection is ``null_transform``.
-
-4. Get a handle to the output vconnection (that receives data from the
- tranformation).
-
- ::
-
- :::c
- output_conn = TSTransformOutputVConnGet (con
-
-5. Get a handle to the input VIO. (See the ``handle_transform``
- function.)
-
- ::
-
- :::c
- input_vio = TSVConnWriteVIOGet (contp);
-
- This is so that the transformation can get information about the
- upstream vconnection's write operation to the input buffer.
-
-6. Initiate a write to the output vconnection of the specified number
- of bytes. When the write is initiated, the transformation expects to
- receive ``WRITE_READY``, ``WRITE_COMPLETE``, or ``ERROR`` events
- from the output vconnection. See the ``handle_transform`` function
- for the following code fragment:
-
- ::
-
- :::c
- data->output_vio = TSVConnWrite (output_conn, contp,
- data->output_reader, TSVIONBytesGet (input_vio));
-
-7. Copy data from the input buffer to the output buffer. See the
- ``handle_transform`` function for the following code fragment:
-
- ::
-
- ::::c
- TSIOBufferCopy (TSVIOBufferGet (data->output_vio),
- TSVIOReaderGet (input_vio), towrite, 0);
-
-8. Tell the input buffer that the transformation has read the data. See
- the ``handle_transform`` function for the following code fragment:
-
- ::
-
- TSIOBufferReaderConsume (TSVIOReaderGet (input_vio), towrite);
-
-9. Modify the input VIO to tell it how much data has been read
- (increase the value of ``ndone``). See the ``handle_transform``
- function for the following code fragment:
-
- ::
-
- ::::c
- TSVIONDoneSet (input_vio, TSVIONDoneGet (input_vio) + towrite);
-
-10. If there is more data left to read ( if ndone < nbytes), then the
- ``handle_transform`` function wakes up the downstream vconnection
- with a reenable and wakes up the upstream vconnection by sending it
- ``WRITE_READY``:
-
- ::
-
- :::c
- if (TSVIONTodoGet (input_vio) > 0) {
- if (towrite > 0) {
- TSVIOReenable (data->output_vio);
-
- TSContCall (TSVIOContGet (input_vio),
- TS_EVENT_VCONN_WRITE_READY, input_vio);
- }
- } else {
-
- The process of passing data through the transformation is
- illustrated in the following diagram. The downstream vconnections
- send ``WRITE_READY`` events when they need more data; when data is
- available, the upstream vconnections reenable the downstream
- vconnections. In this instance, the ``TSVIOReenable`` function sends
- ``TS_EVENT_IMMEDIATE``.
-
- **Passing Data Through a Transformation**
- {#PassingDataThroughaTransformation}
-
-.. figure:: /images/sdk/vconnection1.jpg
- :alt: Passing Data Through a Transformation
-
- Passing Data Through a Transformation
-
-11. If the ``handle_transform`` function finds there is no more data to
- read, then it sets ``nbytes`` to ``ndone`` on the output
- (downstream) VIO and wakes up the output vconnection with a
- reenable. It then triggers the end of the write operation from the
- upstream vconnection by sending the upstream vconnection a
- ``WRITE_COMPLETE`` event.
-
- ::
-
- :::c
- } else {
-
- TSVIONBytesSet (data->output_vio, TSVIONDoneGet (input_vio));
- TSVIOReenable (data->output_vio);
- TSContCall (TSVIOContGet (input_vio),
- TS_EVENT_VCONN_WRITE_COMPLETE, input_vio);
- }
-
- When the upstream vconnection receives the ``WRITE_COMPLETE`` event,
- it will probably shut down the write operation.
-
-12. Similarly, when the downstream vconnection has consumed all of the
- data, it sends the transformation a ``WRITE_COMPLETE`` event. The
- transformation handles this event with a shut down (the
- transformation shuts down the write operation to the downstream
- vconnection). See the ``null_plugin`` function for the following
- code fragment:
-
- ::
-
- :::c
- case TS_EVENT_VCONN_WRITE_COMPLETE:
- TSVConnShutdown (TSTransformOutputVConnGet (contp), 0, 1
- break;
-
- The following diagram illustrates the flow of events:
-
- **Ending the Transformation** {#EndingTransformation}
-
- .. figure:: /images/sdk/vconnection2.jpg
- :alt: Ending the Transformation
-
- Ending the Transformation
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/source/sdk/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/index.en.rst b/doc/source/sdk/index.en.rst
deleted file mode 100644
index 5ad4863..0000000
--- a/doc/source/sdk/index.en.rst
+++ /dev/null
@@ -1,63 +0,0 @@
-Apache Traffic Server Programmers Guide
-***************************************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-*In progress*
-
-**Abstract**
-
-The *Traffic Server Software Developers Kit* shows you how to create
-plugins using the Traffic Server SDK.
-
---------------
-
-This documentation is a work in progress. It was originally written for
-a previous, commercially-available version of Traffic Server that
-supported different operating systems and more functions than the
-current version. As a result, some of the sections may refer to
-functionality that no longer exists.
-
-If you find any such issues, you may want to submit a `bug or a
-patch <https://issues.apache.org/jira/secure/CreateIssue!default.jspa?pid=12310963>`__.
-Or find out how to `find bugs <>`__, `create useful bug reports <>`__ or
-`patches <>`__.
-
-.. toctree::
- :maxdepth: 2
-
- preface.en
- getting-started.en
- how-to-create-trafficserver-plugins.en
- remap-plugin.en
- header-based-plugin-examples.en
- http-transformation-plugin.en
- new-protocol-plugins.en
- http-hooks-and-transactions.en
- misc-interface-guide.en
- http-headers.en
- mutex-guide.en
- continuations.en
- plugin-configurations.en
- actions-guide.en
- io-guide.en
- plugin-management.en
- adding-statistics.en
- sample-source-code.en
- troubleshooting-tips.en
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/source/sdk/io-guide.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/io-guide.en.rst b/doc/source/sdk/io-guide.en.rst
deleted file mode 100644
index 40bf54d..0000000
--- a/doc/source/sdk/io-guide.en.rst
+++ /dev/null
@@ -1,194 +0,0 @@
-IO Guide
-********
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-This chapter contains the following sections:
-
-.. toctree::
- :maxdepth: 2
-
- io-guide/net-vconnections.en
- io-guide/transformations.en
- io-guide/vios.en
- io-guide/io-buffers.en
- io-guide/guide-to-cache-api.en
-
-
-Vconnections
-------------
-
-Vconnections: a User's Perspective
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To use a vconnection, a user must first get a handle to one. This is
-usually accomplished by having it handed to the user; the user may also
-simply issue a call that creates a vconnection (such as
-``TSNetConnect)``. In the case of transform plugins, the plugin creates
-a transformation vconnection viav ``TSTransformCreate`` and then
-accesses the output vconnection using ``TSTransformOutputVConnGet``.
-
-After getting a handle to a vconnection, the user can then issue a read
-or write call. It's important to note that not all vconnections support
-both reading and writing - as of yet, there has not been a need to query
-a vconnection about whether it can perform a read or write operation.
-That ability should be obvious from context.
-
-To issue a read or write operation, a user calls ``TSVConnRead`` or
-``TSVConnWrite``. These two operations both return ``VIO (TSVIO)``. The
-VIO describes the operation being performed and how much progress has
-been made. Transform plugins initiate output to the downstream
-vconnection by calling ``TSVConnWrite``.
-
-A vconnection read or write operation is different from a normal UNIX
-``read(2)`` or ``write(2)`` operation. Specifically, the vconnection
-operation can specify more data to be read or written than exists in the
-buffer handed to the operation. For example, it's typical to issue a
-read for ``INT64_MAX`` (9 quintillion) bytes from a network vconnection
-in order to read all the data from the network connection until the end
-of stream is reached. This contrasts with the usual UNIX fashion of
-issuing repeated calls to ``read(2)`` until one of the calls finally
-returns ``0`` to indicate the end of stream was reached (indeed, the
-underlying implementation of vconnections on UNIX still does issue those
-calls to ``read(2)``, but the interface does not expose that detail).
-
-At most, a given vconnection can have one read operation and one write
-operation being performed on it. This is restricted both by design and
-common sense: if two write operations were performed on a single
-vconnection, then the user would not be able to specify which should
-occur first and the output would occur in an intermingled fashion. Note
-that both a read operation and a write operation can happen on a single
-vconnection at the same time; the restriction is for more than one
-operation of the same type.
-
-One obvious issue is that the buffer passed to ``TSVConnRead`` and
-``TSVConnWrite`` won't be large enough - there is no reasonable way to
-make a buffer that can hold ``INT64_MAX`` (9 quintillion) bytes! The
-secret is that vconnections engage in a protocol whereby they signal to
-the user (via the continuation passed to ``TSVConnRead`` and
-``TSVConnWrite``) that they have emptied the buffers passed to them and
-are ready for more data. When this occurs, it is up to the user to add
-more data to the buffers (or wait for more data to be added) and then
-wake up the vconnection by calling ``TSVIOReenable`` on the VIO
-describing the operation. ``TSVIOReenable`` specifies that the buffer
-for the operation has been modified and that the vconnection should
-reexamine it to see if it can make further progress.
-
-The null transform plugin provides an example of how this is done. Below
-is a prototype for ``TSVConnWrite``:
-
-::
-
- ::::c
- TSVIO TSVConnWrite (TSVConn connp, TSCont contp, TSIOBufferReader readerp, int nbytes)
-
-The ``connp`` is the vconnection the user is writing to and ``contp`` is
-the "user" - i.e., the continuation that ``connp`` calls back when it
-has emptied its buffer and is ready for more data.
-
-The call made in the null transform plugin is:
-
-::
-
- :::c
- TSVConnWrite (output_conn, contp, data->output_reader, TSVIONBytesGet (input_vio));
-
-In the example above, ``contp`` is the transformation vconnection that
-is writing to the output vconnection. The number of bytes to be written
-is obtained from ``input_vio`` by ``TSVIONBytesGet``.
-
-When a vconnection calls back its user to indicate that it wants more
-data (or when some other condition has occurred), it issues a call to
-``TSContCall``. It passes the ``TSVIO`` describing the operation as the
-data parameter, and one of the values below as the event parameter.
-
-``TS_EVENT_ERROR``
- Indicates an error has occurred on the vconnection. This will happen
- for network IO if the underlying ``read(2)`` or ``write(2)`` call
- returns an error.
-
-``TS_EVENT_VCONN_READ_READY``
- The vconnection has placed data in the buffer passed to an
- ``TSVConnRead`` operation and it would like to do more IO, but the
- buffer is now full. When the user consumes the data from the buffer,
- this should re-enable the VIO so it indicates to the vconnection
- that the buffer has been modified.
-
-``TS_EVENT_VCONN_WRITE_READY``
- The vconnection has removed data from the buffer passed to an
- ``TSVConnWrite`` operation and it would like to do more IO, but the
- buffer does not have enough data in it. When placing more data in
- the buffer, the user should re-enable the VIO so it indicates to the
- vconnection that the buffer has been modified.
-
-``TS_EVENT_VCONN_READ_COMPLETE``
- The vconnection has read all the bytes specified by an
- ``TSVConnRead`` operation. The vconnection can now be used to
- initiate a new IO operation.
-
-``TS_EVENT_VCONN_WRITE_COMPLETE``
- The vconnection has written all the bytes specified by an
- ``TSVConnWrite`` operation and can now be used to initiate a new IO
- operation.
-
-``TS_EVENT_VCONN_EOS``
- An attempt was made to read past the end of the stream of bytes
- during the handling of an ``TSVConnRead`` operation. This event
- occurs when the number of bytes available for reading from a
- vconnection is less than the number of bytes the user specifies
- should be read from the vconnection in a call to ``TSVConnRead``. A
- common case where this occurs is when the user specifies that
- ``INT64_MAX`` bytes are to be read from a network connection.
-
-For example: the null transform plugin's transformation receives
-``TS_EVENT_VCONN_WRITE_READY`` and ``TS_EVENT_VCONN_WRITE_COMPLETE``
-events from the downstream vconnection as a result of the call to
-``TSVConnWrite``.
-
-After using a vconnection, the user must call ``TSVConnClose`` or
-``TSVConnAbort``. While both calls indicate that the vconnection can
-destroy itself, ``TSVConnAbort`` should be used when the connection is
-being closed abnormally. After a call to ``TSVConnClose`` or
-``TSVConnAbort``, the user will not be called back by the vconnection
-again.
-
-Sometimes it's desirable to simply close down the write portion of a
-connection while keeping the read portion open. This can be accomplished
-via the ``TSVConnShutdown`` function, which shuts down either the read
-or write portion of a vconnection. *Shutdown* means that the vconnection
-will no longer call back the user with events for the portion of the
-connection that was shut down. For example: if the user shuts down the
-write portion of a connection, then the ``TS_EVENT_VCONN_WRITE_READY``
-or ``TS_EVENT_VCONN_WRITE_COMPLETE`` events will not be produced. In the
-null transform plugin, the write operation is shut down with a call to
-``TSVConnShutdown``. To learn how vconnections are used in
-transformation plugins, see `Writing Content Transform
-Plugins <../http-transformation-plugin#WritingContentTransformPlugins>`__.
-
-The vconnection functions are listed below:
-
-- ```TSVConnAbort`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a08444a9b2fee637672e177ede78b6218>`__
-- ```TSVConnClose`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a69344c2c6e57ece0990a5cee73b75215>`__
-- ```TSVConnClosedGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a441d74cd77bf5d5564048682ca83b6ec>`__
-- ```TSVConnRead`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a29674799a8deffdde3d6ae3231aba1dc>`__
-- ```TSVConnReadVIOGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#aa6f8788f062737f211c788ad5fcd2813>`__
-- ```TSVConnShutdown`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a5935b6c762b65fe87057adf94b1b00b4>`__
-- ```TSVConnWrite`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#acea65496d1fcaf01924b0210f3129e6b>`__
-- ```TSVConnWriteVIOGet`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#ae9a38dbd4866c59131a1f3b806a18aab>`__
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/source/sdk/io-guide/guide-to-cache-api.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/io-guide/guide-to-cache-api.en.rst b/doc/source/sdk/io-guide/guide-to-cache-api.en.rst
deleted file mode 100644
index ea63967..0000000
--- a/doc/source/sdk/io-guide/guide-to-cache-api.en.rst
+++ /dev/null
@@ -1,69 +0,0 @@
-Guide to the Cache API
-**********************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-.. toctree::
- :maxdepth: 2
-
- guide-to-cache-api/how-to-do-a-cache-write.en
- guide-to-cache-api/how-to-do-a-cache-remove.en
- guide-to-cache-api/errors.en
- guide-to-cache-api/example.en
-
-
-The cache API enables plugins to read, write, and remove objects in the
-Traffic Server cache. All cache APIs are keyed by an object called an
-``TSCacheKey``; cache keys are created via ``TSCacheKeyCreate``; keys
-are destroyed via ``TSCacheKeyDestroy``. Use ``TSCacheKeyDigestSet`` to
-set the hash of the cache key.
-
-Note that the cache APIs differentiate between HTTP data and plugin
-data. The cache APIs do not allow you to write HTTP docs in the cache;
-you can only write plugin-specific data (a specific type of data that
-differs from the HTTP type).
-
-**Example:**
-
-::
-
- :::c
- const unsigned char *key_name = "example key name";
-
- TSCacheKey key;
- TSCacheKeyCreate (&key);
- TSCacheKeyDigestSet (key, (unsigned char *) key_name , strlen(key_name));
- TSCacheKeyDestroy (key);
-
-How to Do a Cache Read
-~~~~~~~~~~~~~~~~~~~~~~
-
-``TSCacheRead`` does not really read - it is used for lookups (see the
-sample Protocol plugin). Possible callback events include:
-
-- ``TS_EVENT_CACHE_OPEN_READ`` - indicates the lookup was successful.
- The data passed back along with this event is a cache vconnection
- that can be used to initiate a read on this keyed data.
-
-- ``TS_EVENT_CACHE_OPEN_READ_FAILED`` - indicates the lookup was
- unsuccessful. Reasons for this event could be that another
- continuation is writing to that cache location, or the cache key
- doesn't refer to a cached resource. Data payload for this event
- indicates the possible reason the read failed (``TSCacheError``).
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/source/sdk/io-guide/guide-to-cache-api/errors.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/io-guide/guide-to-cache-api/errors.en.rst b/doc/source/sdk/io-guide/guide-to-cache-api/errors.en.rst
deleted file mode 100644
index f45866b..0000000
--- a/doc/source/sdk/io-guide/guide-to-cache-api/errors.en.rst
+++ /dev/null
@@ -1,31 +0,0 @@
-Errors
-******
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-Errors pertaining to the failure of various cache operations are
-indicated by ``TSCacheError`` (enumeration). They are as follows:
-
-- ``TS_CACHE_ERROR_NO_DOC`` - the key does not match a cached resource
-
-- ``TS_CACHE_ERROR_DOC_BUSY`` - e.g, another continuation could be
- writing to the cache location
-
-- ``TS_CACHE_ERROR_NOT_READY`` - the cache is not ready
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/source/sdk/io-guide/guide-to-cache-api/example.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/io-guide/guide-to-cache-api/example.en.rst b/doc/source/sdk/io-guide/guide-to-cache-api/example.en.rst
deleted file mode 100644
index c00dbea..0000000
--- a/doc/source/sdk/io-guide/guide-to-cache-api/example.en.rst
+++ /dev/null
@@ -1,76 +0,0 @@
-Example
-*******
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-In the example below, suppose there is a cache hit and the cache returns
-a vconnection that enables you to read the document from cache. To do
-this, you need to prepare a buffer (``cache_bufp``) to hold the
-document; meanwhile, use ``TSVConnCachedObjectSizeGet`` to find out the
-actual size of the document (``content_length``). Then, issue
-``TSVConnRead`` to read the document with the total data length required
-as ``content_length``. Assume the following data:
-
-::
-
- ::::c
- TSIOBuffer cache_bufp = TSIOBufferCreate ();
- TSIOBufferReader cache_readerp = TSIOBufferReaderAlloc (out_bufp);
- TSVConn cache_vconnp = NULL;
- TSVIO cache_vio = NULL;
- int content_length = 0;
-
-In the ``TS_CACHE_OPEN_READ`` handler:
-
-::
-
- ::::c
- cache_vconnp = (TSVConn) data;
- TSVConnCachedObjectSizeGet (cache_vconnp, &content_length);
- cache_vio = TSVConnRead (cache_vconn, contp, cache_bufp, content_length);
-
-In the ``TS_EVENT_VCONN_READ_READY`` handler:
-
-::
-
- ::::c
- (usual VCONN_READ_READY handler logic)
- int nbytes = TSVIONBytesGet (cache_vio);
- int ntodo = TSVIONTodoGet (cache_vio);
- int ndone = TSVIONDoneGet (cache_vio);
- (consume data in cache_bufp)
- TSVIOReenable (cache_vio);
-
-Do not try to get continuations or VIOs from ``TSVConn`` objects for
-cache vconnections. Also note that the following APIs can only be used
-on transformation vconnections and must not be used on cache
-vconnections or net vconnections:
-
-- ``TSVConnWriteVIOGet``
-
-- ``TSVConnReadVIOGet``
-
-- ``TSVConnClosedGet``
-
-APIs such as ``TSVConnRead``, ``TSVConnWrite``, ``TSVConnClose``,
-``TSVConnAbort``, and ``TSVConnShutdown`` can be used on any kind of
-vconnections.
-
-When you are finished:
-
-``TSCacheKeyDestroy (key);``
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/source/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.rst b/doc/source/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.rst
deleted file mode 100644
index 0edadf6..0000000
--- a/doc/source/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.rst
+++ /dev/null
@@ -1,31 +0,0 @@
-How to Do a Cache Remove
-************************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-Use ``TSCacheRemove`` to remove items from the cache. Possible callback
-events include:
-
-- ``TS_EVENT_CACHE_REMOVE`` - the item was removed. There is no data
- payload for this event.
-
-- ``TS_EVENT_CACHE_REMOVE_FAILED`` - indicates the cache was unable to
- remove the item identified by the cache key. ``TSCacheError`` data
- indicates why the remove failed.
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/source/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.rst b/doc/source/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.rst
deleted file mode 100644
index 1a9eacc..0000000
--- a/doc/source/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.rst
+++ /dev/null
@@ -1,34 +0,0 @@
-How to Do a Cache Write
-***********************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-Use ``TSCacheWrite`` to write to a cache (see the `sample Protocol
-plugin <../../new-protocol-plugins#AboutSampleProtocol>`__). Possible
-callback events include:
-
-- ``TS_EVENT_CACHE_WRITE_READ`` - indicates the lookup was successful.
- The data passed back along with this event is a cache vconnection
- that can be used to initiate a cache write.
-
-- ``TS_EVENT_CACHE_OPEN_WRITE_FAILED`` - event returned when another
- continuation is currently writing to this location in the cache. Data
- payload for this event indicates the possible reason for the write
- failing (``TSCacheError``).
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/source/sdk/io-guide/io-buffers.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/io-guide/io-buffers.en.rst b/doc/source/sdk/io-guide/io-buffers.en.rst
deleted file mode 100644
index 8c4cc40..0000000
--- a/doc/source/sdk/io-guide/io-buffers.en.rst
+++ /dev/null
@@ -1,52 +0,0 @@
-IO Buffers
-**********
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-The IO buffer data structure is the building block of the vconnection
-abstraction. An **IO buffer** (``TSIOBuffer``) is composed of a list of
-buffer blocks that point to buffer data. Both the buffer block
-(``TSIOBufferBlock``) and buffer data (``TSIOBufferData``) data
-structures are reference-counted, so they can reside in multiple buffers
-at the same time. This makes it extremely efficient to copy data from
-one IO buffer to another via ``TSIOBufferCopy``, since Traffic Server
-must only copy pointers and adjust reference counts appropriately (and
-doesn't actually copy any data).
-
-The IO buffer abstraction provides for a single writer and multiple
-readers. In order for the readers to have no knowledge of each other,
-they manipulate IO buffers through the ``TSIOBufferReader`` data
-structure. Since only a single writer is allowed, there is no
-corresponding ``TSIOBufferWriter`` data structure. The writer simply
-modifies the IO buffer directly. To see an example that illustrates how
-to use IOBuffers, refer to the sample code in the description of
-```TSIOBufferBlockReadStart`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a367203e6e2cf4349e019952782deb96c>`__.
-
-Additional information about IO buffer functions:
-
-- The ``TSIOBufferReader`` data structure tracks how much data in
- ``TSIOBuffer`` has been read. It has an offset number of bytes that
- is the current start point of a particular buffer reader (for every
- read operation on an ``TSIOBuffer``, you must allocate an
- ``TSIOBufferReader``).
-
-- Bytes that have already been read may not necessarily be freed within
- the ``TSIOBuffer``. To consume bytes that have been read, you must
- call ``TSIOBufferConsume``.
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/source/sdk/io-guide/net-vconnections.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/io-guide/net-vconnections.en.rst b/doc/source/sdk/io-guide/net-vconnections.en.rst
deleted file mode 100644
index 1dfe8a2..0000000
--- a/doc/source/sdk/io-guide/net-vconnections.en.rst
+++ /dev/null
@@ -1,31 +0,0 @@
-Net Vconnections
-****************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-A **network** **vconnection** (or*\* netvconnection*\ \*) is a wrapper
-around a TCP socket that enables the socket to work within the Traffic
-Server vconnection framework. See
-`vconnections <index.en.html#Vconnections>`__ for more information about
-the Traffic Server abstraction for doing asynchronous IO.
-
-The netvconnection functions are listed below:
-
-- [dox 'TSNetAccept'] in [dox "TSNetAccept" :src\_file]
-- [dox %TSNetConnect%] in [dox :src\_file]
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/source/sdk/io-guide/transformations.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/io-guide/transformations.en.rst b/doc/source/sdk/io-guide/transformations.en.rst
deleted file mode 100644
index 667e611..0000000
--- a/doc/source/sdk/io-guide/transformations.en.rst
+++ /dev/null
@@ -1,182 +0,0 @@
-Transformations
-***************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-The Vconnection Implementor's View
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A VConnection implementor writes only transformations. All other
-VConnections (net VConnections and cache VConnections) are implemented
-in iocore. As mentioned earlier, a given vconnection can have a maximum
-of one read operation and one write operation being performed on it. The
-vconnection user gets information about the operation being performed by
-examining the VIO returned by a call to ``TSVConnRead`` or
-``TSVConnWrite``. The implementor, in turn, gets a handle on the VIO
-operation by examining the VIO returned by ``TSVConnReadVIOGet`` or
-``TSVConnWriteVIOGet`` (recall that every vconnection created through
-the Traffic Server API has an associated read VIO and write VIO, even if
-it only supports reading or writing).
-
-For example, the null transform plugin's transformation examines the
-input VIO by calling:
-
-::
-
- :::c
- input_vio = TSVConnWriteVIOGet (contp);
-
-where ``contp`` is the transformation.
-
-A vconnection is a continuation. This means it has a handler function
-that is run when an event is sent to it, or more accurately, when an
-event that was sent to it is received. It is the handler function's job
-to examine the event, the current state of its read VIO and write VIO,
-and any other internal state the vconnection might have and potentially
-make some progress on the IO operations.
-
-It is common for the handler function for all vconnections to look
-similar. Their basic form looks something like the code fragment below:
-
-::
-
- ::::c
- int
- vconnection_handler (TSCont contp, TSEvent event, void *edata)
- {
- if (TSVConnClosedGet (contp)) {
- /* Destroy any vconnection specific data here. */
- TSContDestroy (contp);
- return 0;
- } else {
- /* Handle the incoming event */
- }
- }
-
-This code fragment basically shows that many vconnections simply want to
-destroy themselves when they are closed. However, the situation might
-also require the vconnection to do some cleanup processing - which is
-why ``TSVConnClose`` does not simply just destroy the vconnection.
-
-Vconnections are state machines that are animated by the events they
-receive. An event is sent to the vconnection whenever an
-``TSVConnRead``, ``TSVConnWrite``, ``TSVConnClose``,
-``TSVConnShutdown``, or ``TSVIOReenable`` call is performed.
-``TSVIOReenable`` indirectly references the vconnection through a
-back-pointer in the VIO structure to the vconnection. The vconnection
-itself only knows which call was performed by examining its state and
-the state of its VIOs. For example, when ``TSVConnClose`` is called, the
-vconnection is sent an immediate event (``TS_EVENT_IMMEDIATE``). For
-every event the vconnection receives, it needs to check its closed flag
-to see if it has been closed. Similarly, when ``TSVIOReenable`` is
-called, the vconnection is sent an immediate event. For every event the
-vconnection receives, it must check its VIOs to see if the buffers have
-been modified to a state in which it can continue processing one of its
-operations.
-
-Finally, a vconnection is likely the user of other vconnections. It also
-receives events as the user of these other vconnections. When it
-receives such an event, like ``TS_EVENT_VCONN_WRITE_READY``, it might
-just enable another vconnection that's writing into the buffer used by
-the vconnection reading from it. The above description is merely
-intended to give the overall idea for what a vconnection needs to do.
-
-Transformation VConnection
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A `transformation <HTTPTransformationPlugins.html#Transformations>`__ is
-a specific type of vconnection. It supports a subset of the vconnection
-functionality that enables one or more transformations to be chained
-together. A transformation sits as a bottleneck between an input data
-source and an output data sink, which enables it to view and modify all
-the data passing through it. Alternatively, some transformations simply
-scan the data and pass it on. A common transformation is one that
-compresses data in some manner.
-
-A transformation can modify either the data stream being sent *to* an
-HTTP client (e.g. the document) or the data stream being sent *from* an
-HTTP client (e.g. post data). To do this, the transformation should hook
-on to one of the following hooks:
-
-- ``TS_HTTP_REQUEST_TRANSFORM_HOOK``
-
-- ``TS_HTTP_RESPONSE_TRANSFORM_HOOK``
-
-Note that because a transformation is intimately associated with a given
-transaction, it is only possible to add the hook to the transaction
-hooks - not to the global or session hooks. Transformations reside in a
-chain, so their ordering is quite easily determined: transformations
-that add themselves to the chain are simply appended to it.
-
-Data is passed in to the transformation by initiating a vconnection
-write operation on the transformation. As a consequence of this design,
-a transformation must support the vconnection write operation. In other
-words, your transformation must expect an upstream vconnection to write
-data to it. The transformation has to read the data, consume it, and
-tell the upstream vconnection it is finished by sending it an
-``TS_EVENT_WRITE_COMPLETE`` event. Transformations cannot send the
-``TS_EVENT_VCONN_WRITE_COMPLETE`` event to the upstream vconnection
-unless they are finished consuming all incoming data. If
-``TS_EVENT_VCONN_WRITE_COMPLETE`` is sent prematurely, then certain
-internal Traffic Server data structures will not be deallocated, thereby
-causing a memory leak.
-
-Here's how to make sure that all incoming data is consumed:
-
-- After reading or copying data, make sure that you consume the data
- and increase the value of ndone for the input VIO, as in the
- following example taken from ``null-transform.c``:
-
- ::
-
- :::c
- TSIOBufferCopy (TSVIOBufferGet (data->output_vio),
- TSVIOReaderGet (input_vio), towrite, 0);
- /* Tell the read buffer that we have read the data and are no longer interested in it. */
- TSIOBufferReaderConsume (TSVIOReaderGet (input_vio), towrite);
- /* Modify the input VIO to reflect how much has been read.*/
- TSVIONDoneSet (input_vio, TSVIONDoneGet (input_vio) + towrite);
-
-- Before sending ``TS_EVENT_VCONN_WRITE_COMPLETE``, your transformation
- should check the number of bytes remaining in the upstream
- vconnection's write VIO (input VIO) using the function
- ``TSVIONTodoGet`` (``input_vio``). This value should go to zero when
- all of the upstream data is consumed
- (``TSVIONTodoGet = nbytes - ndone``). Do not send
- ``TS_EVENT_VCONN_WRITE_COMPLETE`` events if ``TSVIONTodoGet`` is
- greater than zero.
-- The transformation passes data out of itself by using the output
- vconnection retrieved by ``TSTransformOutputVConnGet``. Immediately
- before Traffic Server initiates the write operation (which inputs
- data into the transformation), it sets the output vconnection either
- to the next transformation in the chain of transformations or to a
- special terminating transformation (if it's the last transformation
- in the chain). Since the transformation is handed ownership of the
- output vconnection, it must close it at some point in order for it to
- be deallocated.
-- All of the transformations in a transformation chain share the
- transaction's mutex. This small restriction (enforced by
- ``TSTransformCreate``) removes many of the locking complications of
- implementing general vconnections. For example, a transformation does
- not have to grab its write VIO mutex before accessing its write VIO
- because it knows it already holds the mutex.
-
-The transformation functions are: \*
-```TSTransformCreate`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a54c4902bb537d3d40763bd947ed753b9>`__
-\*
-```TSTransformOutputVConnGet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ac6832718a2d9f2658409ad231811e1e3>`__
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/source/sdk/io-guide/vios.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/io-guide/vios.en.rst b/doc/source/sdk/io-guide/vios.en.rst
deleted file mode 100644
index 48e5d12..0000000
--- a/doc/source/sdk/io-guide/vios.en.rst
+++ /dev/null
@@ -1,59 +0,0 @@
-VIOs
-****
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-A **VIO**, or **virtual IO**, is a description of an IO operation that's
-currently in progress. The VIO data structure is used by vconnection
-users to determine how much progress has been made on a particular IO
-operation and to re-enable an IO operation when it stalls due to buffer
-space issues. VIOs are used by vconnection implementors to determine the
-buffer for an IO operation, how much work to do on the IO operation, and
-which continuation to call back when progress on the IO operation is
-made.
-
-The ``TSVIO`` data structure itself is opaque, but it could be defined
-as follows:
-
-::
-
- ::::c
- typedef struct {
- TSCont continuation;
- TSVConn vconnection;
- TSIOBufferReader reader;
- TSMutex mutex;
- int nbytes;
- int ndone;
- } *TSVIO;
-
-The VIO functions below access and modify various parts of the data
-structure.
-
-- ```TSVIOBufferGet`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a55df75b6ba6e9152292a01e0b4e21963>`__
-- ```TSVIOVConnGet`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a32b9eaaadf2145f98ceb4d64b7c06c2f>`__
-- ```TSVIOContGet`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a071f12b307885c02aceebc41601bbdcf>`__
-- ```TSVIOMutexGet`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#ab4e8c755cf230918a14a4411af8b3e63>`__
-- ```TSVIONBytesGet`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#af6fc57adc7308864b343b6b7fd30c5ff>`__
-- ```TSVIONBytesSet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a27594723f14891ac43da3e1368328d0e>`__
-- ```TSVIONDoneGet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ad71156f68a119c00502ff1fd598824ab>`__
-- ```TSVIONDoneSet`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#af4590966899039571d874e0c090042ad>`__
-- ```TSVIONTodoGet`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a1dd145ddd60822a5f892becf7b8e8f84>`__
-- ```TSVIOReaderGet`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a471ee1fde01fbeabce6c39944dfe9da6>`__
-- ```TSVIOReenable`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a792ef9d6962193badad2877a81d8bcff>`__
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/source/sdk/misc-interface-guide.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/misc-interface-guide.en.rst b/doc/source/sdk/misc-interface-guide.en.rst
deleted file mode 100644
index 2b4675c..0000000
--- a/doc/source/sdk/misc-interface-guide.en.rst
+++ /dev/null
@@ -1,60 +0,0 @@
-Miscellaneous Interface Guide
-*****************************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-Most of the functions in the Traffic Server API provide an interface to
-specific code modules within Traffic Server. The miscellaneous functions
-described in this chapter provide some useful general capabilities. They
-are categorized as follows:
-
-.. toctree::
- :maxdepth: 2
-
- misc-interface-guide/tsfopen-family.en
- misc-interface-guide/memory-allocation.en
- misc-interface-guide/thread-functions.en
-
-
-The C library already provides functions such as ``printf``, ``malloc``,
-and ``fopen`` to perform these tasks. The Traffic Server API versions,
-however, overcome various C library limitations (such as portability to
-all Traffic Server-support platforms).
-
-Debugging Functions
--------------------
-
-- ```TSDebug`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#afccd91047cc46eb35478a751ec65c78d>`__
- prints out a formatted statement if you are running Traffic Server in
- debug mode.
-
-- ```TSIsDebugTagSet`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a2d3ceac855c1cde83eff5484bc952288>`__
- checks to see if a debug tag is set. If the debug tag is set, then
- Traffic Server prints out all debug statements associated with the
- tag.
-
-- ```TSError`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a19ff77fecfc3e331b03da6e358907787>`__
- prints error messages to Traffic Server's error log
-
-- ```TSAssert`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ad94eb4fb1f08082ea1634f169cc49c68>`__
- enables the use of assertion in a plugin.
-
-- ```TSReleaseAssert`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a5e751769785de91c52bd503bcbc28b0a>`__
- enables the use of assertion in a plugin.
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/source/sdk/misc-interface-guide/memory-allocation.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/misc-interface-guide/memory-allocation.en.rst b/doc/source/sdk/misc-interface-guide/memory-allocation.en.rst
deleted file mode 100644
index f2e2e88..0000000
--- a/doc/source/sdk/misc-interface-guide/memory-allocation.en.rst
+++ /dev/null
@@ -1,46 +0,0 @@
-Memory Allocation
-*****************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-Traffic Server provides five routines for allocating and freeing memory.
-These routines correspond to similar routines in the C library. For
-example, ``TSrealloc`` behaves like the C library routine ``realloc``.
-
-There are two main reasons for using the routines provided by Traffic
-Server. The first is portability: the Traffic Server API routines behave
-the same on all of Traffic Server's supported platforms. For example,
-``realloc`` does not accept an argument of ``NULL`` on some platforms.
-The second reason is that the Traffic Server routines actually track the
-memory allocations by file and line number. This tracking is very
-efficient, always turned on, and quite useful when tracking down memory
-leaks.
-
-The memory allocation functions are:
-
-- ```TSfree`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#afe7f18beddf31a80436a03a5ab7e759f>`__
-
-- ```TSmalloc`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#af030092823148cbbc5525c4fcde9bb37>`__
-
-- ```TSrealloc`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a3abaf3d50d82377dccd1c16bc7b631ab>`__
-
-- ```TSstrdup`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a92c01584655c52e46a58986435e17c86>`__
-
-- ```TSstrndup`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a11072c11fa6d8470ace2963615229146>`__
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/source/sdk/misc-interface-guide/thread-functions.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/misc-interface-guide/thread-functions.en.rst b/doc/source/sdk/misc-interface-guide/thread-functions.en.rst
deleted file mode 100644
index 65fdf3c..0000000
--- a/doc/source/sdk/misc-interface-guide/thread-functions.en.rst
+++ /dev/null
@@ -1,34 +0,0 @@
-Thread Functions
-****************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-The Traffic Server API thread functions enable you to create, destroy,
-and identify threads within Traffic Server. Multithreading enables a
-single program to have more than one stream of execution and to process
-more than one transaction at a time. Threads serialize their access to
-shared resources and data using the ``TSMutex`` type, as described in
-`Mutexes <../mutex-guide/#Mutexes>`__.
-
-The thread functions are listed below:
-
-- ```TSThreadCreate`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#ad087d67be30b68b6d608a5094fceed2a>`__
-- ```TSThreadDestroy`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a600e8ad830081bdcf6caabc07b54c9e4>`__
-- ```TSThreadInit`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a11088d9aaba362827841687864e55242>`__
-- ```TSThreadSelf`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a5cc33c5182755e3d62b4aa55277425d9>`__
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/source/sdk/misc-interface-guide/tsfopen-family.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/misc-interface-guide/tsfopen-family.en.rst b/doc/source/sdk/misc-interface-guide/tsfopen-family.en.rst
deleted file mode 100644
index 0952a4b..0000000
--- a/doc/source/sdk/misc-interface-guide/tsfopen-family.en.rst
+++ /dev/null
@@ -1,54 +0,0 @@
-The TSfopen Family
-******************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-The ``fopen`` family of functions in C is normally used for reading
-configuration files, since ``fgets`` is an easy way to parse files on a
-line-by-line basis. The ``TSfopen`` family of functions aims at solving
-the same problem of buffered IO and line at a time IO in a
-platform-independent manner. The ``fopen`` family of C library functions
-can only open a file if a file descriptor less than 256 is available.
-Since Traffic Server often has more than 2000 file descriptors open at
-once, however, the likelihood of an available file descriptor less than
-256 very small. To solve this problem, the ``TSfopen`` family can open
-files with descriptors greater than 256.
-
-The ``TSfopen`` family of routines is not intended for high speed IO or
-flexibility - they are blocking APIs (not asynchronous). For performance
-reasons, you should not directly use these APIs on a Traffic Server
-thread (when being called back on an HTTP hook); it is better to use a
-separate thread for doing the blocking IO. The ``TSfopen`` family is
-intended for reading and writing configuration information when
-corresponding usage of the ``fopen`` family of functions is
-inappropriate due to file descriptor and portability limitations. The
-``TSfopen`` family of functions consists of the following:
-
-- ```TSfclose`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a2efebe7583752668e6136de0b47bee4f>`__
-
-- ```TSfflush`` <http://people.apache.org/~amc/ats/doc/html/InkAPI_8cc.html#a3cb0cb348ed189a98577f84e0629ca9a>`__
-
-- ```TSfgets`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a6dcc724a432a287836352b31984e0de8>`__
-
-- ```TSfopen`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a53b0430d5b0c042bdb3d06689cf244f3>`__
-
-- ```TSfread`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a29f83c50b52e4fcabfe2b829de5742e2>`__
-
-- ```TSfwrite`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a596a5562db5180ea8818f7bb87336a15>`__
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/a782694b/doc/source/sdk/mutex-guide.en.rst
----------------------------------------------------------------------
diff --git a/doc/source/sdk/mutex-guide.en.rst b/doc/source/sdk/mutex-guide.en.rst
deleted file mode 100644
index 5320754..0000000
--- a/doc/source/sdk/mutex-guide.en.rst
+++ /dev/null
@@ -1,411 +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
--------
-
-A **mutex** is the basic synchronization method used within Traffic
-Server to protect data from simultaneous access by multiple threads. A
-mutex acts as a lock that protects data in one program thread from being
-accessed by another thread.
-
-The Traffic Server API provides two functions that attempt to access and
-lock the data: ``InkMutexLockTry`` and ``TSMutexLock``.
-**``TSMutexLock``** is a blocking call - if you use it, you can slow
-Traffic Server performance because transaction processing pauses until
-the mutex is unlocked. It should be used only on threads created by the
-plugin ``TSContThreadCreate``. Never use it on a continuation handler
-called back by the Cache, Net, or Event Processor. Even if the critical
-section is very small, do not use it. If you need to update a flag, then
-set a variable and/or use atomic operations. If ``TSMutexLock`` is used
-in any case other than the one recommended above, then the result will
-be a serious performance impact.
-
-**``TSMutexLockTry``**, on the other hand, attempts to lock the mutex
-only if it is unlocked (i.e., not being used by another thread). It
-should be used in all cases other than the above mentioned
-``TSMutexLock`` case. If the ``TSMutexLockTry`` attempt fails, then you
-can schedule a future attempt (which must be at least 10 milliseconds
-later).
-
-In general, you should use ``TSMutexLockTry`` instead of
-``TSMutexLock``.
-
-- ``InkMutexLockTry`` is required if you are tying to lock Traffic
- Server internal or system resources (such as the network, cache,
- event processor, HTTP state machines, and IO buffers).
-
-- ``InkMutexLockTry`` is required if you are making any blocking calls
- (such as network, cache, or file IO calls).
-
-- ``TSMutexLock`` might *not* be necessary if you are not making
- blocking calls and if you are only accessing local resources.
-
-The Traffic Server API uses the ``TSMutex`` type for a mutex. There are
-two typical uses of mutex. One use is for locking global data or data
-shared by various continuations. The other typical usage is for locking
-data associated with a continuation (i.e., data that might be accessed
-by other continuations).
-
-Locking Global Data
-~~~~~~~~~~~~~~~~~~~
-
-The ``blacklist-1.c`` sample plugin implements a mutex that locks global
-data. The blacklist plugin reads its blacklisted sites from a
-configuration file; file read operations are protected by a mutex
-created in ``TSPluginInit``. The ``blacklist-1.c`` code uses
-``TSMutexLockTry`` instead of ``InkMutexLock``. For more detailed
-information, see the
-```blacklist-1.c`` <../sample-source-code#Sample_blacklist-1.c>`__ code;
-start by looking at the
-```TSPluginInit`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#a9a0b0ac9cbce9d6644f66bbe93098313>`__
-function.
-
-General guidelines for locking shared data are as follows:
-
-1. Create a mutex for the shared data with
- ```TSMutexCreate`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#aa4300d8888c6962a44c9e827d633e433>`__.
-
-2. Whenever you need to read or modify this data, first lock it by
- calling
- ```TSMutexLockTry`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ac9c08451aa529851b9474e3c035f44bb>`__;
- then read or modify the data.
-
-3. When you are done with the data, unlock it with
- ```TSMutexUnlock`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#afbb474c217fd5b927f1f8487c45646dd>`__.
- If you are unlocking data accessed during the processing of an HTTP
- transaction, then you must unlock it before calling
- ```TSHttpTxnReenable`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ac367347e02709ac809994dfb21d3288a>`__.
-
-Protecting a Continuation's Data
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You must create a mutex to protect a continuation's data if it might be
-accessed by other continuations or processes. Here's how:
-
-1. | Create a mutex for the continuation using ``TSMutexCreate``.
- | For example:
-
- ::
-
- ::::c
- TSMutex mutexp;
- mutexp = TSMutexCreate ();
-
-2. | When you create the continuation, specify this mutex as the
- continuation's mutex.
- | For example:
-
- ::
-
- :::c
- TSCont contp;
- contp = TSContCreate (handler, mutexp);
-
-If any other functions want to access ``contp``'s data, then it is up to
-them to get ``contp``'s mutex (using, for example, ``TSContMutexGet``)
-to lock it. For usage, ssee the sample Protocol plugin.
-
-How to Associate a Continuation With Every HTTP Transaction
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-There could be several reasons why you'd want to create a continuation
-for each HTTP transaction that calls back your plugin.
-
-Some potential scenarios are listed below.
-
-- You want to register hooks locally with the new continuation instead
- of registering them globally to the continuation plugin.
-
-- You want to store data specific to each HTTP transaction that you
- might need to reuse across various hooks.
-
-- You're using APIs (like ``TSHostLookup``) that will call back the
- continuation with a certain event.
-
-How to Add the New Continuation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A typical way of adding the new continuation is by registering the
-plugin continuation to be called back by HTTP transactions globally when
-they reach ``TS_HTTP_TXN_START_HOOK``. Refer to the example below, which
-uses a transaction-specific continuation called ``txn_contp``.
-
-::
-
- ::::c
- void TSPluginInit(int argc, const char *argv[])
- {
- /* Plugin continuation */
- TSCont contp;
- if ((contp = TSContCreate (plugin_cont_handler, NULL)) == TS_ERROR_PTR) {
- LOG_ERROR("TSContCreate");
- } else {
- if (TSHttpHookAdd (TS_HTTP_TXN_START_HOOK, contp) == TS_ERROR) {
- LOG_ERROR("TSHttpHookAdd");
- }
- }
- }
-
-In the plugin continuation handler, create the new continuation
-``txn_contp`` and then register it to be called back at
-``TS_HTTP_TXN_CLOSE_HOOK``:
-
-::
-
- ::::c
- static int plugin_cont_handler(TSCont contp, TSEvent event, void *edata)
- {
- TSHttpTxn txnp = (TSHttpTxn)edata;
- TSCont txn_contp;
-
- switch (event) {
- case TS_EVENT_HTTP_TXN_START:
- /* Create the HTTP txn continuation */
- txn_contp = TSContCreate(txn_cont_handler, NULL);
-
- /* Register txn_contp to be called back when txnp reaches TS_HTTP_TXN_CLOSE_HOOK */
- if (TSHttpTxnHookAdd (txnp, TS_HTTP_TXN_CLOSE_HOOK, txn_contp) == TS_ERROR) {
- LOG_ERROR("TSHttpTxnHookAdd");
- }
-
- break;
-
- default:
- TSAssert(!"Unexpected Event");
- break;
- }
-
- if (TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE) == TS_ERROR) {
- LOG_ERROR("TSHttpTxnReenable");
- }
-
- return 0;
- }
-
-Remember that the ``txn_contp`` handler must destory itself when the
-HTTP transaction is closed. If you forget to do this, then your plugin
-will have a memory leak.
-
-::
-
- ::::c
- static int txn_cont_handler(TSCont txn_contp, TSEvent event, void *edata)
- {
- TSHttpTxn txnp;
- switch (event) {
- case TS_EVENT_HTTP_TXN_CLOSE:
- txnp = (TSHttpTxn) edata;
- TSContDestroy(txn_contp);
- break;
-
- default:
- TSAssert(!"Unexpected Event");
- break;
- }
-
- if (TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE) == TS_ERROR) {
- LOG_ERROR("TSHttpTxnReenable");
- }
-
- return 0;
- }
-
-How to Store Data Specific to Each HTTP Transaction
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-For the example above, store the data in the ``txn_contp`` data
-structure - this means that you'll create your own data structure. Now
-suppose you want to store the state of the HTTP transaction:
-
-::
-
- ::::c
- typedef struct {
- int state;
- } ContData;
-
-You need to allocate the memory and initialize this structure for each
-HTTP ``txnp``. You can do that in the plugin continuation handler when
-it is called back with ``TS_EVENT_HTTP_TXN_START``
-
-::
-
- ::::c
- static int plugin_cont_handler(TSCont contp, TSEvent event, void *edata)
- {
- TSHttpTxn txnp = (TSHttpTxn)edata;
- TSCont txn_contp;
- ContData *contData;
-
- switch (event) {
- case TS_EVENT_HTTP_TXN_START:
- /* Create the HTTP txn continuation */
- txn_contp = TSContCreate(txn_cont_handler, NULL);
-
- /* Allocate and initialize the txn_contp data */
- contData = (ContData*) TSmalloc(sizeof(ContData));
- contData->state = 0;
- if (TSContDataSet(txn_contp, contData) == TS_ERROR) {
- LOG_ERROR("TSContDataSet");
- }
-
- /* Register txn_contp to be called back when txnp reaches TS_HTTP_TXN_CLOSE_HOOK */
- if (TSHttpTxnHookAdd (txnp, TS_HTTP_TXN_CLOSE_HOOK, txn_contp) == TS_ERROR) {
- LOG_ERROR("TSHttpTxnHookAdd");
- }
-
- break;
-
- default:
- TSAssert(!"Unexpected Event");
- break;
- }
-
- if (TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE) == TS_ERROR) {
- LOG_ERROR("TSHttpTxnReenable");
- }
-
- return 0;
- }
-
-For accessing this data from anywhere, use TSContDataGet:
-
-::
-
- ::::c
- TSCont txn_contp;
- ContData *contData;
-
- contData = TSContDataGet(txn_contp);
- if (contData == TS_ERROR_PTR) {
- LOG_ERROR("TSContDataGet");
- }
- contData->state = 1;
-
-Remember to free this memory before destroying the continuation:
-
-::
-
- ::::c
- static int txn_cont_handler(TSCont txn_contp, TSEvent event, void *edata)
- {
- TSHttpTxn txnp;
- ContData *contData;
- switch (event) {
- case TS_EVENT_HTTP_TXN_CLOSE:
- txnp = (TSHttpTxn) edata;
- contData = TSContDataGet(txn_contp);
- if (contData == TS_ERROR_PTR) {
- LOG_ERROR("TSContDataGet");
- } else {
- TSfree(contData);
- }
- TSContDestroy(txn_contp);
- break;
-
- default:
- TSAssert(!"Unexpected Event");
- break;
- }
-
- if (TSHttpTxnReenable(txnp, TS_EVENT_HTTP_CONTINUE) == TS_ERROR) {
- LOG_ERROR("TSHttpTxnReenable");
- }
-
- return 0;
- }
-
-Using Locks
-~~~~~~~~~~~
-
-You do not need to use locks when a continuation has registered itself
-to be called back by HTTP hooks and it only uses the HTTP APIs. In the
-example above, the continuation ``txn_contp`` has registered itself to
-be called back at HTTP hooks and it only uses the HTTP APIs. In this
-case only, it's safe to access data shared between ``txnp`` and
-``txn_contp`` without grabbing a lock. In the example above,
-``txn_contp`` is created with a ``NULL`` mutex. This works because the
-HTTP transaction ``txnp`` is the only one that will call back
-``txn_contp``, and you are guaranteed that ``txn_contp`` will be called
-back only one hook at a time. After processing is finished,
-``txn_contp`` will reenable ``txnp``.
-
-In all other cases, you should create a mutex with the continuation. In
-general, a lock is needed when you're using iocore APIs or any other API
-where ``txn_contp`` is scheduled to be called back by a processor (such
-as the cache processor, the DNS processor, etc.). This ensures that
-``txn_contp`` is called back sequentially and not simultaneously. In
-other words, you need to ensure that ``txn_contp`` will not be called
-back by both ``txnp`` and the cache processor at the same time, since
-this will result in a situation wherein you're executing two pieces of
-code in conflict.
-
-Special Case: Continuations Created for HTTP Transactions
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If your plugin creates a new continuation for each HTTP transaction,
-then you probably don't need to create a new mutex for it because each
-HTTP transaction (``TSHttpTxn`` object) already has its own mutex.
-
-In the example below, it's not necessary to specify a mutex for the
-continuation created in ``txn_handler``:
-
-::
-
- ::::c
- static void
- txn_handler (TSHttpTxn txnp, TSCont contp) {
- TSCont newCont;
- ....
- newCont = TSContCreate (newCont_handler, NULL);
- //It's not necessary to create a new mutex for newCont.
-
- ...
-
- TSHttpTxnReenable (txnp, TS_EVENT_HTTP_CONTINUE);
- }
-
- static int
- test_plugin (TSCont contp, TSEvent event, void *edata) {
- TSHttpTxn txnp = (TSHttpTxn) edata;
-
- switch (event) {
- case TS_EVENT_HTTP_READ_REQUEST_HDR:
- txn_handler (txnp, contp);
- return 0;
- default:
- break;
- }
- return 0;
- }
-
-The mutex functions are listed below:
-
-- ```TSMutexCreate`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#aa4300d8888c6962a44c9e827d633e433>`__
-- ```TSMutexLock`` <http://people.apache.org/~amc/ats/doc/html/InkIOCoreAPI_8cc.html#a306f9923bc9d3c0f417c185919531934>`__
-- ```TSMutexLockTry`` <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#ac9c08451aa529851b9474e3c035f44bb>`__
-