You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by ig...@apache.org on 2011/02/10 00:51:38 UTC
svn commit: r1069172 - in
/trafficserver/site/branches/ats-cms/content/docs/trunk: ./ sdk/io-guide/
sdk/io-guide/guide-to-cache-api/
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)
+