trafficserver-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From iga...@apache.org
Subject svn commit: r1069172 - in /trafficserver/site/branches/ats-cms/content/docs/trunk: ./ sdk/io-guide/ sdk/io-guide/guide-to-cache-api/
Date Wed, 09 Feb 2011 23:51:38 GMT
Author: igalic
Date: Wed Feb  9 23:51:37 2011
New Revision: 1069172

URL: http://svn.apache.org/viewvc?rev=1069172&view=rev
Log:
Done with IO Guide

Modified:
    trafficserver/site/branches/ats-cms/content/docs/trunk/STATUS
    trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/errors.en.mdtext
    trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/example.en.mdtext
    trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.mdtext
    trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.mdtext
    trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/index.en.mdtext
    trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/index.en.mdtext
    trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/io-buffers.en.mdtext
    trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/net-vconnections.en.mdtext
    trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/transformations.en.mdtext
    trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/vios.en.mdtext

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/STATUS
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/STATUS?rev=1069172&r1=1069171&r2=1069172&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/STATUS (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/STATUS Wed Feb  9 23:51:37 2011
@@ -63,8 +63,8 @@ http-headers  -- igalic
 mutex-guide  -- igalic
 continuations -- igalic
 plugin-configurations -- igalic
-actions-guide
-io-guide
+actions-guide -- igalic
+io-guide  -- igalic
 plugin-management
 adding-statistics
 sample-source-code --igalic

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/errors.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/errors.en.mdtext?rev=1069172&r1=1069171&r2=1069172&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/errors.en.mdtext
(original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/errors.en.mdtext
Wed Feb  9 23:51:37 2011
@@ -0,0 +1,34 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](how-to-do-a-cache-remove) - How to Do a Cache Remove
+
+Example - [Next](example)
+
+### Errors ### {#Errors}
+
+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
+

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/example.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/example.en.mdtext?rev=1069172&r1=1069171&r2=1069172&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/example.en.mdtext
(original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/example.en.mdtext
Wed Feb  9 23:51:37 2011
@@ -0,0 +1,73 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](errors) - Errors
+
+Chapter 16. Plugin Management - [Next](../../plugin-management)
+
+### Example ### {#Example}
+
+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);`
+
+

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.mdtext?rev=1069172&r1=1069171&r2=1069172&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.mdtext
(original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.mdtext
Wed Feb  9 23:51:37 2011
@@ -0,0 +1,36 @@
+Title: Apache Traffic Server™ Software Developers Kit # {#ApacheTS™SoftwareDevelopersKit}
+Notice:    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.
+
+
+[Prev](how-to-do-a-cache-write) - How to Do a Cache Write
+
+Errors - [Next](errors)
+
+### How to Do a Cache Remove ### {#HowDoaCacheRemove}
+
+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 idetified by the cache key. `TSCacheError` data indicates why the 
+remove failed.
+
+

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.mdtext?rev=1069172&r1=1069171&r2=1069172&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.mdtext
(original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.mdtext
Wed Feb  9 23:51:37 2011
@@ -0,0 +1,37 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+
+[Prev](../guide-to-cache-api) - Guide to the Cache API
+
+How to Do a Cache Remove - [Next](how-to-do-a-cache-remove)
+
+### How to Do a Cache Write ### {#HowDoaCacheWrite}
+
+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`).
+
+

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/index.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/index.en.mdtext?rev=1069172&r1=1069171&r2=1069172&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/index.en.mdtext
(original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/guide-to-cache-api/index.en.mdtext
Wed Feb  9 23:51:37 2011
@@ -0,0 +1,58 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+
+[Prev](../io-buffers) - IO Buffers
+
+How to Do a Cache Write - [Next](how-to-do-a-cache-write)
+
+## Guide to the Cache API ## {#GuideCacheAPI}
+
+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 ### {#HowDoaCacheRead}
+
+`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`). 
+

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/index.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/index.en.mdtext?rev=1069172&r1=1069171&r2=1069172&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/index.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/index.en.mdtext Wed
Feb  9 23:51:37 2011
@@ -0,0 +1,180 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](../actions-guide/hosts-lookup-api) - Hosts Lookup API
+
+Net Vconnections - [Next](net-vconnections)
+
+##  IO Guide ## {#IOGuide}
+
+This chapter contains the following sections:
+
+* [Vconnections](#Vconnections)
+* [Net Vconnections](net-vconnections)
+* [Transformations](transformations)
+* [VIOs](../http-transformation-plugin#VIOs)
+* [IO Buffers](../http-transformation-plugin#IOBuffers)
+* [Guide to the Cache API](guide-to-cache-api)
+     * [How to Do a Cache Read](guide-to-cache-api)
+     * [How to Do a Cache Write](guide-to-cache-api)
+     * [How to Do a Cache Remove](guide-to-cache-api)
+     * [Errors](guide-to-cache-api)
+     * [Example](guide-to-cache-api)
+
+## Vconnections ## {#Vconnections}
+
+### Vconnections: a User's Perspective ### {#VconnectionsaUsersPerspective}
+
+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](link/to/doxygen)
+* [TSVConnClose](link/to/doxygen)
+* [TSVConnClosedGet](link/to/doxygen)
+* [TSVConnRead](link/to/doxygen)
+* [TSVConnReadVIOGet](link/to/doxygen)
+* [TSVConnShutdown](link/to/doxygen)
+* [TSVConnWrite](link/to/doxygen)
+* [TSVConnWriteVIOGet](link/to/doxygen)
+
+
+

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/io-buffers.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/io-buffers.en.mdtext?rev=1069172&r1=1069171&r2=1069172&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/io-buffers.en.mdtext
(original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/io-buffers.en.mdtext
Wed Feb  9 23:51:37 2011
@@ -0,0 +1,51 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+
+[Prev](vios) - VIOs
+
+Guide to the Cache API - [Next](guide-to-cache-api)
+
+## IO Buffers ## {#IOBuffers}
+
+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`](link/to/doxygen).
+
+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`.
+

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/net-vconnections.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/net-vconnections.en.mdtext?rev=1069172&r1=1069171&r2=1069172&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/net-vconnections.en.mdtext
(original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/net-vconnections.en.mdtext
Wed Feb  9 23:51:37 2011
@@ -0,0 +1,36 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+
+[Prev](../io-guide) - IO Guide
+
+Transformations - [Next](transformations)
+
+## Net Vconnections ## {#NetVconnections}
+
+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](IOGuide.html#Vconnections) for more information 
+about the Traffic Server abstraction for doing asynchronous IO.
+
+The netvconnection functions are listed below:
+
+* [TSNetAccept](NetvconnectionFunctions.html#TSNetAccept)
+* [TSNetConnect](TSNetConnect.html)
+
+

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/transformations.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/transformations.en.mdtext?rev=1069172&r1=1069171&r2=1069172&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/transformations.en.mdtext
(original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/transformations.en.mdtext
Wed Feb  9 23:51:37 2011
@@ -0,0 +1,171 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+
+[Prev](net-vconnections) - Net Vconnections
+
+VIOs - [Next](vios)
+
+## Transformations ## {#Transformations}
+
+### The Vconnection Implementor's View ### {#VconnectionImplementorsView}
+
+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 #### {#TransformationVConnection}
+
+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](link/to/doxygen)
+* [TSTransformOutputVConnGet](link/to/doxygen)
+
+
+

Modified: trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/vios.en.mdtext
URL: http://svn.apache.org/viewvc/trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/vios.en.mdtext?rev=1069172&r1=1069171&r2=1069172&view=diff
==============================================================================
--- trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/vios.en.mdtext (original)
+++ trafficserver/site/branches/ats-cms/content/docs/trunk/sdk/io-guide/vios.en.mdtext Wed
Feb  9 23:51:37 2011
@@ -0,0 +1,58 @@
+Title: Apache Traffic Server™ Software Developers Kit
+Notice:    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.
+
+[Prev](transformations) - Transformations
+
+IO Buffers - [Next](io-buffers)
+
+## VIOs ## {#VIOs}
+
+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](link/to/doxygen)
+* [TSVIOVConnGet](link/to/doxygen)
+* [TSVIOContGet](link/to/doxygen)
+* [TSVIOMutexGet](link/to/doxygen)
+* [TSVIONBytesGet](link/to/doxygen)
+* [TSVIONBytesSet](link/to/doxygen)
+* [TSVIONDoneGet](link/to/doxygen)
+* [TSVIONDoneSet](link/to/doxygen)
+* [TSVIONTodoGet](link/to/doxygen)
+* [TSVIOReaderGet](link/to/doxygen)
+* [TSVIOReenable](link/to/doxygen)
+



Mime
View raw message